# 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