# Roadmap Review: Recommendations & Version Plan This is a review/consulting deliverable. It organizes your near-term changes, nice-to-haves, and long-range goals into version buckets, building on `./docs/ver4.8/feature_backlog_v4_8.md` (already-scoped image work) and folding in the additional items from your original list. Versioning convention (per your direction): **4.8–4.11** are incremental feature/fix releases; **5.x and 6.x are reserved for major changes** to the app (a shared data-model overhaul, and the hosting migration, respectively). Final deliverable will be saved to `./docs` in the repo per your instruction. --- ## V4.8 — Bug fixes + Image Experience **Bug fixes (do first within this release — data correctness, not features):** 1. **Stale Error Detail after resubmit.** Root cause found in `db/models.py`: `Source.latest_error_detail` sorts all `execution_attempts` on the latest job by `attempt_number` descending and returns the **first attempt with any `error_detail`**, even if that's an older attempt and the latest attempt succeeded. Fix: only report error detail from the latest attempt, don't fall through to earlier ones. 2. **"View Jobs" ≠ "View Sources" behavior.** `/documents/{id}/sources` already redirects to the filtered Transcription Pipeline Jobs page; `/documents/{id}/jobs` renders its own bare two-field custom page instead. Fix: make `/documents/{id}/jobs` redirect the same way, filtered by document. **Image Experience (Track A from the V4.8 backlog doc — already scoped, high value/low risk, storage layer already exists):** 3. **Homepage Image Gallery** (recommended first feature in that doc): `list_homepage_images()` already returns every stored image; only the multi-image carousel UI and optional slideshow rotation are missing. 4. **Pan and Zoom on Source Detail**: recover `document_panzoom.py` from git history (deleted in V4.6 Phase 5, `6a3ee26`), but vendor the Panzoom library locally instead of the unpkg CDN, and reuse `resolve_media_url` from `media_urls.py` instead of recreating its old helper. Scope to Source Detail only — do not add it to the shared `dark_room_viewer`. **Note:** the backlog doc's model-performance/telemetry item still applies as stated there — it must wait for V4.7 Phase 4 to land first, since `duration_ms` today mixes provider latency with preprocessing/DB commit time. --- ## V4.9 — Detail Page Parity Pass Small, low-risk structural-parity fixes across Person/Job/Document detail pages: - Hide "Maiden Name" on Person detail when empty. - Job Record detail "Document Links" box → mirror the Document detail page's "Sources & Pipeline Jobs" box (clickable name, Sources count, single "View Sources" button, no "+Add Job"). - Transcription Pipeline Jobs page: add a Document Name column; resolve Created vs. Updated by keeping **Updated** as the primary/visible field (more actionable) and de-emphasizing Created rather than deleting it outright. - Person detail "Linked Documents" → 3-column table (Document Name, Role, Number of Pages), with clickable document names, dropping the "Open" button. --- ## V4.10 — Settings Consolidation & Small Enhancements - **Settings page → tabs**, not sub-pages (per your confirmation). Convert the existing stacked cards (Document Types, Person Roles, Prompts) into `ui.tabs`/`ui.tab_panels`, and add a new **Home Page Text** tab. One route, no navigation overhead, scales cleanly as more settings are added. - **Google Maps links** for Person birth/death locations — cheap, no scraping, a formatted place string becomes a Maps search link. - **FamilySearch ID lookup** (scope confirmed as narrow): on the Person create/edit form, add a FamilySearch ID field and an "Auto-fill from FamilySearch" button that fetches only birth date/place, death date/place, and marriage date/spouse for that specific ID — a single-record lookup, not a crawler. This keeps FamilySearch.org as a companion reference rather than a data source the app tries to replace. Because it's ID-driven and single-record, it's a much smaller, safer feature than open-ended scraping — worth doing at this scope, revisit if FamilySearch's page structure changes and breaks the parser. --- ## V4.11 — Bigger UI Features - **Tags** (supersedes "collections"): many-to-many tagging for documents, reusing the Settings registry pattern (autocomplete against existing tags, managed like Document Types/Person Roles). Since you want dedicated UI to browse/filter by tag, include a tag-filter view (e.g. a "Tags" entry point showing documents grouped/filterable by tag) as part of this version, not deferred — that's the UI surface that makes tags actually replace collections day-to-day, not just a data field. - **UI theme selection**: kept simple, per your confirmation — 2–4 curated themes (e.g. Archival/Sepia, Light, Dark, High-contrast), a single stored preference, swapped via existing CSS variables/Tailwind tokens in `theme.py`. No open-ended theme builder. - **Edit Transcription sub-page**: source image + transcription text + editable revision side-by-side, keeping the existing Save Revision/Reset buttons. You noted the exact interaction/layout needs to be clarified when this is scoped — treat this as a design-first item: confirm the two/three column breakpoint behavior and what happens on narrow windows before building. - **Source detail page reflow** (move Candidate Machine Transcriptions to the bottom of the image column; align Source Metadata's top edge with Transcription Text): do this *after* the Edit Transcription sub-page above, since that page will reuse/rearrange the same boxes — avoids reflowing twice. --- ## V5.0 — Unified Photos Table (major data-model change) Per your feedback, this replaces the earlier "Track B" idea with a single shared model: a **`photos` table** holding an image reference plus a text `description` field, used by **both** the homepage gallery and Person portraits — rather than building two separate, one-off metadata layers. Rough shape (subject to the further discussion you flagged before any implementation): - `photos`: id, image path/reference, description, and whatever owner/context linkage is needed (e.g. a polymorphic or nullable `person_id` plus a `context`/`kind` discriminator such as `"homepage"` vs `"portrait"` — exact shape is an open design question, not decided here). - Person gets **multiple portraits** instead of the current single `portrait_path` string column — needs a migration to move existing single-portrait data into the new table. - Homepage images gain **descriptions**, using the same table instead of a separate sidecar/caption mechanism. - Because this is a genuine shared-schema decision (one table, two consumers, plus a migration of existing single-portrait data), this is correctly a 5.x "major change" rather than a small add-on — **flagged for a follow-up design discussion before implementation starts**, specifically on the exact `photos` table shape and how "which photos belong to which person/context" should be modeled. --- ## V6.0 — Server Hosting Migration Your stated approach (Postgres in Docker, app in Docker, Cloudflare Tunnel) is the standard, low-maintenance way to get secure remote access without exposing ports or running your own VPN/reverse-proxy TLS setup. Sequential stages (each de-risks the next): **Stage 0 — Prerequisites** - Confirm data access already goes through the service layer (it does, per `.github/instructions/services.instructions.md`) — this is what makes the DB swap and later auth additive rather than a rewrite. - Confirm upload/file storage path (`settings.upload_dir`) is Docker-volume-friendly. - Confirm DB URL and upload dir are both env-overridable (`.env`/`.env.example` already exist). **Stage 1 — Containerize** against the *existing* SQLite file first (smallest possible change) to validate the container boundary (networking, volumes, permissions) before also switching databases. `Dockerfile`/`docker-compose.yml` already exist in the repo — confirm current intent vs. extend for production. **Stage 2 — Migrate to PostgreSQL.** Since the app uses SQLModel/SQLAlchemy, this should mostly be a connection string/dialect change plus a data migration script. Do this as its own isolated step so a regression is attributable to the DB swap alone. Resolve the Postgres connection through a small factory/indirection point rather than a single global engine constant — this costs nothing now and keeps the door open for per-user databases later (see Beyond, below). **Stage 3 — Expose via Cloudflare Tunnel.** Add a `cloudflared` container pointed at the app's internal port (no public port exposure needed). Put the tunnel hostname behind Cloudflare Access (free tier, email OTP/SSO) as the **first layer of remote-access auth**, even before the app has its own login system — gets secure remote access working quickly and buys time to do Stage 4 and later user-auth properly instead of rushed. **Stage 4 — Backups & operational hygiene.** Automated Postgres backups (scheduled `pg_dump`) and uploaded-file backups *before* exposing this to the internet — this is the point where a data-loss incident would be most damaging. Basic container health checks/restart policies in compose. --- ## V6.1 — Reporting Features Independent of hosting — can be built any time, including in parallel with V6.0: - **Person timelines**: a query/aggregation feature (documents by person, ordered by document date), no hosting dependency. - **AI-written biographies/family histories**: likely reuses the existing prompt/provider abstraction (`services/prompts.py`) already built for transcription, rather than needing new infrastructure. --- ## Beyond / Pie-in-the-sky (informational only — no version assigned) Not being built now, but the plan above is checked against these so nothing forecloses them later: - **Individual user logins + roles** (admin/editor/contributor/view-only): Cloudflare Access (V6.0 Stage 3) is a stopgap, not this. When you get here, add a real `User`/`Role` model and auth middleware. Because the codebase already funnels data access through the service layer, adding a "current user + role check" later is additive — this is the reason to keep service-layer discipline intact through all the versions above, so authorization can be bolted on without touching every page. - **Per-user databases**: protected for by the Stage 2 connection-factory recommendation above (schema-per-tenant or database-per-tenant becomes much easier if the DB connection is already resolved through an indirection point rather than hardcoded at startup). --- ## Open items for you - V5.0 unified `photos` table: needs the follow-up design discussion you flagged (exact schema, how photos link to homepage vs. person context) before implementation. - Confirm this version numbering/grouping matches your intent before work starts.