# 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)