Task: Document the entry journeys' server side

Table of Contents

This page documents a task in the Implement the entry journeys in ores.web story. It captures the goal, current status, acceptance, and any notes or results.

1. Goal

An architecture page that explains the server side of the two Entry journeys, with interaction diagrams rather than prose alone. It states which layer owns what, the order in which the server refuses a sign-in, the branch a registration takes, the code each refusal carries, and where every piece of state lives, so the implementation is built against a drawn contract instead of a paragraph.

2. Status

Field Value
State DONE
Parent story Implement the entry journeys in ores.web
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-09-29

3. Acceptance

  • A sequence diagram per interaction: the door's policy read, sign in, and sign up.
  • Each diagram's source is committed beside it as a .puml, and the page says how to regenerate it.
  • The order in which the server refuses a sign-in is stated, and it matches the code that runs it.
  • Every refusal the two subjects can answer with is in one table, with its code.
  • The page says where each piece of state lives and what survives a reload.
  • The page links the policy document rather than restating its decisions.

4. Plan

  1. Read the login path as it is: the handler, account_operations_service::login, and the branch on the party count.
  2. Draw the target, not the current state: the flag reads, the destination resolution, the pending branch, and the codes.
  3. Draw the door's policy read first, because it is what tells the screen whether to offer a form.
  4. Put the branch order in prose beside the diagram, because the diagram shows the order but not why it is that order.
  5. Collect every refusal into one table, since a code that exists in two places drifts.
  6. Render each diagram with plantuml -tpng and commit the PNG beside its source.

5. Measurements

What Value Command Commit
Interaction diagrams 3 ls doc/knowledge/journeys/entry/entry_*_sequence.puml 3e39fc8337
Refusal codes 13 the page's codes table 3e39fc8337
Layers the page names 7 the page's layers table 3e39fc8337

6. Notes

  • The diagrams are sequence diagrams, which the tree had not used before; the conventions for class and ER diagrams are on PlantUML class diagram conventions, and the file and caption conventions are shared with them.
  • The pending and account_pending branches are drawn even though nothing implements them yet. A diagram that only drew what exists would not be a target state, and the missing pieces are exactly what the implementation is for.
  • The tenant resolution is drawn twice, once per journey, because the two differ: sign in falls back to the handler's own tenant, and registration refuses rather than falling back, since the system tenant is not a destination a person can be given.

7. Test Scenarios

Manual QA scenarios (scaffolded via compass add test_scenario) that verify this task. Link new ones here as they're created; the scenario doc itself links back via its "Verifies task" field.

Scenario State Notes
     

8. PRs

PR Title
#2423 [iam,web] Implement the entry journeys' registration door

9. Review

Comment summary File Decision Notes
       

10. Result

The entry journeys is the page, at doc/knowledge/journeys/entry/. It is named and shaped like its first-steps counterpart, the tenant provisioning journey: a lede paragraph, one detail section per part of the path, a captioned diagram per interaction with its source beside it, and a See also. It carries three sequence diagrams, each with its .puml source beside it: the door's policy read, sign in with its six-branch order, and sign up with the gate, the destination and the two endings.

Two tables carry the weight. Where the state lives names each piece of state and what survives a reload, which is what makes the browser's cookie and the BFF's session map distinguishable from the server's session row. The refusal codes collects all thirteen codes the two subjects can answer with, so a screen branches on a value and not on a sentence.

The page states plainly which of its flows do not exist yet: the live sign-up path reads no flag, a registration that resolves to no tenant lands in the system tenant, and neither response carries a code. Those are the first implementation tasks, and the diagrams are drawn to the target rather than to what runs today.

Emacs 29.3 (Org mode 9.6.15)