# 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

### acceptance-criteria.md

An implementation-ready checklist for CRUD behavior and quality gates.

Use this document to describe:
- testable acceptance statements by flow (Create, Read, Update, Delete)
- success and failure behaviors
- first-release constraints
- cross-criteria quality gates

### traceability-matrix.md

A criteria-to-code mapping that identifies implementation anchors and status.

Use this document to describe:
- acceptance criteria group to implementation file mapping
- delivery status (implemented, partial, planned)
- ordered implementation priorities

## Organization Rules

- Store documents under `docs/ui/entities/<entity-name>/`.
- Create both `user-journey.md` and `schema-mapping.md` for user-facing entities.
- Create `acceptance-criteria.md` for user-facing entities.
- Create only `schema-mapping.md` for supporting tables that do not currently have standalone UI.
- Keep one shared `traceability-matrix.md` under `docs/ui/entities/` to map criteria to implementation anchors.
- 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