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 indirectly or hidden	Immutable machine output context
revised_text	str	Yes	None	Editable in Source detail	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: Jobs page create flow
Current user action: upload one or more files or a folder through a single upload widget
Current backend path: job create submit -> create_job_for_document()

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	Selected existing Document id	Job create selection + service write	Indirectly	src/transcription/ui/pages/jobs_page.py, src/transcription/services/store.py
page_number	Sequential assignment based on existing max and alphabetical upload order	Service	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 now includes:

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. filename storage policy using UUID.extension

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 centered on dedicated Sources list/detail routes with optional document/job filtering.

Field	Current Rendering	Visible to User	Notes	Evidence
upload_name	Shown in Sources list and Source detail	Yes	Displayed in source context	src/transcription/ui/pages/sources_page.py
filename	Shown in Sources list and Source detail	Yes	Source metadata shown in list/detail	src/transcription/ui/pages/sources_page.py
file_path	Hidden from direct text rendering	No	Used internally for preview rendering	src/transcription/ui/components/document_panzoom.py
page_number	Shown in Sources list and Source detail	Yes	Ordering visible in filtered/global list	src/transcription/ui/pages/sources_page.py
raw_transcription	Shown read-only in Source detail	Yes	Read from latest linked JobSource context	src/transcription/ui/pages/sources_page.py
revised_text	Shown and editable in Source detail	Yes	Saved through revision action	src/transcription/ui/pages/sources_page.py
date_uploaded	Shown in Source detail	Yes	Read-only metadata	src/transcription/ui/pages/sources_page.py
date_revised	Shown in Source detail	Yes	Read-only metadata after revision save	src/transcription/ui/pages/sources_page.py

5.3 Gap to Target

To satisfy intended Read flow, implementation must add:

1. optional list filtering controls in-page (current filtering is URL/context based)
2. optional page-specific navigation enhancements beyond current list/detail pattern

6. UPDATE Mapping

6.1 Intended Update Behavior

Primary user update for Source is revised_text maintenance in Source detail.

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() from Source detail
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 in a later revision:

1. optional future controls for page ordering and metadata corrections
2. revision history and conflict-resolution UX beyond single revised_text updates

7. DELETE Mapping

7.1 Intended Delete Behavior

Source deletion is deferred in the current UI.

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 should add in a future revision:

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/sources_page.py
• src/transcription/ui/pages/jobs_page.py
• src/transcription/ui/pages/documents_page.py
• src/transcription/ui/components/document_panzoom.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 create flow and dedicated Sources list/detail review flow.
• Gaps between intended and current behavior are explicit.
• Read, Update, and Delete sections distinguish target behavior from current code.