transcription/docs/ui/entities/source/user-journey.md

Source User Journey

Purpose: Define how a user should interact with the UI to create and manage Source records, including page-level transcription context and revision behavior.

Scope: This document describes intended user interaction for the Source UI. It is the UX contract for the Source entity.

Companion schema mapping: schema-mapping.md Companion acceptance criteria: acceptance-criteria.md

1. Overview

A Source represents one page or file unit associated with a Document.

Managing Source records is page-first:

1. The user starts from a transcription job flow.
2. The user adds one or more source files.
3. The system creates Source records linked to the Document and linked to the Job through JobSource.
4. The user reviews original transcription output and can maintain revised text.

2. User Goal

The user wants to:

1. add page files to a Document
2. ensure every source is attached to the transcription job context
3. keep page order reliable
4. review original machine output
5. save human revisions per page
6. navigate source pages efficiently

3. Page Model

3.1 Source List Surface

A Source list surface should support:

1. listing source pages for a selected Document
2. sorting by page_number
3. opening a source detail or revision view

3.2 Source Detail Surface

A Source detail surface should show:

1. file preview (image or PDF)
2. source metadata
3. original transcription context
4. revision editor and revision state

4. Entry Points

Primary entry points:

1. from Job workflow, Add sources while creating or configuring a job
2. from Job detail, open source preview and revision editor

Current implementation note:

1. source interaction currently occurs in upload and job-detail flows

5. Create Source Flow

5.1 User Intent

The user wants to attach one or more files to a Document so each page can be processed and reviewed.

5.2 Create from Job Context

1. The user starts from a job-creation or job-configuration flow
2. The user can upload one or more files, or upload a whole folder
3. The system creates Source rows linked to the selected Document
4. The system creates JobSource links for the active Job as part of this flow
5. Source creation fails if required Document or Job linkage cannot be established

5.3 Source Create Inputs

UI Label	Schema Field	Input Type	Required	Notes
Source files	upload_name/filename/file_path	Multi-file upload or folder upload	Yes	User may select one file, many files, or a folder
Processing order	page_number assignment rule	System rule	Yes	If multiple files are uploaded, processing order is alphabetical by original filename
Document reference	document_id	Hidden/context	Yes	Comes from selected Document
Job reference	JobSource.job_id	Hidden/context	Yes	Required for first-release source creation

5.4 Filename Strategy

1. store original user filename in upload_name
2. store persisted filename using UUID plus original extension only, in the form UUID.extension
3. this replaces the previous UUID-upload_name.extension pattern

5.5 Ordering Guidance

1. multi-file or folder uploads are processed alphabetically by original filename
2. UI should show a warning or helper note so users understand that filename conventions control order

Suggested helper text:

1. Files are processed alphabetically by original filename. Use leading numbers such as 001, 002, 003 to control page order.

5.6 System-Managed Values at Create

Schema Field	User Editable	Notes
id	No	System-generated
date_uploaded	No	System-generated
raw_transcription	No	Filled later by processing
revised_text	No	Initially empty
date_revised	No	Initially null

5.7 Expected Create Result

After successful source create:

1. Source is linked to the Document
2. Source appears in page order derived from alphabetical upload filename ordering
3. Source is linked to the Job through JobSource at create time
4. The user can open preview and revision workflow

5.8 Source Creation Invariant

For first release:

1. every new Source must have a Document link (Source.document_id)
2. every new Source must have a Job link through JobSource (JobSource.job_id -> JobSource.source_id)
3. source creation is treated as part of transcription workflow, not a standalone document-only upload path

6. Read Source Journey

6.1 User Intent

The user wants to view each page file and understand file identity, processing context, and revision status.

6.2 Read Surface Expectations

The UI should show:

1. file preview for the current Source
2. upload_name as the original user-provided filename
3. filename as the stored system filename
4. file_path information, with the option to keep it internal or partially hidden for safety
5. page_number and ordering context
6. whether revised_text exists
7. original transcription output context

6.3 Read Empty and Missing States

If source is missing:

1. Show clear not found or no source available messaging

If source has no revision:

1. Show empty-state guidance and create-revision action

If source metadata is partially unavailable:

1. Show fallback labels and keep preview and revision actions available where possible

7. Update Source Journey

7.1 User Intent

The user primarily updates page-level revision text while preserving raw machine output.

7.2 Intended Editable Fields

Editable in first release:

1. revised_text

Read-only in first release:

1. upload_name
2. filename
3. file_path
4. raw_transcription
5. page_number
6. date_uploaded
7. date_revised set by system on revision save

7.3 Revision Save Behavior

On save:

1. validate revision text is non-empty
2. persist revised_text
3. set date_revised
4. show success feedback
5. keep user in current source context

7.4 Revision Failure Behavior

If save fails:

1. Show clear error feedback
2. keep user input where possible
3. Allow retry

8. Delete Source Journey

8.1 User Intent

The user may need to remove incorrect or duplicate source files from a Document.

8.2 Guardrails

Delete is allowed when:

1. policy allows removal of related processing history

Delete is blocked when:

1. policy requires preserving dependent job-source execution records until explicit cleanup

8.3 Delete UX

When blocked:

1. explain dependency constraints
2. Show cleanup guidance

When allowed:

1. confirm permanent removal
2. remove source
3. return to source list with success state

9. Relationship to Other Workflows

Source workflow integrates with:

1. Document workflow for ownership and page organization
2. Job workflow for processing status and outputs
3. revision workflow for human correction lifecycle

10. Relationship to Schema Mapping

The companion schema-mapping document should specify:

1. field visibility per CRUD action
2. current implementation status
3. intended behavior
4. gap-to-target items

11. Deferred Items

Deferred to future revisions:

1. bulk page reordering UX
2. multi-file upload progress and resumable upload UX
3. revision history versions beyond a single revised_text field
4. richer per-page status dashboards