From e54c2d9f26533581557f5e7968aadfabb727038c Mon Sep 17 00:00:00 2001 From: Jim Lancaster <40281233+zoltan57@users.noreply.github.com> Date: Wed, 2 Sep 2026 19:03:35 -0500 Subject: [PATCH] Update the roadmap_plan.md --- docs/roadmap_plan.md | 128 +++++++++++++++++++++++++++++++++---------- 1 file changed, 99 insertions(+), 29 deletions(-) diff --git a/docs/roadmap_plan.md b/docs/roadmap_plan.md index 1e487f7..71d23f4 100644 --- a/docs/roadmap_plan.md +++ b/docs/roadmap_plan.md @@ -69,30 +69,104 @@ Status: **Completed** - compose maps Postgres container init values from `DATABASE__*`, - env contract drift tests now guard `.env.production.example`. -## V6.2 - Reporting Features +## V6.2 - GEDCOM Data Layer -[ *More thoughts on additional features:* -* *Ability to search within a document to find potential users to add to the People table.* -* *Ability to search within a document to find dates to associate with people (e.g., John Smith was born on July 7, 1899; or "In February 1942, Martha and I drove to Wisconsin", "We took a vacation to Alaska in the summer of 1987", etc* ] - -Objective: improve research value with person-centric outputs. +Objective: introduce a genealogical data layer sourced from GEDCOM exports, bridged to +existing `Person` records via FamilySearch ID, without disrupting document-focused Person +workflows. ### Scope -1. Person timeline views using document dates and linked records. -2. AI-assisted biography/family-history generation from curated sources. -3. Exportable report views (human-readable, print-oriented). +1. Manual `.ged` file upload only. No FamilySearch credentials are stored or used by the + app; the user runs the third-party `getmyancestors` tool themselves and uploads the + resulting export. +2. Four new tables: `genealogy_person`, `genealogy_family`, `genealogy_family_child`, and + `genealogy_citation` (raw GEDCOM `SOUR` citations, reusable in a later version to record + when a transcribed document itself becomes citation evidence for FamilySearch). +3. Upsert-based import keyed on FamilySearch ID (`fs_id`) so repeat imports update existing + records in place without breaking existing `Person.family_search_id` links or duplicating + surrogate keys. +4. Reuse the existing V6.1 worker-backed `maintenance_run` pattern for import runs (run + history, status, summary, log view/download) rather than new infrastructure. ### Deliverables -- Timeline UI and service queries with clear ordering/filters. -- Prompted narrative generation workflow using existing evidence-safe patterns. -- Saved/printable report presentation for review and sharing. +- GEDCOM parser/importer producing the four genealogy tables. +- `MaintenanceJobType` entry for GEDCOM import with upsert semantics and a run summary + (records added/updated). +- Settings UI entry to upload a `.ged` file, trigger an import run, and view history. ### Exit Criteria +- Importing the same `.ged` file twice does not duplicate or orphan data. +- Existing `Person.family_search_id` values continue to resolve to the correct + `genealogy_person` row after import. +- Import run history is visible with status, duration, and summary, consistent with other + maintenance runs. + +## V6.3 - Reporting and Genealogy-Enriched Features + +Objective: improve research value with person-centric outputs, grounded in both archival +documents and the V6.2 genealogical data layer. + +This version is broken into five sequential sub-versions because of real dependency +ordering: entity linking must exist before GEDCOM data can be targeted per-person; the +Facts/Events mechanism must exist before timelines or reconciliation have anything +meaningful to consume. + +### V6.3.1 - Manual Entity Linking + +- Search/browse UI over `genealogy_person` to find and link a candidate match to an + application `Person`, setting `family_search_id`. Linking is reversible (unlink). +- Once linked, GEDCOM vitals display alongside the `Person` record without requiring any + schema change to `Person`. + +### V6.3.2 - Person Facts and Events + +- New fact/event table capturing: person, fact type (birth/death/event/free-form), date + (+raw), place, free-text description, and a link to the source document as evidence. +- Manual tagging UI while reviewing a transcribed document: select a passage, choose the + person and fact type, record the date/description. +- One-time migration of existing `Person.birth_date`/`birth_date_raw`/`birth_place`/ + `death_date`/`death_date_raw`/`death_place` values into fact/event rows (tagged as + legacy/no-document-evidence where no source document is known), followed by retiring those + six columns from `Person`. Birth/death become Facts/Events like any other locally-known + fact, for both linked and unlinked people. `Person` permanently keeps `last_name`, + `given_names`, `biography`, `family_search_id`, `metadata_`, tags, photos, and document + associations. + +### V6.3.3 - Person Timelines + +- Timeline query merging GEDCOM milestones (birth, marriage, children's births, death) for + linked persons with locally recorded Facts/Events. +- Timeline UI on Person Detail with clear ordering/filters; entries link back to their + originating document or GEDCOM record. + +### V6.3.4 - Reconciliation + +- Compares Facts/Events (the real, document-evidenced local signal) against corresponding + `genealogy_person` fields for linked persons. +- Persisted reconciliation record: person, field, local value with evidence-document link, + GEDCOM value, and status (open / submitted / dismissed). +- Re-evaluated automatically as part of each GEDCOM import maintenance run: opens new + discrepancies, auto-resolves ones where GEDCOM now matches, leaves others unchanged. +- Reconciliation review UI functions as a manual to-do list for updating FamilySearch; the + app does not write back to FamilySearch itself. + +### V6.3.5 - AI-Assisted Biography Generation + +- Prompted narrative generation grounded in GEDCOM facts, Facts/Events, and relevant + document snippets as structured input, using existing evidence-safe prompting patterns. +- Output cites back to source documents and FamilySearch records. +- Saved/printable report presentation for review; reports do not modify archival source + data. + +### Exit Criteria (applies across V6.3.1-V6.3.5) +- Entity links are reversible and do not alter document associations. - Timelines are reproducible from persisted records. +- Reconciliation items always carry a link to the document evidence justifying the local + value, and re-running GEDCOM import correctly opens, resolves, or leaves items unchanged. - Narrative generation is traceable to source records and prompts. - Reports can be reviewed without modifying archival source data. -## V6.3 - Access Control and Multi-User Readiness +## V6.4 - Access Control and Multi-User Readiness [ *More thoughts on user accounts:* * *Create a generic "view only" user that does not have the rights to alter any of the data* @@ -115,26 +189,22 @@ Objective: prepare for managed collaboration beyond single-user operation. - Role policies are enforced by deterministic tests. - User-attributed changes are visible for audit/review. -## V7 or later - Scalability and Multi-Tenant Direction (Optional) +## Deferred / Future Ideas (not committed scope) -Objective: keep architecture ready for broader deployment footprints. - -### Scope -1. Evaluate per-tenant or per-user data partitioning strategy. -2. Formalize connection/runtime strategy for tenant-aware DB selection. -3. Expand operational telemetry for throughput and cost monitoring. - -### Deliverables -- Decision document for tenancy model and migration strategy. -- Prototype-safe runtime boundary for selecting data targets. -- Monitoring baseline for queue depth, job latency, and provider cost trends. - -### Exit Criteria -- Selected tenancy strategy is documented and testable. -- Operational metrics support capacity planning. +Captured for later consideration, not yet scheduled to a version: +* AI-assisted entity disambiguation (kinship co-occurrence, chronological plausibility + filtering) when linking document mentions to people. +* Kinship-aware `@mention` tagging while transcribing. +* Relationship-calculator badges (e.g., "3rd Great-Grandmother") in the document viewer. +* Interactive migration/geography mapping from GEDCOM and document place mentions. +* AI-suggested document discovery by date/location overlap with known persons. +* Ability to search within a document to find potential people to add to the People table. ## Planning Notes - Keep architecture, schema, and UI contracts synchronized in `docs/` as each version lands. - Prefer explicit schema migration over runtime compatibility write paths. - Preserve evidence/provenance guarantees when adding new AI-powered features. +- GEDCOM/FamilySearch data is external, collaborative, and mutable; treat it as a managed + cache bridged via `fs_id`, never as a replacement for archival evidence recorded from + transcribed documents.