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

JobSource Schema-to-UI Mapping

Purpose: Map the JobSource schema to UI-facing workflows, while separating intended target behavior from current implementation.

Supporting entity note: JobSource does not currently have a standalone UI surface.

1. Entity Snapshot

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

2. Mapping Rules

This document uses three lenses:

1. Intended behavior: what user-facing workflows should support indirectly.
2. Current behavior: what code supports today.
3. Gap to target: what must change to align implementation with 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
job_id	UUID FK	No	None	Context-managed	Selected Job context
source_id	UUID FK	No	None	Context-managed	Selected Source context
status	enum JobSourceStatus	No	pending	Shown in job detail source context	Per-source execution state
raw_transcription	str	Yes	None	Shown read-only in review context	Machine output per source
ai_metadata	JSONB/JSON	Yes	None	Hidden or advanced diagnostics	Provider metadata
raw_api_response	JSONB/JSON	Yes	None	Hidden or advanced diagnostics	Low-level provider payload
error_detail	str	Yes	None	Shown when status is failed	Execution failure details
executed_at	datetime	No	datetime.now(UTC)	Shown read-only	Execution timestamp

4. CREATE Mapping

4.1 Intended Create Flow

JobSource creation is indirect through Job and transcription workflows:

1. Job create flow should create a JobSource row for each uploaded source page.
2. Processing workflow may create missing JobSource rows when persisting transcription output.

Field	Intended User Input	Required	Visible	Notes
job_id	None	Yes	No	Derived from active Job
source_id	None	Yes	No	Derived from created/selected Source
status	None	No	Indirectly	Defaults to pending at create
raw_transcription	None	No	No at create	Filled after processing
ai_metadata	None	No	No	Operational metadata
raw_api_response	None	No	No	Operational payload
error_detail	None	No	No at create	Filled on failure
executed_at	None	No	No	System-generated

4.2 Current Implementation

Current entry points:

1. upload create path adds pending JobSource link in _create_upload_records().
2. transcription update path creates or updates JobSource row during output persistence.

Current backend paths:

1. src/transcription/services/store.py -> _create_upload_records()
2. src/transcription/services/transcription.py -> update_job_transcription()

Field	Current Value at Create/Update	Source	Visible to User	Evidence
id	Generated UUID	System	No	src/transcription/db/models.py
job_id	Caller or workflow derived	Service/workflow	Indirectly	store.py, transcription.py
source_id	Caller or workflow derived	Service/workflow	Indirectly	store.py, transcription.py
status	pending at create, transcribed or failed on update	Workflow logic	Partial	transcription.py
raw_transcription	Set on successful transcription update	Workflow/provider result	Yes in review context	transcription.py, jobs UI
ai_metadata	Available in model; not currently filled in update path	Workflow potential	No	models.py, transcription.py
raw_api_response	Available in model; not currently filled in update path	Workflow potential	No	models.py, transcription.py
error_detail	Set on failed transcription update	Workflow/provider error	Partial	transcription.py
executed_at	Set at row creation and refreshed on updates	System/workflow	Partial	models.py, transcription.py

4.3 Gap to Target

To satisfy intended supporting behavior, implementation must add:

1. explicit per-source status display for all linked sources in Job detail.
2. clear surfaced error_detail for failed source executions.
3. optional diagnostics surface for ai_metadata/raw_api_response when needed.
4. first-class multi-source create path from Job create flow.

5. READ Mapping

5.1 Intended Read Behavior

Users should see JobSource data indirectly in job detail and review workflows:

1. per-source execution status.
2. per-source raw transcription output.
3. per-source failure details where applicable.
4. execution timestamp context.

5.2 Current Implementation

Current read behavior is partial and job-detail-centric.

Field	Current Rendering	Visible to User	Notes	Evidence
status	Job-level status is visible; source-level status is limited	Partial	Source-level status not fully surfaced as a dedicated list	src/transcription/ui/pages/jobs_page.py
raw_transcription	Original transcription card is visible	Yes	Primary source is shown in current detail flow	src/transcription/ui/components/transcript.py
error_detail	Not prominently surfaced in current detail UI	Partial	Stored in JobSource rows during failures	src/transcription/services/transcription.py
executed_at	Not first-class rendered	Partial	Available in model for future display	src/transcription/db/models.py

Service read/query coverage:

1. read_job_source() reads one row with source relation.
2. list_job_sources() lists rows and supports job_id filtering.

5.3 Gap to Target

To satisfy intended read behavior, implementation must add:

1. source-level execution table in Job detail.
2. explicit failed-source messaging from error_detail.
3. multi-source navigation in job review UI.

6. UPDATE Mapping

6.1 Intended Update Behavior

JobSource updates are workflow-managed, not directly user-edited.

Intended user-editable fields:

• none in first-release behavior

Workflow-managed fields:

• status
• raw_transcription
• error_detail
• executed_at
• optional diagnostics payload fields

6.2 Current Implementation

Field	Updatable via UI	Updatable via Service/Workflow	Notes
status	No	Yes	Set by transcription update and job lifecycle handling
raw_transcription	No	Yes	Persisted in update_job_transcription()
error_detail	No	Yes	Persisted on transcription failure
executed_at	No	Yes	Updated when existing JobSource rows are changed
ai_metadata/raw_api_response	No	Potentially yes	Model supports them; active population is limited

6.3 Gap to Target

Implementation should add:

1. clearer job-detail visualization of per-source execution updates.
2. optional operator diagnostics views for advanced troubleshooting.

7. DELETE Mapping

7.1 Intended Delete Behavior

JobSource deletion should be policy-driven and usually tied to Job/Source lifecycle operations.

Rules:

1. direct user deletion is not required in first-release behavior.
2. cleanup should occur through Job or Source deletion policies.

7.2 Current Implementation

Action	UI Exposed	Backend Capability	Notes
Delete JobSource row	No	Yes	TranscriptionService.delete_job_source() exists

7.3 Gap to Target

Implementation may add:

1. maintenance tooling for cleanup operations.
2. policy-aware cascade guidance in Job and Source delete flows.

8. Hidden and System-Managed Fields

Field	Category	Why Hidden or Protected
id	System-managed	Internal identifier
job_id	Context-managed	Derived from Job context
source_id	Context-managed	Derived from Source context
ai_metadata	Operational metadata	Advanced diagnostics payload
raw_api_response	Operational metadata	Raw provider response payload
executed_at	System-managed	Execution timestamp

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/services/workflows.py
• src/transcription/ui/pages/jobs_page.py
• src/transcription/ui/components/transcript.py
• tests/services/test_v2_crud.py

Related user-facing workflows:

• docs/ui/entities/job/user-journey.md
• docs/ui/entities/source/user-journey.md

10. Coverage Summary

• Every JobSource schema field appears in the field inventory.
• Intended behavior is defined as supporting workflow behavior rather than standalone UI.
• Current behavior reflects workflow/service-driven CRUD with partial job-detail visibility.
• Gaps between intended and current behavior are explicit.