transcription/docs/ui/entities/document/schema-mapping.md

# Document Schema-to-UI Mapping

Purpose: Map the Document schema to the UI, while clearly separating intended target behavior from current implementation.

Companion document: user-journey.md
Acceptance criteria: acceptance-criteria.md

## 1. Entity Snapshot

- Table: Document
- Primary key: `id` (UUID)
- Related entities: `Source`, `Job`, `DocumentPerson`
- Canonical schema references:
  - `src/transcription/db/models.py`
  - `docs/schema_v2.md`

## 2. Mapping Rules

This document uses three lenses:
1. Intended behavior: what the UX should support.
2. Current behavior: what the code supports today.
3. Gap to target: what must change to align implementation with the intended UX.

## 3. Field Inventory

| Field | DB Type | Nullable | Default/Auto Value | Intended UI Treatment | Notes |
|---|---|---|---|---|---|
| id | UUID | No | `uuid4()` | Hidden, system-managed | Primary key |
| name | str | No | None | Shown, editable on create and future edit | Required |
| document_type | str | Yes | None | Shown, editable on create and future edit | Required by intended UX |
| document_date | date | Yes | None | Shown, editable | Canonical exact date when present |
| document_date_raw | str | Yes | None | Shown, editable | Approximate or unknown date text |
| location_created | str | Yes | None | Shown, editable | Optional metadata |
| notes | str | Yes | None | Shown, editable | Optional metadata |
| archive_identifier | str | Yes | None | Shown, editable | Free text in first release |
| created_at | datetime | No | `datetime.now(UTC)` | Hidden or read-only | System-managed |
| updated_at | datetime | No | `datetime.now(UTC)` | Hidden or read-only | System-managed |

## 4. CREATE Mapping

### 4.1 Intended Create Flow

Entry point: Document page  
User action: Create new document  
Success destination: new Document detail page

| Field | Intended User Input | Required | Visible | Notes |
|---|---|---|---|---|
| name | Text input | Yes | Yes | Primary identifier used by the user |
| document_type | Text input | Yes | Yes | Free text in first release |
| document_date | Date input | No | Yes | Structured exact date |
| document_date_raw | Text input | No | Yes | Approximate or uncertain date |
| location_created | Text input | No | Yes | Optional |
| notes | Text area | No | Yes | Optional |
| archive_identifier | Text input | No | Yes | Free text |
| created_at | None | No | No | System-generated |
| updated_at | None | No | No | Not used during initial create |

Related records during intended create:
- A related person may optionally be selected or created.
- If present, the system creates a `DocumentPerson` link.
- Jobs are not created during Document create.
- Sources are not created during Document create.

### 4.2 Current Implementation

Current entry point: upload page  
Current user action: upload file via upload widget  
Current backend path: upload page submit callback -> `create_upload_job()` -> `_create_upload_records()`

| Field | Current Value at Create | Source | Visible to User | Evidence |
|---|---|---|---|---|
| id | Generated UUID | System | No | `Document` default factory in `src/transcription/db/models.py` |
| name | Basename of uploaded filename | User file name transformed by service | Indirectly | Set in `src/transcription/services/store.py` |
| document_type | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
| document_date | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
| document_date_raw | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
| location_created | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
| notes | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
| archive_identifier | `None` | Service default | No | Not set in `src/transcription/services/store.py` |
| created_at | Current UTC timestamp | System | No | Default factory in `src/transcription/db/models.py` |
| updated_at | Current UTC timestamp | System | No | Default factory in `src/transcription/db/models.py` |

Current related-record behavior:
- `Job` is created automatically.
- `Source` is created automatically.
- `JobSource` is created automatically.
- No `Person` or `DocumentPerson` records are created.

### 4.3 Gap to Target

To satisfy the intended Create flow, implementation must add:
1. a Document page and dedicated create form
2. user-entered metadata fields for `document_type`, `document_date`, `document_date_raw`, `location_created`, `notes`, and `archive_identifier`
3. optional Person lookup and inline Person creation
4. optional `DocumentPerson` link creation when a person is chosen
5. post-submit routing to a Document detail page
6. removal of the assumption that Document creation always starts with file upload

## 5. READ Mapping

### 5.1 Intended Read Behavior

On the Document detail page, the user should be able to see:
1. Document metadata
2. linked people
3. a Sources section with empty-state behavior when no sources exist
4. a Jobs section with empty-state behavior when no jobs exist
5. future links to filtered Jobs and Sources views for the current document

### 5.2 Current Implementation

Current Document visibility in the UI is indirect.

| Field | Current Rendering | Visible to User | Notes | Evidence |
|---|---|---|---|---|
| name | Indirect filename context in jobs list and job detail | Yes, indirect | The UI shows source/job filename, not a dedicated Document page | `src/transcription/ui/pages/jobs_page.py`, `src/transcription/ui/components/table/jobs.py` |
| id | Not shown as Document id | No | Job id is shown instead | `src/transcription/ui/pages/jobs_page.py` |
| document_type | Not rendered | No | Hidden metadata | no current UI field |
| document_date | Not rendered | No | Hidden metadata | no current UI field |
| document_date_raw | Not rendered | No | Hidden metadata | no current UI field |
| location_created | Not rendered | No | Hidden metadata | no current UI field |
| notes | Not rendered | No | Hidden metadata | no current UI field |
| archive_identifier | Not rendered | No | Hidden metadata | no current UI field |
| created_at | Not rendered as Document timestamp | No | Job timestamps are shown instead | `src/transcription/ui/components/table/jobs.py` |
| updated_at | Not rendered as Document timestamp | No | Job metadata is shown instead | `src/transcription/ui/components/transcript.py` |

### 5.3 Gap to Target

To satisfy the intended Read flow, implementation must add:
1. a Document detail page
2. metadata rendering for Document fields
3. linked people rendering
4. Sources and Jobs sections with empty states
5. filtered navigation from the detail page into document-specific Jobs and Sources views

## 6. UPDATE Mapping

### 6.1 Intended Update Behavior

The user should eventually be able to edit Document metadata from the Document detail page or a dedicated edit flow.

Intended editable fields:
- `name`
- `document_type`
- `document_date`
- `document_date_raw`
- `location_created`
- `notes`
- `archive_identifier`

Intended system-managed fields:
- `id`
- `created_at`
- `updated_at`

### 6.2 Current Implementation

| Field | Updatable via UI | Updatable via Service | Notes |
|---|---|---|---|
| id | No | Practically no | Primary key should be treated as immutable |
| name | No | Yes | `DocumentService.update_document()` |
| document_type | No | Yes | `DocumentService.update_document()` |
| document_date | No | Yes | `DocumentService.update_document()` |
| document_date_raw | No | Yes | `DocumentService.update_document()` |
| location_created | No | Yes | `DocumentService.update_document()` |
| notes | No | Yes | `DocumentService.update_document()` |
| archive_identifier | No | Yes | `DocumentService.update_document()` |
| created_at | No | Technically yes | Should remain system-managed |
| updated_at | No | Technically yes | Should remain system-managed |

### 6.3 Gap to Target

Implementation must add:
1. Document edit controls in the UI
2. validation and save behavior for Document metadata
3. a consistent `updated_at` update policy if metadata edits are introduced

## 7. DELETE Mapping

### 7.1 Intended Delete Behavior

The UI should eventually provide a delete action for Document with guardrails.

Rules:
1. A Document can be deleted when it has no attached Jobs and no attached Sources.
2. If dependent Jobs or Sources exist, the UI should block deletion and explain that those related records must be removed first.
3. Delete confirmation should make it clear that the action is permanent.

### 7.2 Current Implementation

| Action | UI Exposed | Backend Capability | Notes |
|---|---|---|---|
| Delete Document | No | Yes | `DocumentService.delete_document()` exists, but no dedicated UI guard flow exists |

### 7.3 Gap to Target

Implementation must add:
1. a Document delete control in the UI
2. pre-delete dependency checks for Jobs and Sources
3. user-facing messaging when deletion is blocked
4. confirmation UX for successful delete attempts

## 8. Hidden and System-Managed Fields

| Field | Category | Why Hidden or Protected |
|---|---|---|
| id | System-managed | Internal identifier |
| created_at | System-managed | Audit timestamp |
| updated_at | System-managed | Audit timestamp |

## 9. Traceability Anchors

Schema and models:
- `docs/schema_v2.md`
- `src/transcription/db/models.py`

Current implementation:
- `src/transcription/services/documents.py`
- `src/transcription/services/store.py`
- `src/transcription/ui/pages/upload_page.py`
- `src/transcription/ui/pages/jobs_page.py`
- `src/transcription/ui/components/table/jobs.py`
- `src/transcription/ui/components/transcript.py`

Companion UX spec:
- `docs/ui/entities/document/user-journey.md`

## 10. Acceptance Checklist Summary

- Every Document schema field appears in the field inventory.
- Intended Create behavior matches the companion user journey.
- Current Create behavior reflects the existing upload-driven implementation.
- Gaps between intended and current behavior are explicit.
- Read, Update, and Delete sections distinguish target behavior from current code.