transcription/docs/ver4/architecture_v4.md

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
• V4 Requirements
• V4 Schema
• V3 Architecture