Reading diagrams / Topic 31 of 42
What happens when: one route as a tree
The rule
The system map draws every route at once. A what-happens tree draws one route, top to bottom, and every way it can go. The request comes in at the top, at an arrowhead under the route's name, and each path runs down to what the request gets back.
Yichus computes a tree for every route, from the code. An author can also describe a route in a scenario: a short file beside the code that gives the route a title, gives some of its parts plain names, and writes claims about its paths, such as not writes docs on one path. The line above the tree, such as “entries · 3 of 4 described by a scenario” on notes-api, counts the routes that have one. The scenario adds names and claims; it never changes the tree. Under the arrowheads, a dashed line such as “1 entry not described” opens to the routes no scenario describes, each drawn faint behind a hollow dashed arrowhead. Faint is not struck: the code serves those routes and their trees are computed like the others; only no requirement was written for them.
The marks are the map's. Every effect on a path is a ring, with its verb beside it. A blue ring touches the database: hollow to read, filled to write or create a row, with the table's name after the verb; mint, which makes a new id for a table, is blue too. A purple ring calls the language model, and an orange ring reaches the network. A grey ring is an effect on no table, such as a read of the database's clock, or runs, which is code Yichus could not open. A branch the code takes is a fork: a chevron with what it tests, and one arm per case. The longest path runs straight down. An arm that ends at once is a short stub to its side, read left to right: the case, an arrow, and the ending.
Every path ends in a cap. A ringed dot is an answer: Done, or a value the route returns, such as “Denied” or “Allowed”. Denied is a value the reply carries, not an HTTP status. A bar across the line is a refusal: refused, its kind, its HTTP status, and the code the reply carries, as in “refused NotFound 404 no_such_doc”. When the route answers with what an effect handed back, the cap says so in the effect's words: “what write · notes gives back”. Any other answer keeps the code's own name for it.
The tree draws everything the route runs: its declared guard, its wrappers, the platform's transaction, and its own code. Every branch and every ending they can reach is drawn. So no path of the route ends in a way the tree does not show, and a ring that is not on a path is not done on it. The one exception is a grey runs ring: Yichus could not open that code, so whatever it does is not drawn. The last of these topics comes back to it. Before the route runs, the platform itself also refuses a body it cannot read (400) or one too large (413), and a key it cannot verify or does not allow on that route (401 or 403); it answers 500 when code fails. Those answers are the same for every route and are not drawn.
Yichus checks each claim on its path and marks the ending with a count: ✓ 2 is two claims that hold there. On a route with claims, an ending marked no claim has none written on it, which is neither a pass nor a fail; the code can still end there. A ring label struck through beside a stub, such as “write · docs”, is a write a claim says does not happen on that path, checked: that write is not done. Colour, such as a red or green cap, also comes from checks. The last of these topics explains it.
Some steps come from shared code: a wrapper, or the platform's sign-in check. They are folded into shaded boxes, which the next topic opens. For now, read a box's stubs like any other: “not signed in → refused 401” is an ending.
Under the tree, one line for each table the route touches says what a row of it holds, by its checked type: “docs holds Doc(author: String, body: String)” in shared-docs. The fields come from the type, so a field that is not listed is not in the row. What a field means is still the author's word.
Words in italic, such as “You save a document” or “is it yours?”, are the author's names for parts Yichus computed. A name for an ending sits under its cap, or on the arm that leads to it, as “your edit is saved” does. Use them to find your way; they are not evidence. The forks, rings and caps are.
- A refusal cap with the status confirms a path is refused that way; no such cap anywhere rules it out. A ringed dot, such as Denied, is an answer, not a refusal.
- A filled ring on the path to an ending confirms a write on the way; none rules it out.
- A field in the line under the tree confirms a row holds it; a field not listed rules it out.
- Italic words are names, not evidence.
- A faint entry rules out that a scenario describes it, and nothing else: it is still a route the code serves.
notes-api /notes/add: one sign-in check and one path.
Loading the notes-api tree.
shared-docs /docs/edit: a route with two forks.
Loading the shared-docs tree.
policy-docs /docs/write.
Loading the policy-docs tree.
How to read this: what each mark in these pictures means
Loading the worked examples and practice.