V4 plan created: Adding many-to-many links between Documents & People in the UI. Also adding some new tables for Document Type, Person role.

2026-08-09 13:29:50 -05:00
parent e6549277c6
commit 5753eb0135
13 changed files with 1356 additions and 0 deletions
@@ -0,0 +1,137 @@
+# System Architecture (Version 4)
+
+This document describes the V4 architecture changes for expanded `Document`-`Person` relationship management.
+
+V4 extends V3 with role extensibility, assisted suggestion review, and role-policy enforcement while preserving the existing transcription execution topology.
+
+## Architecture Objectives
+
+- Keep V3 transcription pipeline behavior stable unless relationship evidence extraction requires additive integration.
+- Support many people per role for each document.
+- Support extensible relationship roles without hardcoding UI and API behavior to two values.
+- Support non-canonical suggestion intake with explicit human promotion to canonical asserted links.
+- Enforce role exclusivity policy consistently at service and persistence boundaries.
+- Preserve auditability for suggestion provenance and review actions.
+
+## Runtime Topology
+
+V4 keeps the existing runtime shape:
+
+- FastAPI + NiceGUI web app process.
+- Async service layer with SQLModel/SQLAlchemy persistence.
+- Existing worker execution path for transcription jobs.
+
+Additive V4 components:
+
+- Relationship policy evaluator (exclusivity checks).
+- Suggestion lifecycle service (propose/list/accept/reject).
+- Optional suggestion extraction adapter (rule/NLP or LLM-backed).
+
+^^^mermaid
+flowchart LR
+U[Browser User] --> UI[NiceGUI Pages]
+UI --> API[FastAPI Routes]
+API --> DS[Document Service]
+API --> SS[Suggestion Service]
+DS --> PE[Policy Evaluator]
+SS --> PE
+DS --> DB[(Relational DB)]
+SS --> DB
+W[Async Worker Engine] --> DB
+W --> E[Optional Suggestion Extraction]
+E --> SS
+^^^
+
+## Layer Responsibilities
+
+### UI Layer (`src/transcription/ui/**`)
+
+- Render per-role grouped relationships for document and person views.
+- Provide multi-select role assignment controls in document create/edit flows.
+- Provide suggestion review controls (accept/reject) for pending suggestions.
+- Surface policy conflict errors from API/service layer clearly.
+
+### API Layer (`src/transcription/api/**`)
+
+- Expose role-aware and state-aware read contracts.
+- Expose suggestion lifecycle write contracts.
+- Return deterministic validation/conflict errors for exclusivity and duplicate semantics.
+- Evolve endpoints additively, with explicit deprecations and short-lived transition windows.
+
+### Service Layer (`src/transcription/services/**`)
+
+- Implement set-based relationship sync (delta add/remove) to avoid destructive replacement behavior.
+- Apply policy evaluator before persistence commits.
+- Orchestrate suggestion acceptance/rejection transitions.
+- Ensure accepted suggestions result in asserted link creation/confirmation.
+
+### Policy Evaluator (New logical component)
+
+- Evaluate role exclusivity matrix for `(document_id, person_id)` writes.
+- Provide deterministic conflict reason payloads suitable for UI/API display.
+- Stay stateless and reusable across create/update/sync code paths.
+
+### Persistence Layer (`src/transcription/db/**`)
+
+- Store asserted links and suggestion records according to selected schema option.
+- Persist provenance metadata for suggestion records.
+- Enforce uniqueness and support performant role/state filtering.
+
+## Core V4 Workflows
+
+### 1) Manual Relationship Management
+
+1. User opens document edit view.
+2. UI loads asserted links grouped by role.
+3. User adds/removes people per role.
+4. Service computes delta and runs policy checks.
+5. Persistence applies adds/removes atomically.
+
+### 2) Assisted Suggestion Review
+
+1. Suggestion records are created (`pending`) by extraction logic or manual propose action.
+2. UI displays pending suggestions with evidence metadata.
+3. User accepts or rejects each suggestion.
+4. Accept path creates/confirms asserted relationship and marks suggestion `accepted`.
+5. Reject path marks suggestion `rejected`.
+
+### 3) Exclusivity Conflict Handling
+
+1. Incoming write attempts role assignment.
+2. Policy evaluator checks role pair conflicts for same `(document_id, person_id)`.
+3. If conflict exists, write is rejected with structured conflict details.
+4. UI presents actionable message without partial updates.
+
+## Invariants
+
+- Suggested links are never canonical until accepted.
+- Asserted links must satisfy exclusivity rules.
+- Relationship mutations are set-based and deterministic.
+- Relationship views remain consistent between document detail and person detail pages.
+- Existing V3 links remain valid under asserted semantics after migration.
+
+## Backward Compatibility
+
+- V3 author/recipient links are interpreted as asserted links in V4.
+- Existing document and person flows continue to function where unaffected by new role/state dimensions.
+- During development revisions, the current API contract is authoritative; long-lived legacy runtime compatibility layers are not required.
+
+## Observability and Auditability
+
+- Persist suggestion provenance fields sufficient for operator review.
+- Record review decision outcomes (`accepted`/`rejected`) with timestamps and reviewer identity where available.
+- Emit structured service-level logs for exclusivity conflicts and review actions.
+
+## Test Strategy Additions
+
+- Service tests for delta sync and exclusivity matrix enforcement.
+- API tests for role/state filtering and suggestion transitions.
+- UI tests for multi-role selection and suggestion review interactions.
+- Migration tests for V3-to-V4 asserted mapping and conflict scans.
+
+## Related Local References
+
+- [V4 Scope Boundary](scope_boundary_v4.md)
+- [V4 Requirements](requirements_v4.md)
+- [V4 Schema](schema_v4.md)
+- [V3 Architecture](../architecture_v3.md)