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](scope_boundary_v4_1.md)
- [V4 Implementation Plan](../ver4.0/implementation_plan_v4.md)
- [V4 Requirements](../ver4/requirements_v4.md)
- [V4 Error Handling Policy](../ver4/error_handling_v4.md)