transcription/docs/ui/README.md

UI Documentation

This folder contains UI-focused design and mapping documents that connect the database schema to user-facing workflows.

Document Types

user-journey.md

A product and UX contract for a user-facing entity.

Use this document to describe:

• what the user is trying to do
• which screen or action starts the workflow
• which fields the user sees and edits
• validation rules
• expected success and failure outcomes
• where the user goes next

schema-mapping.md

A field-level mapping between schema, UI, and implementation.

Use this document to describe:

• the authoritative schema fields for an entity
• which fields are shown, hidden, editable, or system-managed
• current implementation behavior
• intended target behavior
• implementation gaps between current code and intended UX

Organization Rules

• Store documents under docs/ui/entities/<entity-name>/.
• Create both user-journey.md and schema-mapping.md for user-facing entities.
• Create only schema-mapping.md for supporting tables that do not currently have standalone UI.
• Keep top-level docs/ reserved for core architecture, requirements, schema, and system-wide reference material.

Current Entity Plan

User-facing entities:

• document
• person
• source
• job

Supporting entities:

• document-person
• job-source

Relationship to Core Docs

These UI docs complement, but do not replace:

• docs/schema_v2.md
• docs/requirements_v2.md
• docs/architecture_v2.md

When there is a conflict:

• schema definitions come from the database model and schema docs
• user interaction intent comes from the user-journey docs
• implementation truth comes from code and is recorded in schema-mapping docs as current-state evidence