User Journeys

Table of Contents

A user journey describes what one person is trying to do, before anything is built. Each journey is one document: the actor, the trigger, the steps, a wireframe of the screen, the entity models it composes, and the operations and messages each step needs — including the ones the server does not provide yet.

These documents describe what a person does in the interface, which screens they move between, and what each screen shows. A journey is a definition, and where a journey needs resumable state, the journey is not server-side — its state is, kept as a workflow instance in ores.workflow. Most journeys need no such state at all. See Journey execution for the four composition classes and where the transaction boundary sits.

Journeys are grouped by logical topic, never by component. A component is an implementation concept, and it changes as the code moves; what a person is trying to do does not. A journey belongs to the group a designer would look in, not to the folder the code happens to live in.

1. Groups

Group What it gathers
Entry Getting in: signing in and out, and self-registration
Setup Standing up an installation: first run, a new tenant, a new party
Profile How a person is represented: name, photo, job title, contact details
Credentials Passwords, sign-in state, and the audit of who signed in
Access Roles, and the permissions each role bundles
Membership Which parties a person works in, and who they report to
Directory The account roster, and bringing accounts in
Tenancy The tenant itself, its lifecycle, and the lookups that classify things

2. How to read a journey

Every journey carries the same sections. * Goal says what the person wants in their own words. * Actor and trigger says who runs it and what brings them there. * Steps is the path. * Screens and wireframes shows the screen, which composes several entity field sets into one place. * Entities composed names the models whose fields appear. * Operations and messages lists every NATS subject the journey needs and marks each one exists, partial or missing. * What is missing gathers the gaps, which are the work that has to happen before the journey can be built. * Related journeys is not documentation decoration: the screen should carry a link for each one, so a person can move between related screens without going back to a menu.

3. Prototypes

Some journeys already have a clickable prototype on a throwaway branch. The journey document links it under * Prototype; the branch is kept as the record and is not merged. The first-setup prototypes are the model for the rest.

4. One screen, not one per entity

A journey is one screen organised around a goal. The list, detail and history primitives still exist, but they are composed into the journey rather than standing alone per entity: contact details and sign-in state are panels on the account journey, not screens of their own. The entity models supply the fields; the journey decides which fields belong together and in what order.

5. Adding a journey

Group a new journey by the topic a designer would look it up under, then scaffold it into that group's folder: 

compass add user_journey \
  --slug <slug> \
  --parent-dir doc/knowledge/journeys/<group> \
  --title "<title>" \
  --description "<one line>" \
  --tags "user_journey,security"

The file is journey_<slug>.org. Wire it into the group hub's table. The full contract is on Document type: user_journey; the recipe is New user journey.

6. See also

Emacs 29.3 (Org mode 9.6.15)