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

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.