transcription/docs/ver4.1/scope_boundary_v4_1.md

V4.1 Scope Boundary

This document defines the scope of the first incremental revision to Version 4. V4 remains the product and architecture baseline; V4.1 adds focused usability improvements and one additive Person field.

Purpose

• Improve common archival record workflows without redesigning the application.
• Resolve table overflow, ambiguous person selection, and unnecessary navigation.
• Add a manually maintained FamilySearch person reference without introducing external API integration.

In Scope

1. Archival Documents List

• Keep every table column within the available page width.
• Limit and wrap long Document Title values.
• Left-align Document Title and Type.
• Add Author and Document Date columns.
• Display all people linked through the author role in the Author column.
• Display exact document date when present, otherwise approximate date when present, otherwise Unknown.

2. Document Detail and Editing

• Use an unambiguous label in person selectors. The label should prefer Display Name, retain Full Name for context, and include the birth year when known.
• Do not require Display Name to be unique.
• Link each Related People entry to its Person Detail page.
• In view mode, display only the populated exact or approximate document date row. Display a single unknown/not-set state when neither exists.
• Keep both exact and approximate inputs available in create/edit mode.
• Move source navigation out from beneath the media viewer.
• Present Pipeline Jobs and Sources together in one related-processing card with counts and actions.

3. People List

• Left-align Display Name and Maiden Name.
• Display exact birth date when present, otherwise approximate birth date when present, otherwise Unknown.
• Add a Death Date column with the same fallback rule.

4. Person Detail and Editing

• Add a New Document action that opens Document creation with the current person preselected.
• Preserve the existing Document-first workflow.
• In view mode, display only the populated exact or approximate row for each of birth and death date. Display a single unknown/not-set state when neither value exists.
• Keep both exact and approximate inputs available in create/edit mode.

5. FamilySearch Reference

• Add a nullable, unique family_search_id field to Person.
• Allow the field to be entered and changed in Person create/edit flows.
• Trim whitespace, normalize the identifier to uppercase, and validate it against the supported XXXX-XXX alphanumeric shape before persistence.
• When an identifier exists, show a FamilySearch action on Person Detail linking to: https://www.familysearch.org/tree/person/details/{family_search_id}
• Construct the URL in application code; do not persist the full URL.

6. Source List and Detail

• Keep every Source Asset Records table column within the available page width.
• Limit and wrap long Document Name, Upload Title, and Error Detail values.
• Left-align Document Name, Upload Title, and Error Detail.
• Remove Stored Filename only from the Source Asset Records table. Continue storing it and showing it on Source Detail.
• On Source Detail, add previous and next navigation for Sources belonging to the same Document, ordered by page_number.
• Disable or omit the previous/next action at the first/last page.

7. Job Detail

• Automatically refresh Job Detail while the job is in a non-terminal state.
• Use a modest interval in the 3-5 second range.
• Stop polling when the job reaches a terminal state or the page is no longer active.
• Preserve manual navigation and existing job actions.

8. Homepage Storage Decision

• Continue treating homepage markdown and images as mutable application data, not prompt artifacts or packaged source assets.
• Keep homepage content separate from prompts.
• Defer relocation to a configurable application-data root unless the existing location prevents normal installed or deployed operation.

Out of Scope

• Source page renumbering or reordering.
• A Settings page.
• Editing .env or secrets through the UI.
• Runtime theme editing.
• FamilySearch authentication, API calls, search, import, synchronization, or conflict resolution.
• Ancestry references or other genealogy providers.
• Google Maps links from place fields.
• Enforcing unique Display Name values.
• Changes to transcription execution or provider behavior.
• Changes to the V4 API solely to expose the V4.1 presentation enhancements.

Locked Design Decisions

A. Person Selector Identity

• Selection values remain internal Person UUIDs.
• Display labels provide disambiguating context but are not identity keys.
• Duplicate Full Name and Display Name values remain valid.

B. Date Presentation

• Exact dates take precedence over approximate/raw dates for compact list and view presentation.
• Create/edit forms retain both fields so either representation can be maintained.
• V4.1 does not introduce a new mutual-exclusion database constraint.

C. FamilySearch Storage

• Store only the FamilySearch person identifier.
• Treat a FamilySearch person identifier as unique across local Person records.
• Use one dedicated nullable Person field while FamilySearch is the only supported external genealogy reference.
• Reconsider a generic external-reference model only when a second provider or multiple references per person are required.

D. Stored Filename

• Stored Filename remains part of the Source model and Source Detail diagnostics.
• Only the list-table column is removed.

Data and Compatibility Policy

• The family_search_id addition must be nullable and non-destructive for existing Person rows.
• Existing records, routes, relationships, jobs, Sources, prompt provenance, and uploaded media remain valid.
• UI changes must preserve both Document-first and Person-first workflows.
• V4.1 must remain portable across SQLite and PostgreSQL.

Acceptance Criteria

1. Document, Person, and Source tables fit their page containers at supported desktop widths without losing requested columns.
2. Long table text wraps or is constrained without forcing important columns outside the table container.
3. Duplicate-named people can be distinguished in every document relationship selector.
4. Related People entries navigate to the correct Person Detail page.
5. Compact date displays consistently use exact, then approximate, then unknown fallback behavior.
6. Starting from Person Detail can create a Document with that person preselected without breaking normal Document creation.
7. A valid FamilySearch ID is persisted and produces the correct Person Detail hyperlink; absent IDs produce no action.
8. Source previous/next actions remain within the same Document and follow page_number.
9. Active Job Detail pages update without manual refresh and stop polling after terminal status.
10. Stored Filename is absent from the Source list table but remains available on Source Detail.
11. Focused automated tests pass and unaffected V4 behavior remains intact.

Related Local References

• V4.1 Implementation Plan
• V4 Scope Boundary
• V4 Architecture
• V4 Schema