User Journey Specification

What is this document?

User journeys trace a real person through a complete task — signing up, paying, getting help — across every layer: what they see, which API is called, and which rows change in the database.

They are the thread that connects entities to endpoints to screens.

Why does it matter?

• Without journeys, the AI builds the database, API and UI in isolation — and nothing connects.
• Edge paths (cancel, retry, go back) are designed instead of discovered by users.
• Every step names its success and failure state.

What's inside?

• Journey list — The critical journeys per space, ranked by importance.
• Step-by-step flows — User → frontend → API → database for every step.
• Alternate paths — Errors, cancellations and resumptions.

How CREAH generates it

CREAH builds this document from your Stage 0 answers and interview. Questions that shape it include:

• What happens if the user closes the tab halfway through checkout?
• Which journey must work perfectly on day one?
• Where does the user go after the task succeeds?

Example excerpt

## Journey: Individual User Creates and Pays for a Project

Step 1: User submits the brief
  → Frontend: validates fields, calls POST /api/projects
  → API: creates the project row (status: draft)

Step 2: Price shown
  → API: GET /api/projects/{id}/cart (deterministic, no AI)
  → Frontend: renders itemised line items