# 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
