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 from a dedicated Sources page.
5. The user opens Source detail to review preview, metadata, transcription text, and revision 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 globally or filtered by selected Document or Job
2. sorting by page_number
3. opening the owning Document or Job context
4. opening Source detail for a selected source

3.2 Source Detail Surface

Source detail supports:

1. pan/zoom image or PDF preview
2. read-only source metadata (page number, names, timestamps)
3. read-only original transcription text
4. editable revision text with save action

4. Entry Points

Primary entry points:

1. from Job workflow, Add sources while creating or configuring a job
2. from Job detail, open filtered Sources for the current Job
3. from Document detail, open filtered Sources for the current Document
4. from global navigation, open all Sources

Current implementation note:

1. source interaction occurs in job-create flow and dedicated Sources list/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 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 for current context (all, document-filtered, or job-filtered)
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. direct action to open Source detail

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 Source detail

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 after trimming
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 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
5. source delete UI with dependency-aware confirmation