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 source lists by document and can navigate to the owning Document or Job.

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 the owning Document or Job context

3.2 Source Detail Surface

Source detail and revision surfaces are deferred in the current UI.

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 job-create and document-scoped source list 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 the owning Document or Job context

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 and processing context.

6.2 Read Surface Expectations

The UI should show:

1. source lists grouped by Document
2. upload_name as the original user-provided filename
3. filename as the stored system filename
4. page_number and ordering context
5. the owning Document and Job navigation context

6.3 Read Empty and Missing States

If source is missing:

1. Show clear not found or no source available messaging

If source metadata is partially unavailable:

1. Show fallback labels and keep navigation available where possible

7. Update Source Journey

7.1 User Intent

The user primarily tracks page-level source records while preserving raw machine output in the service layer.

7.2 Intended Editable Fields

Editable in first release:

1. revised_text in a later revision, not in the current simplified UI

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 when the revision UI exists in a later release
2. persist revised_text when the revision UI exists
3. set date_revised when the revision UI exists
4. show success feedback when the revision UI exists
5. keep user in current source context when the revision UI exists

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 in a future delete flow
2. show cleanup guidance in a future delete flow

When allowed:

1. confirm permanent removal in a future delete flow
2. remove source in a future delete flow
3. return to source list with success state in a future delete flow

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