Story: Prototype the post-setup IAM journeys in ores.web
Table of Contents
This page documents a story in Sprint 25. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
1. Goal
This story is a wayfinder map: an index of decisions. Each decision
lives in its task. Tasks carry a [wayfinder:<type>] tag. Each task
names its blockers in its goal. The frontier is every BACKLOG task
whose blockers are all DONE.
1.1. Destination
A user-journey document for every post-setup IAM journey, then clickable ores.web prototypes taken one journey at a time. The journeys come from what a person is trying to do, not from the domain entities, and the member's journeys and the tenant administrator's journeys are separate journeys with separate screens. Each journey is documented before it is prototyped, and each document names the operations and subjects it needs, so the server-side gaps are visible before any code is written.
1.2. Notes
- This effort carries execution, not only decisions. The destination includes the journey documents, then the prototypes, then the implementation.
- Start from the user journey, never from the entity. An owned record such as contact information or login information becomes a panel inside a journey, not a screen of its own. A reference lookup is the likely exception, and Decide what building material to reuse and what to decommission settles it.
- The list, detail and history primitives survive, but they are no longer per entity. A journey is one screen organised around a goal, composing several entity field sets as panels. That abandons the entity-level view, not the primitives.
- The generated TypeScript is building material, not the design. The protocol messages and the column and field metadata are reused wherever they help.
- A journey is documented as a
user_journeydocument underdoc/knowledge/journeys/, grouped by logical topic rather than by component. The contract is Document type: user_journey and the recipe is New user journey. - Every journey document carries a wireframe and a table of the operations and
subjects it needs, each marked
exists,partialormissing. Those tables are where the server-side gaps surface. - A prototype records every modeling error and every missing server-side operation it exposes. The inventory already names gaps the journeys are expected to meet: no forgot-password operation, no account activate or deactivate, no way for an administrator to end another account's session, no subject for session statistics, and no image upload for a profile photo.
- Screens are designed for the web, not cloned from ores.qt. Follow UI design principles and UX language.
- One prototype per journey: a
prototype/<journey>branch cut fromfeature/iam-screens-from-user-journeys, with a[wayfinder:prototype]ticket. Accepted prototypes merge back; the rest stay on their branch as the record. - Pattern to copy:
prototype/first-run-journey,prototype/new-tenant-journeyandprototype/new-party-journey– the same approach applied to the bootstrap journeys. - The word journey is settled: a
user journey is a design
document, and the journey is the definition it becomes. The journey is not
server-side; its state is, and that state is a
workflow instance in
ores.workflow. Most post-setup journeys keep no such state. Journey execution records this and the four composition classes. - The authoritative entity is account. "User" is not a defined term: it is one value of account type, beside service, algorithm and LLM.
- Grilling tasks: use the grilling and domain-modeling skills. Research tasks: use the research skill. Prototype tasks: use the prototype skill.
- Legacy reference: the ores.qt post-setup screens –
MyAccountDialog,SessionAuditDialog,AccountRolesWidget,AccountPartiesWidget,AccountChildEntityTablesandOrgChartWidget– and the screen-per-entity web screens this map replaces.
1.3. Not yet specified
- The prototype ticket for each journey, and the order they are taken in. One journey at a time, from its document to a prototype to an implementation.
- The implementation of the missing operations the documents expose: the self-service profile update, the image upload, session statistics, ending another account's session, and account activate or deactivate.
- Where the gap log lives.
2. Status
| Field | Value |
|---|---|
| State | ABANDONED |
| Parent sprint | Sprint 25 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-09-23 |
3. Acceptance
- The journey catalogue names every post-setup IAM journey, with the member's journeys and the tenant administrator's journeys listed separately.
- Every journey has an accepted prototype, or a recorded reason it has none.
- Every IAM operation a person can perform is reachable through some journey.
- Every non-secret IAM field is visible or editable somewhere.
- No secret field reaches the browser. The forbidden fields are
password_hash,password_salt,service_password_hash,totp_secret, every cleartext password field, and every JWT. - Service-only operations are listed as out of scope, so the gap is deliberate.
- Every modeling error and every missing server-side operation a prototype exposed is recorded in the gap log.
4. Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Scaffold story: Prototype the post-setup IAM journeys in ores.web | DONE | 2026-09-23 | Story scaffolding rides this task: documents, sprint wiring, and the scaffold PR. Close it before merging that PR. | |
| Inventory the IAM functionality a journey can surface | DONE | 2026-09-23 | [wayfinder:research] Every IAM operation and field a post-setup screen can surface, split by actor, and whether a person photo exists at all. | |
| Inventory the reusable ores.web building material | DONE | 2026-09-23 | [wayfinder:research] What exists in ores.web today, and the exact pattern the three bootstrap journey prototypes use. | |
| Formalise the IAM vocabulary and the screen rules | DONE | 2026-09-23 | [wayfinder:research] Canonical IAM terms, and the screen-specification rules the journeys must obey. | |
| Identify the post-setup IAM journeys | DONE | 2026-09-23 | [wayfinder:grilling] The catalogue of post-setup IAM journeys, member and tenant-administrator separately, derived from user goals rather than from the entities. | |
| Decide what building material to reuse and what to decommission | DONE | 2026-09-23 | [wayfinder:grilling] Which existing ores.web artefacts serve the hand-crafted journeys, and which are retired. | |
| Decide how a prototype records a gap it exposes | ABANDONED | 2026-09-23 | [wayfinder:grilling] Where a modeling error or a missing server-side operation is recorded when a prototype exposes one. | |
| Create the user_journey document type | DONE | 2026-09-23 | [wayfinder:task] A document type that describes a journey before it is built: sections, template, codegen registration, metadata. | |
| Document every post-setup IAM journey | DONE | 2026-09-23 | [wayfinder:task] One high-level user-journey document per journey, grouped by topic, each with a wireframe and a NATS coverage assessment. | |
| Retire the TypeScript UI codegen | DONE | 2026-09-23 | 2026-09-23 | Remove codegen support for the TypeScript UI, keep the NATS protocol and domain facets, and reduce ores.web to a shell plus the transport core. |
5. Decisions
- Charted 2026-09-23. This map supersedes the screen-per-entity approach. The generated TypeScript stays as the data and API layer; the screens are hand-crafted from journeys. Which artefacts are decommissioned is Decide what building material to reuse and what to decommission's to settle.
- Charted 2026-09-23. The member's journeys and the tenant administrator's journeys are separate journeys with separate screens. The journey is the unit of design, so the journeys are identified before any prototype is specified.
- Charted 2026-09-23. Prototypes follow the bootstrap pattern: one
prototype/<journey>branch per journey, cut fromfeature/iam-screens-from-user-journeys. - Charted 2026-09-23. The map stops at accepted prototypes. Implementing the screens is a later story.
- Charted 2026-09-23. Coverage bar: every IAM operation a person can perform is reachable through some journey, and every non-secret field is visible or editable somewhere. A prototype also records the modeling errors and the missing server-side operations it exposes.
- Charted 2026-09-23. System-administrator cross-tenant operations are a later map.
- Inventory the IAM functionality a journey can surface:
account.image_idis a real profile picture intoores.assets, so a journey may show it. Contact details are one flat 1:1 child per account, not a hierarchy.login_infois current-state only and cannot carry a History screen. Accounts have no activate or deactivate, onlylocked. There is no forgot-password operation, no way for an administrator to end another account's session, and no subject for session statistics. The secrets arepassword_hash,password_salt,service_password_hash,totp_secret, every cleartext password field and every JWT. - Formalise the IAM vocabulary and the screen rules:
journey is already a project term – a server-stateful guided path
– and user is not a term at all, only one value of account type.
Screens are bound by
entity_specification.organdcomponent_specification.org, which live inprojects/ores.web/modeling/. Neither UI document mentions journeys or steps, so the journey shape has no written rule yet.ux_language.orgrequires an event-log screen to be called Audit, never History. - Inventory the reusable ores.web building material:
AccountsPage.tsxand the mainline prototype tree are both already deleted, so the two rival implementations named in story Implement every IAM entity in the web client are gone. All eleven IAM entities sit on the shared entity shell and the BFF routes are uniform. TheJourneyStepandJourneyPagerenderer survives on the prototype branches and in git history. - Create the user_journey document type:
a journey is documented before it is built. Journeys live under
doc/knowledge/journeys/<group>/journey_<slug>.org, grouped by logical topic, never by component. A PlantUMLsaltwireframe must not carry atitledirective. - Identify the post-setup IAM journeys: fourteen journeys in six topic groups. A journey is one person and one goal. The member's journeys and the administrator's journeys are separate. List, detail and history survive as primitives but are no longer per entity. Most journeys carry no server-side state.
- Document every post-setup IAM journey:
done. Fourteen documents, each with a rendered
saltwireframe and a coverage table. 105 claimed subjects were checked against the generated protocol and all exist; every id-link resolves. The exercise paid for itself: it found three server-side security defects, captured as Account secrets reach the browser in the accounts wire shape, Change-password ignores the current password and IAM handlers skip their permission checks, plus the design gaps the coverage tables record. - 2026-09-23, after auditing every
ores.iamdata type and responsibility: the corpus was incomplete. Every entity was covered, which is why the gap was invisible, but four message families had no journey at all —login_messages,signup_messages,bootstrap_messagesandreset_messages— andtenant_provisioning_messageshad none either. Seven journeys were added: Sign in, Sign up, First run, New tenant, New party, Register a service account and Retire or reset a tenant. The corpus is now 21 journeys in 8 groups, with Entry and Setup as new groups. Every journey carries* Related journeys, which is a UI requirement rather than an editorial one: each entry becomes a link on the screen. The three setup journeys carry* Prototypeand link the throwaway branchesprototype/first-run-journey,prototype/new-tenant-journeyandprototype/new-party-journey. The hub was renamed from "Journeys" to "User Journeys", because these are client-side journeys and a "journey" inores.workflowis a different thing. - Retire or reset a tenant found two more server-side defects, captured separately because they are defects rather than design gaps: the generic delete can terminate the system tenant (Delete can terminate the system tenant), because the guard lives in the lifecycle functions the generic path does not call; and suspension is not enforced anywhere on the sign-in path (Suspending a tenant does not suspend it), so a suspended tenant still admits its accounts.
6. Out of scope
- System-administrator cross-tenant operations: tenant create, update and delete, tenant provisioning, system bootstrap and system reset.
- The bootstrap and first-run journeys, which Prototype ORE Studio bootstrap in ores.web already covers.
- Service-only operations: service login, impersonation and the publish-from-dq triggers, except as notes in the gap log.
7. Result
Abandoned at sprint 25 close. Sprint 26 orders the work as: codegen sync for each module, then user-journey analysis, then UX. New journey and UX stories start clean after the codegen pass. This story is not carried forward. The journey documents that this story produced stay in place as input to the journey pass.