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

# Document User Journey

Purpose: Define how a user should interact with the UI to create and manage a Document record, including expected inputs, validation, results, and related record creation.

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

Companion acceptance criteria: acceptance-criteria.md

## 1. Overview

A Document represents a real historical artifact the user wants to describe, organize, and eventually transcribe. The user should be able to create a Document before uploading or linking any source files.

Creating a Document is a metadata-first workflow:
1. The user opens the Document page.
2. The user selects Create new document.
3. The user enters descriptive metadata about the document.
4. The user optionally links one related person.
5. The system creates the Document.
6. If a person was selected or created, the system links that Person to the Document through DocumentPerson.
7. The user sees a success state and lands on the new Document detail page.

## 2. User Goal

The user wants to create a new Document record that:
1. Has enough metadata to identify the historical artifact.
2. Can optionally be linked to a person.
3. Exists independently of transcription jobs and source uploads.
4. Is ready for later steps such as adding sources, starting jobs, and reviewing transcriptions.

## 3. Page Model

### 3.1 Document Page

The Document page is the general UI surface where users manage documents.

It should support:
1. listing or locating existing documents
2. starting the Create new document flow
3. navigating into a specific Document after it exists

### 3.2 Document Detail Page

The Document detail page is the page for one specific Document after it has been created.

It should show:
1. the Document metadata
2. related people linked to the Document
3. a Sources section
4. a Jobs section
5. empty states when no sources or jobs exist yet

It should later support links to filtered views for:
1. jobs associated with the current document only
2. sources associated with the current document only

## 4. Entry Point

Entry point: Document page

Primary action: Create new document

Expected UI affordance:
1. A visible button, link, or primary action labeled Create new document.
2. Activation opens a dedicated form view, modal, or detail panel for creating a Document.

Preferred first implementation:
1. A dedicated Document create page or panel.
2. A simple form with explicit labels.
3. Text inputs are acceptable for first release, even where future versions may use dropdowns or richer selectors.

## 5. Create Document Form

The Create Document form should contain the following fields.

### 5.1 Required Fields

| UI Label | Schema Field | Input Type | Required | Notes |
|---|---|---|---|---|
| Document name | name | Text input | Yes | Examples: Pioneer Days, Letter from Zenna to Omie |
| Document type | document_type | Text input | Yes | Examples: book, letter, enlistment papers, military record, other |

### 5.2 Date Fields

| UI Label | Schema Field | Input Type | Required | Notes |
|---|---|---|---|---|
| Exact date | document_date | Date input | No | Use when the exact date is known |
| Approximate date | document_date_raw | Text input | No | Use when exact date is uncertain, approximate, or unknown |

Date handling rule:
1. The form may allow both fields to be entered.
2. If both fields are entered, `document_date` is the canonical structured date.
3. `document_date_raw` may still be retained as the user-entered descriptive form.
4. The UI should explain the distinction clearly.

Examples:
1. Exact date: `07/13/1885`
2. Approximate date: `c. 1885`
3. Approximate date: `Fall 1925`
4. Approximate date: `unknown`

### 5.3 Optional Metadata Fields

| UI Label | Schema Field | Input Type | Required | Notes |
|---|---|---|---|---|
| Document location | location_created | Text input | No | Where the document was created |
| Notes | notes | Multiline text area | No | Freeform notes about the document |
| Archive identifier | archive_identifier | Text input | No | Free text for now; may represent inventory code, storage reference, or repository note |

Archive identifier guidance:
1. First implementation should treat this as free text.
2. Helper text may explain that this can store a repository code, box or folder reference, or storage note.

### 5.4 System Fields

| Schema Field | User Editable | Notes |
|---|---|---|
| created_at | No | System-generated at creation time |
| updated_at | No | Not user-entered during creation |

### 5.5 Optional Related Person

The Create Document flow may optionally link one related person during first release.

| UI Label | Schema Area | Input Type | Required | Notes |
|---|---|---|---|---|
| Related person | Person -> DocumentPerson | Search/select or create inline | No | Intended to support common author-like associations without making the field mandatory |

First release behavior:
1. The user may save a Document without linking any person.
2. If a person is linked during create, only one person is supported in first release.
3. Additional people and recipient workflows are deferred to a future revision.

### 5.6 Related Records Not Created Directly Here

| Related Area | Included in Document Create | Notes |
|---|---|---|
| Jobs | No | Jobs are created later when transcription work begins |
| Sources | No | Sources are added later as uploaded pages or files |

## 6. Related Person Workflow

### 6.1 User Intent

The user should be able to:
1. select an existing Person to associate with the Document
2. create a new Person if the person does not already exist
3. save the Document even if no person is linked

### 6.2 Data Model Interpretation

Person selection source:
1. The UI should select from Person records.
2. If a person is linked, the system should create a DocumentPerson record.
3. Role handling for non-author document relationships is deferred.
4. If the first release needs a persisted role immediately, the role can default to `author` until the relationship model is broadened.

This means:
1. The user does not choose from DocumentPerson records.
2. DocumentPerson is the relationship created after the Person is chosen or created.

### 6.3 Related Person UI Behavior

Minimum acceptable first implementation:
1. Searchable or scrollable list of existing Person records.
2. Option to create a new Person inline or in a small secondary flow.
3. Clear display of the selected related person before submit.

If the person does not exist:
1. User selects Create new person.
2. User enters the minimum required Person information.
3. System creates Person.
4. System returns to Document create flow.
5. System links the new Person if the user completes Document creation.

## 7. Validation Rules

### 7.1 Required Field Validation

The form must reject submission if:
1. `name` is empty
2. `document_type` is empty

### 7.2 Date Validation

The form should allow:
1. `document_date` only
2. `document_date_raw` only
3. both `document_date` and `document_date_raw`
4. neither date field

If both are present:
1. `document_date` is treated as the canonical exact date
2. `document_date_raw` is retained as descriptive context

### 7.3 Related Person Validation

The form must not require a linked person in first release.

If a related person is selected or created:
1. the selected value must resolve to a valid Person record before final save
2. the DocumentPerson link must not be partially persisted on failure

## 8. Submission Behavior

When the user submits the form, the system should perform these logical steps:
1. validate form inputs
2. create the Document record
3. create a Person record only if the user chose to add a new related person
4. create one DocumentPerson record only if a related person was selected or created
5. persist all intended records successfully before reporting success to the user

Expected write sequence:
1. insert Document
2. insert Person only if needed
3. insert DocumentPerson link only if a person is linked

Recommended transactional behavior:
1. all related writes should succeed or fail together
2. the user should not end up with a partial create state where the Document exists but an intended person link does not

## 9. Expected Result After Success

After successful creation, the user should expect to see:
1. confirmation that the Document was created successfully
2. the Document name displayed in the resulting UI state
3. the Document metadata displayed on the new Document detail page
4. any linked person displayed in the resulting UI state
5. a Sources section showing an empty state when no sources exist yet
6. a Jobs section showing an empty state when no jobs exist yet
7. a clear next step, such as adding source files

Recommended success route:
1. navigate to the new Document detail page
2. show Document summary metadata
3. show linked people section
4. show empty-state placeholders for Sources and Jobs

## 10. Expected Result After Failure

If submission fails, the user should expect:
1. clear error messaging
2. field-level validation feedback where applicable
3. no false success message
4. preservation of entered form values when possible

Examples:
1. missing required name
2. missing required document type
3. failed person creation
4. failed DocumentPerson link creation
5. database or server error

## 11. Read Document Journey

### 11.1 User Intent

The user wants to open a specific Document and quickly understand:
1. what the document is
2. which people are linked to it
3. whether sources exist
4. whether jobs exist
5. what the next action should be

### 11.2 Entry Points

A user can reach a Document detail page by:
1. selecting a document from the Document page list
2. being redirected after successfully creating a new document
3. following a direct link to a known Document record

### 11.3 Document Detail Layout

The Document detail page should include:
1. a header area with document name, document type, and key date values
2. a metadata section with location_created, notes, and archive_identifier
3. system metadata where created_at and updated_at are shown as read-only values
4. a related people section
5. a Sources section
6. a Jobs section

The Document detail page should support:
1. empty-state messaging when no related records exist
2. clear next actions from each empty state
3. future links to filtered Sources and Jobs views scoped to the current document

### 11.4 Read Empty States

If no related records exist:
1. People section says no linked people yet
2. Sources section says no sources added yet
3. Jobs section says no jobs created yet
4. each section presents one clear next action

### 11.5 Read Success Criteria

A successful Read experience means:
1. user can identify the Document immediately
2. user can see whether work has started
3. user can navigate directly to document-scoped Jobs and Sources workflows

## 12. Update Document Journey

### 12.1 User Intent

The user wants to correct or enrich metadata after creation without touching jobs or source transcriptions directly.

### 12.2 Update Entry Point

From the Document detail page:
1. user selects Edit document
2. UI opens edit mode or a dedicated edit view

### 12.3 Editable Fields

First release editable fields:
1. name
2. document_type
3. document_date
4. document_date_raw
5. location_created
6. notes
7. archive_identifier

Read-only or system-managed fields:
1. id
2. created_at
3. updated_at

### 12.4 Update Validation Rules

1. name remains required
2. document_type remains required
3. document_date and document_date_raw may both be present
4. if both date fields are present, document_date remains canonical
5. validation errors should be shown inline and block save

### 12.5 Update Save Behavior

On save:
1. system validates form data
2. system persists Document updates
3. updated_at is refreshed by system policy
4. UI shows a confirmation message
5. user remains on Document detail page with refreshed values

### 12.6 Update Failure Behavior

If save fails:
1. show a clear error message
2. keep user edits in form where possible
3. do not show stale success messaging
4. allow retry without losing context

## 13. Delete Document Journey

### 13.1 User Intent

The user wants to remove a Document only when it is safe and unambiguous.

### 13.2 Delete Entry Point

From the Document detail page:
1. user selects Delete document
2. UI opens a confirmation dialog explaining permanence

### 13.3 Delete Guardrails

Delete is allowed only when:
1. the Document has no related Source records
2. the Document has no related Job records

Delete is blocked when:
1. any Source exists for the Document
2. any Job exists for the Document

### 13.4 Blocked Delete UX

When blocked:
1. show an explicit reason that related Jobs or Sources exist
2. show which dependency types are present
3. provide links to filtered Sources and Jobs for cleanup
4. keep the Document unchanged

### 13.5 Allowed Delete UX

When allowed:
1. show final confirmation with document name
2. perform delete
3. show success confirmation
4. return user to Document page list

### 13.6 Delete Failure Behavior

If delete fails due to system error:
1. show a clear error message
2. keep user on Document detail page
3. preserve ability to retry

## 14. Non-Goals for This Flow

The Document journey does not define:
1. Source upload field-level UX
2. Job execution internals
3. revision editor behavior for transcriptions
4. multi-person recipient workflows in first release

## 15. Relationship to Other Workflows

This Document workflow integrates with:
1. Sources workflow for adding pages or files to the document
2. Jobs workflow for transcription execution
3. Person workflow for future expansion beyond one optional linked person

## 16. Relationship to Schema Mapping

This document is the intended UX contract.

The companion schema-mapping document should answer:
1. which schema field appears on which screen
2. whether the field is currently implemented
3. whether the field is hidden, editable, or system-managed
4. what the implementation gap is between intended UX and current code

## 17. Deferred Items

These topics are intentionally deferred to future revisions:
1. multiple linked people during create and update
2. recipient support during create and update
3. a broader role model for non-author document relationships
4. filtered Jobs and Sources list navigation details