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 |
| Operations | The installation's own life: the services running, the compute grid, the message bus, the logs, and the versions and database under them |
| Compute | The grid's work: the load, one job end to end, a failure to reproduce, the capacity planned, and what it may run |
| Reporting | A party's reports: which definitions it runs and how the last run of each went, running one on demand, reading what it produced, finding out what went wrong, choosing when it runs, and the configurations it binds, including the pricing engine configurations, the engine run settings and the published curves each market role prices from |
| Cuts | The body of data a valuation prices from: taking a cut at a timepoint and having it authorised, naming one in a report's run settings, and rerunning and auditing one |
| Currencies and FX | Currencies with their countries, calendars and desk groups, and currency pairs |
| Calendars | Holiday calendars: their rules, exceptions and events, and the business days they produce |
| Classifications | The short code lists that classify reference data |
| Parties | The tenant's own legal entities and the counterparties it trades with: their identifiers, contacts, and the countries, currencies and units they connect to |
| Books and portfolios | The book structure: portfolios that hold books, the classification a book carries, and the rights that decide who may see it |
| Conventions | The market terms an instrument is built on, and the reference data lists each convention picks from |
| Tenors | Tenor codes and the resolution the system computes from them, down to the date a tenor produces on a named calendar |
| Market data | Curves and surfaces: their blueprints, the market they are built from, their adjustments, their approval and publication, and how they are read over time |
| Trades | What a person does with a trade: book it, amend it, read it, bring it in from ORE and send it out, record what happens to it, and group trades into one deal |
| Data exchange | Bringing data in and taking it out: a whole environment, a party, one dataset, a retry, and the export for support or archive |
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 have a clickable prototype. Every prototype is a static page
under Prototypes, which is the
only inventory: it names the journey groups, and each group has a page that
lists its prototypes and what each argues. A prototype sits at
doc/prototypes/<journey group>/<name>/, and the one way to add one is plain
HTML, CSS and JavaScript, no framework and no build step. A journey document
links its own prototype under * Prototype and names the commit that accepted
it.
4. A journey is not a screen
A journey says what a person is trying to do, in terms of the reads and writes it needs. It is a design document. It is not the design of a screen, and a screen is not a journey drawn step by step.
The screens that serve a journey follow the UX standards in UX: the list and the page of a subject, the cards with an Edit button each, the dialogs, and the history. One journey is usually served by several standard screens, and one screen serves several journeys. A record, or an entity made of several kinds of record, is edited on the page of the subject and not in a wizard.
A guided sequence of steps is kept for the tasks it makes easier or quicker, for example the first run of an installation and the setup of a tenant. That sequence is a workflow, and the journey runtime defines the step and the rail that orders its steps. A journey document that describes a screen as a run of steps for an ordinary edit is describing the task, not the interface, and the screen does not copy it.
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
- UX — the structure note for this cluster; this page sits alongside its sequence rather than in it.
- User Journey Extraction Standard — the checklist that extracts a component's journeys, including its legacy
ores.qtscreens. - Identity and Access — the structure note that orders this cluster, and where to read this page in it.