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.

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. Non-Goals for This Flow

The Create Document flow does not:

1. upload document images or PDFs
2. create transcription jobs
3. start AI processing
4. create Source rows directly
5. edit page-level transcription content

Those actions belong to later workflows.

12. Relationship to Other Workflows

This Document creation workflow should precede:

1. adding Sources to a Document
2. creating transcription Jobs
3. reviewing raw transcription output
4. editing revised transcription text
5. linking additional people or recipients later

13. 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

14. Deferred Items

These topics are intentionally deferred to future revisions:

1. multiple linked people during create
2. recipient support during create
3. a broader role model for non-author document relationships
4. filtered Jobs and Sources list navigation details