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 schema mapping: schema-mapping.md 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 selects one related person from the existing Person list.
5. The system creates the Document.
6. If a person was selected, the system links that Person to the Document through DocumentPerson with author role.
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 linked-author summary when available
4. document-scoped navigation links for Sources and Jobs
5. filtered views for sources and jobs linked to the current document

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. Existing Person records should be selectable through a dropdown.
4. Text inputs are acceptable for the remaining fields in first release.

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	Dropdown select	No	Selects an existing Person and links as author when saved

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. The selected person is linked as author.
4. 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. change the associated Person from the Document edit flow
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. Dropdown of existing Person records.
2. Clear display of the selected related person before submit.
3. Ability to change or clear the selected person in the Document edit flow.

If the person does not exist:

1. The user should create the Person first from the Person page.
2. The Document create flow only links existing Person records in first release.

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. The user can identify the Document immediately
2. The user can see whether work has started
3. The 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. The 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. The 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