transcription/docs/ver4.1/implementation_plan_v4_1.md

Implementation Plan (Version 4.1)

Goal

Deliver the V4.1 usability revision as a small, behavior-safe increment over the V4 baseline.

Implementation Principles

• Keep presentation formatting in UI components and route orchestration in pages.
• Keep persistence and cross-record queries behind service boundaries.
• Reuse shared table and date-label helpers instead of duplicating fallback logic.
• Make the FamilySearch schema change additive and nullable.
• Add focused tests for changed behavior before broad regression verification.

Current Project Impact

Area	Expected impact
Persistence	Add nullable Person.family_search_id; provide the repository's supported schema-upgrade path for existing databases.
People service	Normalize and validate FamilySearch IDs at the domain/service boundary if model validation does not fully cover writes.
Documents UI	Add table data, improve relationship labels/links, compact date display, and combine processing navigation.
People UI	Add table date fields, Person-first Document creation, compact date display, and FamilySearch controls.
Sources service/UI	Query adjacent document Sources and add bounded navigation; revise list columns and wrapping.
Jobs UI	Refresh the active detail read model on a timer until terminal status.
Shared UI	Add reusable constrained/wrapped table presentation and compact date formatting where appropriate.
Tests	Update model/service and UI coverage for all affected workflows.

Implementation Phases

1. Add Shared Presentation Rules

• Review ui/components/table/common.py and packaged theme CSS for the narrowest reusable table-width solution.
• Add reusable styles or column slots for constrained, wrapping, left-aligned text.
• Add a shared formatter for exact/approximate/unknown dates if it can be reused without coupling components to persistence.
• Preserve sorting and search behavior for rendered display values.

2. Update Archival List Tables

• Extend the Document table read model with author names and the compact document date.
• Build author display from eagerly loaded document-person links using the author role.
• Apply title/type alignment and constrained title wrapping.
• Extend the Person table read model with compact birth and death date values.
• Apply Display Name and Maiden Name alignment.
• Remove Stored Filename from the Source table read model only if no other list behavior consumes it; always remove its rendered column.
• Constrain and left-align the requested Source columns.
• Add or update UI component tests for serialized rows, columns, and fallback formatting.

3. Improve Document Relationship Workflows

• Introduce one person-label formatter that combines preferred Display Name, Full Name context, and known birth year without implying uniqueness.
• Use Person UUIDs as selector values.
• Apply the formatter to every relationship role selector.
• Change Related People rows into actions that navigate to /people/{person_id}.
• Replace separate exact/approximate rows in view mode with one conditional Document Date row.
• Combine Pipeline Jobs and Sources into one related-processing card beneath Related People.
• Preserve existing job/source counts and navigation actions.

4. Add the Person-First Document Workflow

• Add a New Document action on Person Detail.
• Pass the Person UUID through a narrowly defined query parameter to /documents/new.
• Validate the requested UUID against the loaded people list.
• Preselect that person in the intended default relationship role. Use author unless a different role is explicitly encoded later.
• Ignore invalid or unavailable preselection values with the application's normal visible error/notification behavior.
• Confirm ordinary /documents/new behavior remains unchanged.

5. Add FamilySearch Person References

• Add nullable, unique family_search_id to the Person model and schema.
• Implement a non-destructive upgrade for existing SQLite and PostgreSQL databases using the repository's established schema-management approach.
• Normalize values by trimming and uppercasing.
• Validate the XXXX-XXX alphanumeric identifier shape and return a clear validation error for malformed input.
• Report duplicate identifiers as a deterministic conflict rather than a generic persistence failure.
• Add the field to Person create/edit forms and preserve it during updates.
• Add a URL builder that safely inserts only a validated identifier into the fixed FamilySearch details URL.
• Render a FamilySearch action on Person Detail only when an identifier is present.
• Add persistence, normalization, validation, form, and link-generation tests.

6. Add Source Page Navigation

• Add a Sources service query that returns previous/current/next context for a Source within its Document.
• Define ordering by page_number, with a stable secondary key such as Source UUID for defensive determinism.
• Keep navigation bounded to the current document_id.
• Render previous and next actions adjacent to the source viewer or detail header.
• Disable or omit unavailable boundary actions.
• Test first, middle, last, single-page, and cross-document cases.

7. Add Job Detail Auto-Refresh

• Make Job Detail content refreshable without rebuilding unrelated global navigation.
• Start a NiceGUI timer only for queued or processing jobs.
• On each tick, re-read the Job through JobService and refresh the detail content.
• Use a 4-second default interval.
• Stop or deactivate the timer when status becomes completed, partial success, failed, or cancelled, according to the model's actual terminal states.
• Prevent overlapping refresh callbacks.
• Retain existing error presentation if a refresh read fails.
• Add UI tests for timer creation, refresh, and terminal-state stopping.

8. Simplify View-Mode Date Rows

• On Document Detail, show exact date, else approximate date, else one not-set value.
• On Person Detail, apply the same independent rule to birth and death.
• Do not hide either input in create/edit mode.
• Test each exact, approximate, and absent state.

9. Verification and Documentation Alignment

• Run the focused model/service/UI tests covering changed surfaces.
• Run the existing regression suite appropriate to persistence and UI changes.
• Confirm SQLite and PostgreSQL model compatibility at the schema-definition level.
• Update V4.1 documentation if implementation reveals a necessary boundary change; do not silently expand scope.

Recommended Delivery Order

1. Shared formatters and table presentation.
2. Additive Person schema change and FamilySearch validation.
3. Document and Person list/detail changes.
4. Person-first Document workflow.
5. Source navigation.
6. Job polling.
7. Focused and regression verification.

Done When

• Every V4.1 acceptance criterion is demonstrated or covered by a focused test.
• Existing Person rows remain valid after the nullable schema addition.
• Duplicate FamilySearch references cannot be assigned to multiple local Person records.
• FamilySearch links are generated only from normalized, validated IDs.
• Auto-refresh performs no polling after a terminal job state.
• Adjacent Source navigation never crosses Document boundaries.
• The existing V4 workflows remain operational.

Out of Scope

• Page reordering.
• Settings management.
• External genealogy API integration.
• Raw .env editing.
• Theme editing.

Related Local References

• V4.1 Scope Boundary
• V4 Implementation Plan
• V4 Requirements
• V4 Error Handling Policy