# Source Schema-to-UI Mapping

Purpose: Map the Source 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: Source
- Primary key: id (UUID)
- Related entities: Document, JobSource, Job
- 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 |
| document_id | UUID FK | No | None | Hidden/context-managed | Selected Document context |
| page_number | int | No | 1 | Shown read-only or ordered list | Sequential ordering |
| upload_name | str | No | None | Shown read-only after upload | Original user-provided name |
| filename | str | No | None | Shown read-only | Stored filename |
| file_path | str | No | None | Usually hidden; preview uses path internally | Filesystem path |
| raw_transcription | str | Yes | None | Shown read-only | Immutable machine output context |
| revised_text | str | Yes | None | Shown editable | Human-authored correction |
| date_uploaded | datetime | No | datetime.now(UTC) | Shown read-only | System-managed timestamp |
| date_revised | datetime | Yes | None | Shown read-only | Set when revision is saved |

## 4. CREATE Mapping

### 4.1 Intended Create Flow

Entry point: Job creation or job configuration Add sources action  
User action: upload one or more source files, or a whole folder  
Success destination: source preview or revision flow in job detail context

| Field | Intended User Input | Required | Visible | Notes |
|---|---|---|---|---|
| document_id | Hidden/context | Yes | No | Comes from selected Document |
| JobSource.job_id | Hidden/context | Yes | No | Comes from active Job; required for first release |
| page_number | Auto or user-assisted ordering | Yes | Indirectly | Should preserve sequence |
| upload_name | File picker name | Yes | Yes | Original display name |
| filename | None | Yes | No or read-only | System-stored as UUID.extension |
| file_path | None | Yes | No | Storage path |
| raw_transcription | None | No | No | Filled by processing |
| revised_text | None | No | No | Initially empty |
| date_uploaded | None | No | No | System-generated |
| date_revised | None | No | No | Null until revision |

### 4.2 Current Implementation

Current entry point: upload page through create_upload_job()  
Current user action: upload one file through upload flow  
Current backend path: upload submit -> create_upload_job -> _create_upload_records

| Field | Current Value at Create | Source | Visible to User | Evidence |
|---|---|---|---|---|
| id | Generated UUID | System | No | Source model default in src/transcription/db/models.py |
| document_id | Created Document id | Service | Indirectly | src/transcription/services/store.py |
| page_number | 1 | Service default in upload flow | No | src/transcription/services/store.py |
| upload_name | original filename basename | User file name transformed by service | Indirectly | src/transcription/services/store.py |
| filename | stored generated filename | Service | Indirectly | src/transcription/services/store.py |
| file_path | stored path | Service | Indirectly | src/transcription/services/store.py |
| raw_transcription | None initially | System | No at create | Source model defaults |
| revised_text | None initially | System | No at create | Source model defaults |
| date_uploaded | current UTC timestamp | System | No | Source model default |
| date_revised | None | System | No | Source model default |

### 4.3 Gap to Target

To satisfy intended Create flow, implementation must add:
1. multi-source and folder upload support in job create/configure flows
2. deterministic page_number assignment from alphabetical original filename ordering
3. enforced create-time Source-to-Document and Source-to-Job linkage invariants
4. complete filename storage policy migration to UUID.extension only

## 5. READ Mapping

### 5.1 Intended Read Behavior

On Source detail/list surfaces, users should be able to see:
1. source page preview
2. source metadata and ordering
3. revision state
4. original transcription context

### 5.2 Current Implementation

Current Source reading is primarily embedded in job detail.

| Field | Current Rendering | Visible to User | Notes | Evidence |
|---|---|---|---|---|
| upload_name | Shown in source-related UI | Yes | Displayed in job detail source context | src/transcription/ui/components/job_detail.py |
| filename | Indirectly shown in jobs list/detail | Yes | Via Job.filename and source metadata | src/transcription/ui/components/table/jobs.py, src/transcription/ui/pages/jobs_page.py |
| file_path | Used for preview rendering | Indirectly | Source preview in job detail page | src/transcription/ui/pages/jobs_page.py |
| page_number | Not explicitly rendered in current jobs page flow | Limited | Ordering implicit via selected source | jobs page flow |
| raw_transcription | Rendered from JobSource context | Yes | Original transcription card | src/transcription/ui/components/transcript.py |
| revised_text | Rendered/editable in revision editor | Yes | Revision editor in job detail page | src/transcription/ui/pages/jobs_page.py |
| date_uploaded | Limited visibility | Partial | Shown in some source metadata components | src/transcription/ui/components/job_detail.py |
| date_revised | Indirect via revision row timestamp | Partial | Used in revision caption | src/transcription/ui/components/transcript.py |

### 5.3 Gap to Target

To satisfy intended Read flow, implementation must add:
1. dedicated Source list and detail surfaces under Document context
2. explicit page_number presentation and navigation
3. clearer source metadata display independent of Job-centric pages

## 6. UPDATE Mapping

### 6.1 Intended Update Behavior

Primary user update for Source is revised_text maintenance.

Intended editable fields (first release):
- revised_text

Intended read-only fields (first release):
- document_id
- page_number
- upload_name
- filename
- file_path
- raw_transcription
- date_uploaded
- date_revised

### 6.2 Current Implementation

| Field | Updatable via UI | Updatable via Service | Notes |
|---|---|---|---|
| revised_text | Yes | Yes | Saved via TranscriptionService.upsert_revision_for_source() |
| date_revised | No | Yes | Set automatically on revision save |
| other fields | No | Technically yes in service layer | No first-class UI editing flow |

### 6.3 Gap to Target

Implementation should add:
1. explicit Source edit boundaries in dedicated Source UI
2. validation and save UX for revisions in document-scoped source views
3. optional future controls for page ordering and metadata corrections

## 7. DELETE Mapping

### 7.1 Intended Delete Behavior

Source deletion should include dependency-aware guardrails.

Rules:
1. Deletion can proceed when policy allows cleanup of related JobSource records.
2. If related execution history must be preserved first, deletion is blocked with guidance.

### 7.2 Current Implementation

| Action | UI Exposed | Backend Capability | Notes |
|---|---|---|---|
| Delete Source | No | Yes | TranscriptionService.delete_source() exists, no dedicated UI delete flow |

### 7.3 Gap to Target

Implementation must add:
1. source delete controls in source/document context UI
2. dependency checks for JobSource links
3. blocked-delete messaging and cleanup path guidance
4. confirmation UX for successful delete attempts

## 8. Hidden and System-Managed Fields

| Field | Category | Why Hidden or Protected |
|---|---|---|
| id | System-managed | Internal identifier |
| document_id | Context-managed | Derived from selected document context |
| file_path | Operational/internal | Used for file storage and preview plumbing |
| date_uploaded | System-managed | Audit timestamp |
| date_revised | System-managed | Revision timestamp set by system |

## 9. Traceability Anchors

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

Current implementation:
- src/transcription/services/store.py
- src/transcription/services/transcription.py
- src/transcription/ui/pages/jobs_page.py
- src/transcription/ui/components/transcript.py
- src/transcription/ui/components/job_detail.py

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

Acceptance checklist:
- docs/ui/entities/source/acceptance-criteria.md

## 10. Acceptance Checklist Summary

- Every Source schema field appears in the field inventory.
- Intended Create behavior matches the companion user journey.
- Source create invariant requires both Document linkage and Job linkage at create time.
- Current behavior reflects upload-centric and job-detail-centric implementation.
- Gaps between intended and current behavior are explicit.
- Read, Update, and Delete sections distinguish target behavior from current code.