Diagrams

A visual language: the kinds of picture an agent draws in its replies, so the author reads at a glance what words would take a page to say. For each kind: what it shows, when it fits and when it does not, its parts, how it is drawn. Which kind for which data: the chooser in the guide Data as a picture.

45 diagrams

45 diagrams

ALLAt a glance

USEHand them to an agent

Paste this into a project's CLAUDE.md or AGENTS.md: it is read at every start, so the agent draws its pictures this way without being told. The agents' guides hand these over too. To give one kind in a conversation, copy it with its Copy for an agent button.

Draw the pictures in your replies the way these diagrams say:
- Sequence diagram: who talks to whom: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/sequence.md
- One case: today beside fixed: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/case.md
- Annotated screen: where on the screen: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/screen.md
- State diagram: what moves a thing between its states: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/state.md
- Flywheel: what feeds itself: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/flywheel.md
- Flowchart: what is decided where: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/flowchart.md
- Swimlanes: who does each step: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/swimlanes.md
- Step tree: a process as its stages and their small steps: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/steptree.md
- Known and open questions: how it works, and the gaps: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/questions.md
- Cause tree: why it happened: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/causetree.md
- Timeline: what happened when: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/timeline.md
- Chronology: what one user did, in order: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/chronology.md
- Event plot: who did what, when: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/eventplot.md
- Milestone track: where a goal stands: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/milestone.md
- Plan graph: what waits on what: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/plangraph.md
- Roadmap: what is planned when: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/roadmap.md
- Kanban board: where each piece of work is: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/kanban.md
- Priority quadrant: what to do first: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/quadrant.md
- Container sketch (C4): where the parts run: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/containers.md
- Entity-relationship: what data there is and how it links: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/entities.md
- Class diagram: the types of a program and how they link: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/class.md
- Breakdown tree: a whole split into its parts: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/breakdown.md
- Status dashboard: where each part stands: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/dashboard.md
- Line chart: a number over time: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/linechart.md
- Bar chart: how much of each: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/barchart.md
- Pie chart: shares of one whole: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/piechart.md
- Heatmap: when it happens: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/heatmap.md
- Versions: which version runs where: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/versions.md
- Cloud architecture diagram: what runs where: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/cloud.md
- Network diagram: addresses, ports, who may connect: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/network.md
- Layered diagram: the tiers a request passes: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/tiers.md
- Isometric diagram: the system as a model: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/isometric.md
- Service map: what talks to what, live: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/servicemap.md
- Sankey diagram: where the traffic goes, how much: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/sankey.md
- Trace waterfall: where one request spends its time: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/waterfall.md
- Data flow diagram: where data crosses a trust boundary: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/dataflow.md
- Dependency matrix: every link in a grid: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/matrix.md
- Call graph: which function calls which: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/callgraph.md
- Data flow of a script: files in, steps, files out: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/pipeline.md
- Module graph: which file needs which: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/modules.md
- Change map: what a change touches: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/changemap.md
- Before and after: what a change does to a system: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/delta.md
- Flame graph: where one run spends its time: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/flame.md
- Code map: how big each part is: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/treemap.md
- Diagram Design: 25 kinds this page has no guide for: https://raw.githubusercontent.com/vbarbarosh/rules/main/diagrams/diagramdesign.md

01Sequence diagram: who talks to whom

The course of events: the parts of a system as columns, what they send each other as arrows, top to bottom in time order. A request, a failure, a retry or a fix reads in one look, and today beside proposed shows only the change.

Its parts: participants with an icon above the name, dashed lifelines under them, messages as arrows top to bottom; blue a request, green a success, red a failure, grey what stays the sameIts parts: participants with an icon above the name, dashed lifelines under them, messages as arrows top to bottom; blue a request, green a success, red a failure, grey what stays the same

Fits when

  • Parts pass something along: a person, a browser, a server, a database, a job, an outside service.
  • The order matters: a failure, a retry, a timeout, a race; what happens where, and after what.
  • A fix changes the course: a step added, an event dropped, a call moved. Today beside proposed.

Not when

  • One part alone, nothing passed between: its states are a state diagram, its decisions a flowchart, its look a screenshot.
  • The order does not matter, only where the parts run or how the data links: a container sketch or an entity-relationship diagram.
  • The times matter more than who: a timeline.
  • Too many at once: more than five participants or ten messages. Split it in two, or say it in a table.
  • A change the author sees on screen: screenshots before and after say it better.

How it is drawn

  1. Participants: one column each, a plain icon above a short name. A person, a laptop or browser, a server, a database cylinder, a clock for a cronjob, a page for another writer or a file, a cloud for an outside service, a warning triangle for an error tracker. The icons carry most of the reading; the names stay short.
  2. Lifelines: a dashed vertical line under each participant.
  3. Messages: arrows between lifelines, top to bottom in time order, each with a few words. A request blue, a failure or an error red, a success or an answer green, what stays the same grey. A note on a step sits on its arrow: 13:05 INSERT … SELECT, 403 plan limit.
  4. A step on a clock or a loop (every minute, a retry until it works): a low rectangle with well-rounded corners (48 high for 18-pixel words, its radius a third of that), spanning the lifelines it involves. One arrowhead sits on its top edge pointing right, one on its bottom edge pointing left, so it reads as a cycle. Its period is written inside (every minute); what it checks and does goes beside it, right of the lifelines: alive? writing?, then gone, silent 30 s or older: started again. The loop is orange, the waiting colour; its words keep the usual text colours.

Turned down: a straight arrow reads as one call, not a repeat; an ellipse reads poorly; a UML loop frame around the steps, its tag in the corner, stretches a compact diagram into a long one. A refresh sign, a filled rectangle with an arrow on every side and a path out of a lifeline and back came second. 5. Today beside proposed (or before beside after, today beside made): two framed panels, tagged, the same participants in the same order, so only the change differs. The change is drawn, not described: an event crossed out, a step added, a participant greyed. 6. Around it: a title line with the item's id and what it is, one line of context under it (where, how often), one line of proof under the panels. 7. In the app's colours, and drawn for the width it is shown at: its words no smaller than the text around it.

S4, a plan limit: today the browser sends an error event to the tracker after the upgrade window; proposed, no eventS4, a plan limit: today the browser sends an error event to the tracker after the upgrade window; proposed, no event

Examples

servermon kept running by the agent: systemd starts the agent, the agent writes and starts servermon, which writes a JSON line a second and keeps running when the agent restarts; every minute, in an orange rounded loop, the agent asks alive? writing? and starts it again if gone or silent 30 sservermon kept running by the agent: systemd starts the agent, the agent writes and starts servermon, which writes a JSON line a second and keeps running when the agent restarts; every minute, in an orange rounded loop, the agent asks alive? writing? and starts it again if gone or silent 30 s U2, an upload retried: before, a passing 500 fails the export; after, the job waits and puts the file again, and the export is doneU2, an upload retried: before, a passing 500 fails the export; after, the job waits and puts the file again, and the export is done D1, a deadlock in a cronjob retried inside the run: today an error event and the rows a run later; made, once more at once and no eventD1, a deadlock in a cronjob retried inside the run: today an error event and the rows a run later; made, once more at once and no event D1, the same deadlock with no change proposed: the retry drawn as what would be done only if it growsD1, the same deadlock with no change proposed: the retry drawn as what would be done only if it grows E7, the exporter's upload: today a failed upload is an error event; proposed, retried up to 3 times, the file arrives, no eventE7, the exporter's upload: today a failed upload is an error event; proposed, retried up to 3 times, the file arrives, no event One upload through a render service: the browser gets a signed URL from the API through Cloudflare, puts the file straight to S3, asks for a render; the API queues it and answers 202; later SQS starts Lambda, which renders to S3 and marks the job doneOne upload through a render service: the browser gets a signed URL from the API through Cloudflare, puts the file straight to S3, asks for a render; the API queues it and answers 202; later SQS starts Lambda, which renders to S3 and marks the job done
In the author's words
  • Pictures that are clear to me; I'd like agents to make pictures of this kind in their messages: it makes them easier to understand. And especially the icons. (2026-10-13 15:29)
  • It makes sense to make one diagrams page, where we add diagrams, describe what they are, when they fit and when they do not: a visual language of sorts. This is a good example of a diagram for the course of events. (15:50)
  • This picture shows a loop: the part of a process where something is polled, something is done all the time. Loops can be drawn this way. (2026-10-18 21:12)
sequence.md

02One case: today beside fixed

One real request, its answer today beside its answer with the fix: the question on top, two framed panels under it, red for today and green for the fix. Big numbers and what works and what is missing follow, so the one case stands for the rest.

A shop's help chat asked how much shipping to Canada is: today a vague reply, not covered; with a shipping-rates article, a table of four rates, answered; then the numbers, what works and what is missing, by effortA shop's help chat asked how much shipping to Canada is: today a vague reply, not covered; with a shipping-rates article, a table of four rates, answered; then the numbers, what works and what is missing, by effort

Fits when

  • One real request shows the gap: a question a help chat cannot answer, a call that fails, a search that finds nothing.
  • The fix is content or data, and its effect is the answer itself: a table, a value, a reply.
  • The author must decide what to do next: the case convinces, the lists say what else is open and what each costs.

Not when

  • The course of messages between parts changes, not the answer: a sequence diagram, today beside proposed.
  • Many parts at once, each with its state: a status dashboard.
  • A change on screen: two screenshots, before and after.

How it is drawn

  1. The question: quoted big in a soft blue box, where it was asked and when in grey beside it. The real words, not a summary.
  2. Today: a red frame, a red cross in a circle and "Today:" with why it fails; inside, the real answer as given and a red tag ("not_covered").
  3. With the fix: a green frame, a green tick and "With" and the fix; inside, the answer it would give and a green tag ("answered"). Values go in a small table, a line between rows.
  4. A verdict under each: in bold, red or green, what the panel shows; a line under it says where the real answer was seen, or in amber what is still to confirm.
  5. KPI cards: four big numbers for the whole, each a few words of what it counts; red or amber for a count that stands for a gap.
  6. Two lists: "Works" with green ticks; "Missing, by effort" with a pill per item, red for work to do (small, medium), amber for what waits on an answer (wait, check, decide). The item the case is about first, in bold.
  7. Ticks and crosses are drawn as paths, not typed as glyphs, so every font shows them alike.
In the author's words
  • Add all of them, only make them anonymous: nothing about the company or anything personal. (2026-10-14 23:56, of the visual-lang drafts)
case.md

03Annotated screen: where on the screen

A plain sketch of a screen, grey blocks and a few real labels, with an amber number on each spot that changes; beside it a numbered list says what changes at each. The reader sees where the change is before reading what it is.

The checkout page sketched twice, while paying and with the card declined, in grey blocks with real labels for Checkout, the total of $84.00, the coupon field and the Pay button; amber number 1 sits by the coupon field under the total, 2 by the Pay button, faded, with a spinner and the word Paying, 3 by a red Card declined message right above the blue Pay button; beside the sketches a list says 1 the coupon field moves from the top of the page to under the total, 2 Pay shows a spinner and stays disabled until the bank answers, 3 the error shows right above the button, not at the top of the page; a Now box sums up the three changesThe checkout page sketched twice, while paying and with the card declined, in grey blocks with real labels for Checkout, the total of $84.00, the coupon field and the Pay button; amber number 1 sits by the coupon field under the total, 2 by the Pay button, faded, with a spinner and the word Paying, 3 by a red Card declined message right above the blue Pay button; beside the sketches a list says 1 the coupon field moves from the top of the page to under the total, 2 Pay shows a spinner and stays disabled until the bank answers, 3 the error shows right above the button, not at the top of the page; a Now box sums up the three changes

Fits when

  • A change to a screen: a field moves, a button gets a new state, a message shows in a new place.
  • The question is where: words alone would say "the error moves up" and leave the reader to guess from where to where.
  • No screenshots yet: the change is planned, or the screen is still being built.

Not when

  • Real screenshots exist before and after: one case, the screenshots side by side.
  • The parts of a system, not of a screen: a container diagram.
  • A thing's states and what moves it between them: a state diagram.

How it is drawn

  1. The sketch: the screen as a framed wireframe, its parts as plain grey blocks; only the parts that matter get real labels, such as the total, a field's placeholder or a button's text.
  2. States: a frame per state when the change shows in one state only, such as while paying or after an error; the state's name in bold above its frame. One frame when the state does not matter.
  3. The numbers: an amber circle with a number beside each spot that changes, in the margin of the frame, never over a label; each number once only, in the frame where it shows best.
  4. Colour in the sketch: grey for what stays; the changed parts in their real colours, such as a blue button or a red error.
  5. The list: beside the sketch, the same amber numbers in order, each with what changes in bold and a line or two of why under it.
  6. Now: a blue box under the panel says in one sentence all the changes together.
In the author's words
  • Good, add them all. (2026-10-16 21:00)
screen.md

04State diagram: what moves a thing between its states

The states a thing has and what moves it from one to the next: a card's steps, a message's life, a job's run. Each state is a box; each arrow says what moves it.

A sign-in card: from signed out through the code and the wait to saved; a refused code goes back for a new link, an unread token is shown in its windowA sign-in card: from signed out through the code and the wait to saved; a refused code goes back for a new link, an unread token is shown in its window

Fits when

  • A thing has a few states, and the question is how it gets from one to another, or why it stays in one.
  • A state can be reached by more than one way, or left by a way that goes back.
  • A bug is a wrong state: stuck, skipped, or reached from where it should not be.

Not when

  • The order of calls between parts is the question: that is a sequence diagram.
  • One decision with its answers, no lasting state: a flowchart.
  • More than about eight states: draw the part that matters, and say the rest.

How it is drawn

  1. States: rounded boxes, a short name each. Coloured by what they mean: blue a step on the way, green the end that is wanted, orange one that needs a look.
  2. Transitions: the project's arrows, grey, each with the few words that move it (a click, an answer, a timeout).
  3. The start: a filled dot with an arrow into the first state.
  4. Around it: a title with the thing's name, one line of context, one line under it saying how to read it.
In the author's words
  • Add all five. (2026-10-13, as the note of 16:29 quotes it)
  • The new diagrams, I think, should go on the pages too, only in the same format as the other diagrams; and mind the arrows: take the ones the project uses. (16:33)
state.md

05Flywheel: what feeds itself

A loop that grows as it turns: each stage feeds the next, and the last feeds the first, so the next turn starts bigger. A data flywheel is the common case: use makes data, data makes a better model, a better model brings more use. Also called a virtuous cycle or a reinforcing loop.

Search that learns from its users: more users, more searches, clicks logged, clicks as labels, model retrained and a better ranking, evenly on one circle, each with its number; clicks as labels in amber, only 15% usable, the weak link; seed labels by hand come in from outsideSearch that learns from its users: more users, more searches, clicks logged, clicks as labels, model retrained and a better ranking, evenly on one circle, each with its number; clicks as labels in amber, only 15% usable, the weak link; seed labels by hand come in from outside

Fits when

  • Growth feeds itself: more users bring more data, more data a better product, a better product more users.
  • The question is where it is slow: which stage holds back every turn after it.
  • A start from outside: what was put in by hand to get it turning, seed data or a launch.

Not when

  • A thing goes round its states, nothing grows: a state diagram.
  • A step repeats on a clock (every minute, a retry): the loop on a sequence diagram.
  • How much each stage moves on: a sankey, its bands as wide as their share.

How it is drawn

  1. Stages: four to six boxes evenly on one circle, clockwise, the outcome on top; each with its name and its number now (40k a day).
  2. Arrows: blue and bold, arcs of that same circle, each from one stage into the next; the last back into the first. Nothing bends off the circle: a wheel that wobbles reads as broken.
  3. The weak link: the stage that turns slowest in amber, said in a line under the ring.
  4. From outside: what started it or still feeds it, a grey dashed box with its arrow into the stage it feeds.
  5. The middle: how long one turn takes.
In the author's words
  • do we have "data flywheel" diagram? (2026-10-20 21:45)
  • 🚀 add it (21:53)
flywheel.md

06Flowchart: what is decided where

The decisions one action goes through, in order: each question a diamond, each answer its own arrow, each outcome a box.

What Paste decides: a token, running, this link; each answer leads to its own outcomeWhat Paste decides: a token, running, this link; each answer leads to its own outcome

Fits when

  • One action branches: a click, a request or a job that does different things depending on what it finds.
  • The question is which way it went, and why: an outcome nobody expected.
  • A rule has cases, and every case must be seen at once.

Not when

  • A thing lives through states and comes back to them: a state diagram.
  • Several parts take turns: a sequence diagram.
  • More than about six questions: split it, or say it as a table of cases.

How it is drawn

  1. Steps: rectangles; the one that starts it darker.
  2. Questions: diamonds, a few words ending in a question mark, the words inside the diamond.
  3. Answers: the project's arrows, one per answer, each labelled (yes, no, or the value).
  4. Outcomes: boxes coloured by what they mean: green done, orange refused or spent, blue the way on.
  5. Left to right for the main way, down for the answers that leave it.
In the author's words
  • Add all five. (2026-10-13, as the note of 16:29 quotes it)
  • The new diagrams, I think, should go on the pages too, only in the same format as the other diagrams; and mind the arrows: take the ones the project uses. (16:33)
flowchart.md

07Swimlanes: who does each step

A process as its steps in order, a lane per actor, each step a box in the lane of who does it. An arrow leads from each step to the next, and it crosses lanes where the work changes hands. The reader sees who holds the work now and which hand-off waits on them.

A refund in four lanes, Customer, Support, You the shop owner, and Payment service: the customer asks for a refund and support checks the order, both done in green; the amber arrow hands it to you, and Approves the refund is amber, waiting 2 days; then, dashed grey and still to come, the payment service pays it back and support e-mails the customer; a Now box says the refund waits on you to approveA refund in four lanes, Customer, Support, You the shop owner, and Payment service: the customer asks for a refund and support checks the order, both done in green; the amber arrow hands it to you, and Approves the refund is amber, waiting 2 days; then, dashed grey and still to come, the payment service pays it back and support e-mails the customer; a Now box says the refund waits on you to approve

Fits when

  • Several people or services share one process, each doing a part of it in turn.
  • The question is who does what, and where the work passes from one to another.
  • A hand-off is slow or stuck, and the reader sees whose lane it waits in, often their own.

Not when

How it is drawn

  1. Lanes: one row per actor in one framed panel, the name in bold at the left, thin lines between the rows; two to five lanes, the reader's own named "You".
  2. Steps: one box per step, left to right in order, each in the lane of who does it; a verb in bold and a few words under it.
  3. Arrows: from each step to the next, down or up out of the box and then right into the next one; the arrowheads touch the boxes.
  4. Colours: green for steps done, grey dashed for steps to come. A hand-off that waits on the reader is amber, its arrow too, and says for how long.
  5. Now: a blue box under the panel says in one sentence who holds the work and what it waits on.
In the author's words
  • Good, add them all. (2026-10-16 21:00)
swimlanes.md

08Step tree: a process as its stages and their small steps

A process read top to bottom: one trunk down the left, a branch per stage, and under each stage its small steps as leaves. Every node starts with an emoji: the stage's says who or what does it, the step's what it does. Each stage has its colour, and the trunk takes it as it passes. A blank line between stages, none inside one, so the eye finds the stages before it reads a word. A cost or a warning stands at the right of the row it belongs to; the total closes the tree.

Resize, one banner into many sizes, as a step tree: on top the board, where you tick sizes and drop the source banner, every size its own chat turn, the first size of a kind leading; then the start of a size, purple, where the canvas, the design's kind and the ask are made; Round 1 and Round 2 to the model, blue, with their costs at the right; the layout in code, amber, free, with backgrounds, pinned elements, blocks and texts, a red warning that the shoe stays small; the editor takes a picture of each scene, green; Rounds 3 to 10 look, measure and patch until done; Save, green, a new banner per size; and the total, one size 4 to 6 cents, four sizes 20 centsResize, one banner into many sizes, as a step tree: on top the board, where you tick sizes and drop the source banner, every size its own chat turn, the first size of a kind leading; then the start of a size, purple, where the canvas, the design's kind and the ask are made; Round 1 and Round 2 to the model, blue, with their costs at the right; the layout in code, amber, free, with backgrounds, pinned elements, blocks and texts, a red warning that the shoe stays small; the editor takes a picture of each scene, green; Rounds 3 to 10 look, measure and patch until done; Save, green, a new banner per size; and the total, one size 4 to 6 cents, four sizes 20 cents

Its parts, numbered where they are:

The parts of a step tree on a short tree: 1 the title, an emoji then from and to; 2 a stage, who or what does it, in its colour; 3 the trunk, one line in the colour of its stage; 4 the steps, a leaf each with an emoji first; 5 a blank line between stages, none inside one; 6 the tags at the right, a cost, free, a warning; 7 the total, the sum on the last lineThe parts of a step tree on a short tree: 1 the title, an emoji then from and to; 2 a stage, who or what does it, in its colour; 3 the trunk, one line in the colour of its stage; 4 the steps, a leaf each with an emoji first; 5 a blank line between stages, none inside one; 6 the tags at the right, a cost, free, a warning; 7 the total, the sum on the last line

Fits when

  • A process of a few stages, each of a few small operations: what a feature does from the click to the result, a job round by round, a build step by step.
  • Different hands do the stages: the user, a model, plain code, an editor; the emoji of the stage says which.
  • A step has a price or a catch worth reading beside it: what a round costs, where it waits, where it goes wrong.

Not when

  • One action branches on what it finds: a flowchart.
  • Who holds the work, and where it changes hands between people: swimlanes.
  • A whole and its parts with no order between them: a breakdown tree.
  • What happened when, with its times: a chronology or a timeline.
  • Files in and files out of a script: a pipeline.

How it is drawn

  1. The title: on top, an emoji, the name of the process and what it turns into what ("Resize: one banner → many sizes"); in monospace, as the whole tree.
  2. The trunk: one line down the left, from under the title to the last stage; it takes the colour of the stage it has just passed.
  3. Stages: a branch each off the trunk, in order; an emoji for who or what does it (👤 the user, 🤖 a model, ⚙️ code, 📸 the editor, 🔁 a loop, 💾 save), then its name in bold, in its colour: blue for the user and the model, purple for the start, amber for code, green for what comes out.
  4. Steps: the leaves of a stage, each a line with its own emoji then a few words; a step of a step one level deeper, three levels at most; a long line wraps under its own words, not under the emoji.
  5. Blank lines: one between stages, none inside a stage: the gap is what tells one stage from the next.
  6. Tags at the right: aligned on one right edge, on the row they belong to: a cost in green with 💵, free in blue with 🆓, a warning in red with ⚠️ and its words.
  7. The total: the last line, 💰 and the sum: one case and many, and where the number comes from.
  8. Emoji: one per node, never two; the same emoji means the same thing throughout (📐 a layout, 📸 a picture, ✅ done), and a reader who knows none of them still reads the words.
In the author's words
  • Look at this picture; I like it very much. It is a diagram of its own kind too, for small step-by-step operations. The emoji are a must, and the different colours; and the blank lines between some of the blocks matter a lot. (2026-11-03 07:33)
  • I like the name, step tree, so let us add it. One thing: you showed the picture as a legend, and a legend is too short to show the whole power of this approach, all its expressiveness. Keep the legend, but there must be an example too, at least the one I sent, and the example must be the more expressive one. (07:44)
steptree.md

09Known and open questions: how it works, and the gaps

How something works, stage by stage, with the facts read from the code and the questions no one can answer yet, each where it arises. A panel per stage, left to right; the questions inside the panel they belong to; a row of big numbers under them.

Gift cards in a small shop: buying, spending and expiring as three green panels of facts; amber questions inside them, a refund, two orders at once, a return, a reminder, the law; 1 240 cards sold, 3 400 left unspent, 5 open questions, 0 reminders sentGift cards in a small shop: buying, spending and expiring as three green panels of facts; amber questions inside them, a refund, two orders at once, a return, a reminder, the law; 1 240 cards sold, 3 400 left unspent, 5 open questions, 0 reminders sent

Fits when

  • Someone asks how a thing works, and part of the answer is "no one knows yet".
  • The facts and the gaps must be told apart: what the code says, beside what a person still has to decide or find out.
  • A meeting needs its questions: each one shown where it bites, not in a list at the end.

Not when

How it is drawn

  1. The title says both halves: "how it works, and what we don't know", and the line under it says what green and amber mean.
  2. Stages: a green panel each, numbered "1 · Buying", left to right, an arrow between them; a few short lines of facts, the key figures in bold.
  3. Questions: an amber note inside the panel where the question arises, a thick amber bar on its left; the question in bold, and in grey what is known so far.
  4. Big numbers: a row under the panels, each a number and two lines of what it counts; amber or red when it stands for a gap.
  5. Facts only in green: a line in a green panel is read from the code or a log; a guess is a question, and goes in amber.
In the author's words
  • Add all of them, only make them anonymous: nothing about the company or anything personal. (2026-10-14 23:56, of the visual-lang drafts)
questions.md

10Cause tree: why it happened

The failure on top, its causes below it as a tree: each row down says why the row above happened. The root cause is amber, the fix green beside it, and the causes that were checked and ruled out stay in grey with the reason. The reader sees why it broke, what one change ends it, and what was already looked at.

Why customers were charged twice: a red box on top says customers were charged twice, 38 orders on 10-14; below it, the pay button sent twice, two requests 0.4 s apart, beside two grey dashed boxes ruled out, the provider retried (one call each) and a reload resent it (no reloads); below that, the button stays enabled for the 1.8 s it waits, beside a grey box ruled out, the mobile app retried (all 38 on web); at the bottom the root cause in amber, the spinner shows only after the reply, joined by a green line to the fix, disable the button on the first click and show the spinner at once; a Now box says a second click gets through while the button waitsWhy customers were charged twice: a red box on top says customers were charged twice, 38 orders on 10-14; below it, the pay button sent twice, two requests 0.4 s apart, beside two grey dashed boxes ruled out, the provider retried (one call each) and a reload resent it (no reloads); below that, the button stays enabled for the 1.8 s it waits, beside a grey box ruled out, the mobile app retried (all 38 on web); at the bottom the root cause in amber, the spinner shows only after the reply, joined by a green line to the fix, disable the button on the first click and show the spinner at once; a Now box says a second click gets through while the button waits

Fits when

  • Something broke and the question is why, down to the one cause a change would end.
  • Several causes were suspected, and the reader sees which were checked and why they are out.
  • The fix follows from the cause, and the reader sees it is aimed at the root, not at the failure on top.

Not when

  • The order of events in one request: a sequence diagram; what happened when, from a log: a timeline.
  • The cause is not found yet: what is known and what is still open, a questions diagram.
  • One real request today beside the same with the fix: a case.

How it is drawn

  1. The failure: a red box on top, what broke in a few words and, under it, how much or since when.
  2. The causes: one box per row down, each the "because" of the box above it, its name in bold in two or three words and under it what shows it; dark lines join the chain from the failure to the root.
  3. Ruled out: a grey box with a dashed border beside the cause it was checked against, its name in grey and "ruled out:" with the reason; grey dashed lines join it.
  4. The root cause: the last box of the chain, amber with an amber border, its name in bold and "the root cause" under it.
  5. The fix: a green box beside the root cause, joined to it by a green line, the change in bold.
  6. Now: a blue box under the tree says in one sentence why it broke and what fixes it.
In the author's words
  • Good, add them all. (2026-10-16 21:00)
causetree.md

11Timeline: what happened when

Events at their moments, from a log: one line of time, left to right, each event a dot with its time and a few words.

A sign-in second by second: started, link opened, code typed, ended with the token unread, then Paste starting a new sign-inA sign-in second by second: started, link opened, code typed, ended with the token unread, then Paste starting a new sign-in

Fits when

  • A log tells it: times matter, and the gaps between them.
  • The question is what came before what, or what happened while something else waited.
  • One event went wrong among others that did not.

Not when

  • Who sent what to whom matters more than when: a sequence diagram.
  • The times do not matter, only the order of states: a state diagram.
  • Hundreds of events: pick the few that tell it, and say how many were left out.

How it is drawn

  1. The line of time: one grey line, left to right.
  2. Events: a dot on the line, a stem to its label, the time in bold above a few words. The labels go above and below in turn, so close events do not collide.
  3. Colours: blue for what went as it should, green for an end that is wanted, red for what went wrong.
  4. What went wrong gets a note of its own, in red, under its event.
In the author's words
  • Add all five. (2026-10-13, as the note of 16:29 quotes it)
  • The new diagrams, I think, should go on the pages too, only in the same format as the other diagrams; and mind the arrows: take the ones the project uses. (16:33)
timeline.md

12Chronology: what one user did, in order

Steps in the order they happened, each with its time, at even distances: the order and the times count, not the gaps between them. A long gap is cut short, its length written on the cut.

One user's seven steps evenly along a line, from opening the pricing page on Monday to upgrading to Pro on Tuesday, the 23-hour night cut shortOne user's seven steps evenly along a line, from opening the pricing page on Monday to upgrading to Pro on Tuesday, the 23-hour night cut short

For more steps than a strip holds, the same chronology goes down a line, the times on the left, one row per step.

The same seven steps as a list down a vertical line, the times on the left, the 23-hour night cut short between the fifth and the sixthThe same seven steps as a list down a vertical line, the times on the left, the 23-hour night cut short between the fifth and the sixth

Fits when

  • One actor's steps: a user, a job, an agent; first this, then that.
  • The order matters more than the distances: a minute and a night between two steps take the same room.
  • Steps far apart in time: minutes, then a day, then a week; a timeline would squeeze the short ones flat.

Not when

  • The gaps are the story: a wait, a timeout, what happened while something else waited: a timeline.
  • Several parts pass something between them: a sequence diagram.
  • The states matter, not the steps: a state diagram.

How it is drawn

  1. The line: one grey line, left to right in the strip, top to bottom in the list.
  2. Steps: a dot each, at even distances. In the strip, a stem to its label, the time in bold above a few words, the labels above and below in turn; in the list, the time on the left, the words on the right.
  3. Colours: blue for each step, green for the end that is wanted, red for a step that went wrong.
  4. A long gap: the line cut by two slanted amber strokes, its length written in amber on the cut.
  5. Strip or list: a strip up to seven or eight steps; more, the list.
In the author's words
  • A new term, chronology. Make a diagram for it and show several variants of such diagrams. (2026-10-19 10:20)
  • A chronology diagram can probably show a user's actions over time: first they did one thing, then another, then a third. (10:24)
  • Chronology: C, the strip. (10:26)
  • I see the definition of chronology, but I don't see chronology among the diagrams. There should be a diagram for chronology. (18:51)
  • And about chronology: I remember there were two views of it; on the page I see only one. (18:52)
chronology.md

13Event plot: who did what, when

Every event of many actors at its moment: a lane per actor, a tick per event at its time, coloured by its kind. Also called a raster plot; told as a timeline, a swimlane timeline.

Who did what today: a lane per account, a tick per save, rename, export, delete or sign-in from 08:00 to 20:00; the busiest account works in bursts all morning, health checks tick evenly all day in a lane of their ownWho did what today: a lane per account, a tick per save, rename, export, delete or sign-in from 08:00 to 20:00; the busiest account works in bursts all morning, health checks tick evenly all day in a lane of their own

Fits when

  • Many actors, one log: accounts, users, jobs or services, each with its events over the same hours.
  • When and by whom matter together: bursts, quiet hours, who works when, what one actor did before another.
  • Every event counts: a single delete in a lane of saves shows as one red tick.

Not when

How it is drawn

  1. Lanes: one per actor, its name on the left; the busiest on top.
  2. The time: one axis under the lanes, thin grey lines at even hours.
  3. Ticks: a thin bar per event at its time, coloured by its kind, a legend of the kinds on top.
  4. Totals: at the end of each lane, how many events it holds.
  5. Noise: health checks, bots, staff in a lane of their own, under the rest; the many quiet actors folded into one lane, "31 other accounts".
In the author's words
  • What is this way of showing information called? (2026-10-19 19:40, of a picture of who did what today: a lane per account, a tick per action)
  • Yes, let's add it too. (19:46)
eventplot.md

14Milestone track: where a goal stands

One goal and its steps on a line, left to right: the steps done, the step now, the steps ahead, and who each one waits on.

Payments open to every shop, 3 of 6 done: the card form, refunds and five shops trying it done with their dates; fees shown at checkout now, waiting on you to approve the text; opening to every shop by you and watching the first week by me aheadPayments open to every shop, 3 of 6 done: the card form, refunds and five shops trying it done with their dates; fees shown at checkout now, waiting on you to approve the text; opening to every shop by you and watching the first week by me ahead

Fits when

  • One goal, a few steps: four to seven, each done or not.
  • The question is what is next and who it waits on: the reader or the agent.
  • The same track is shown again later, and the reader sees how far it moved.

Not when

  • What happened when matters, not what is left: a timeline.
  • A thing's states and what moves it between them: a state diagram.
  • Many parts at once, each with its own state: a status dashboard.

How it is drawn

  1. The band: one framed panel; a flag, the goal's name in bold and how many steps are done, in blue, beside it.
  2. The steps: dots on one line, left to right. A done step is green with a tick, a green line up to the step now; the step now is a blue ring with its number; the steps ahead are grey, numbered, on a grey line.
  3. Under each dot: its name in a word or two, and under that its date when done, or who it waits on: "waits on you" in amber for the step now, "by you" or "by me" for the steps ahead.
  4. Now: a blue box under the line names the step now and what it waits on, in one sentence.
In the author's words
  • Add all of them, only make them anonymous: nothing about the company or anything personal. (2026-10-14 23:56, of the visual-lang drafts)
milestone.md

15Plan graph: what waits on what

A plan's parts as boxes, an arrow from each part to the parts that wait on it. Parts that can run side by side stand in one column. The longest chain is bold blue: it sets the day the plan ends.

A coupon field at checkout in five parts over seven days: P1 the coupon API, 2 days, done in green; then side by side P2 the form, 3 days, under way in blue, and P3 the e-mail, 1 day, not started in grey; both lead to P4 tests, 1 day, not started; then P5 your go, waiting on you in amber; the arrows P1 to P2 to P4 to P5 are bold blue, the longest chain; a Now box says a late form moves the ship day, the e-mail can slip 2 days, and then it waits on your goA coupon field at checkout in five parts over seven days: P1 the coupon API, 2 days, done in green; then side by side P2 the form, 3 days, under way in blue, and P3 the e-mail, 1 day, not started in grey; both lead to P4 tests, 1 day, not started; then P5 your go, waiting on you in amber; the arrows P1 to P2 to P4 to P5 are bold blue, the longest chain; a Now box says a late form moves the ship day, the e-mail can slip 2 days, and then it waits on your go

Fits when

  • A plan in parts, some of which wait on others and some of which can run at the same time.
  • The question is what holds the end date: which parts must not slip, and which have time to spare.
  • A part waits on the reader, and the reader sees how much waits behind it.

Not when

  • One goal's steps in a line, one after another: a milestone track.
  • The months ahead, bars against dates: a roadmap.
  • Work by stage today, not by what it waits on: a kanban board.
  • What is decided where, questions and their answers: a flowchart.

How it is drawn

  1. The parts: one box per part, its name in bold, P1, P2 and so on with a few words; under it how long it takes and where it stands. Three to eight parts.
  2. The columns: left to right in the order the parts can start, the days on top. Parts that can run side by side are stacked in one column.
  3. The arrows: from a part to each part that waits on it, from box edge to box edge, thin grey.
  4. The longest chain: its arrows bold blue, so the reader sees which parts move the end date and which can slip.
  5. Where each stands: green is done, blue under way, grey with a dashed border not started, amber with "waits on you" a part the reader must do or approve.
  6. Now: a blue box under the panel says in one sentence what holds the end date, what has time to spare and what waits on the reader.
In the author's words
  • Good, add them all. (2026-10-16 21:00)
plangraph.md

16Roadmap: what is planned when

The months ahead on one line of time, a lane per area of work, each piece of work a bar from its start to its end; a red line marks today. The reader sees what is done, what is under way, what is at risk and what comes next.

The shop from July to December: Payments has the card form done and bank payouts under way; Checkout has Apple Pay under way and tax by country at risk in amber after it; Help centre has the gift card articles done and search planned in grey; a red dashed line marks today, 10-16; a Now box says tax by country is at risk because it needs Apple PayThe shop from July to December: Payments has the card form done and bank payouts under way; Checkout has Apple Pay under way and tax by country at risk in amber after it; Help centre has the gift card articles done and search planned in grey; a red dashed line marks today, 10-16; a Now box says tax by country is at risk because it needs Apple Pay

Fits when

  • Several areas of work over months: what each one does when, side by side.
  • The question is what comes next and what is late, measured against today.
  • One piece of work waits on another, and the reader sees the delay push the next one.

Not when

How it is drawn

  1. Time: the months left to right in one framed panel, their names on top; four to twelve of them.
  2. Lanes: one row per area of work, its name in bold on the left, thin lines between the rows; two to five lanes.
  3. Bars: one per piece of work, from its start to its end, its name inside in two or three words. Green is done, blue under way, amber at risk with its name in amber, grey with a dashed border planned.
  4. Today: a red dashed line down the panel, behind the bars, its date on a red pill at the bottom.
  5. Now: a blue box under the panel says in one sentence what is under way and what is at risk, and why.
In the author's words
  • For some reason I don't see a roadmap in our diagrams. (2026-10-16 15:37)
roadmap.md

17Kanban board: where each piece of work is

Many pieces of work at once, each in the column of its stage: to do, doing, in review, done. The board says what is in flight, where work piles up, and what waits on whom.

The checkout's work this week: To do holds saved cards, the receipt e-mail and the coupon field, one more hidden; Doing is full at 3 of 3, Apple Pay, tax by country, and bank payouts blocked for 3 days in red; Review holds the fees text, waiting on you in amber; Done holds the card form and refunds with their dates, three more hidden; a Now box says what is stuckThe checkout's work this week: To do holds saved cards, the receipt e-mail and the coupon field, one more hidden; Doing is full at 3 of 3, Apple Pay, tax by country, and bank payouts blocked for 3 days in red; Review holds the fees text, waiting on you in amber; Done holds the card form and refunds with their dates, three more hidden; a Now box says what is stuck

Fits when

  • Many pieces of work at once, each in one stage, none of them the whole goal.
  • The question is what is in flight: what is stuck, what piles up before a stage, what waits on the reader.
  • A stage has a limit, and the reader sees it is full before more work is started.

Not when

How it is drawn

  1. The columns: one framed column per stage, left to right in the order work moves; three to five of them.
  2. The header: the stage's name in bold, its count at the right. A stage with a limit shows "3 of 3" in blue when full; red when over.
  3. The cards: one per piece of work, its name in bold in two or three words, under it who it is by and how long it has been there.
  4. What stands out: a card that waits on the reader is amber with "waits on you"; a blocked card has a red border and says for how long; a done card has a green tick and its date.
  5. Long columns: a few cards are shown, the rest as "+ 3 more" under them; Done shows the newest first.
  6. Now: a blue box under the board says in one sentence what is stuck and what waits on whom.
In the author's words
  • It seems our diagrams have no kanban charts. (2026-10-16 09:58)
kanban.md

18Priority quadrant: what to do first

Many pieces of work weighed on two things only: how much each is worth and how much it costs. Value goes up, effort goes right, and the square splits in four quarters: do first, plan, later, skip. The reader sees what to start with and what to drop.

Eight checkout ideas on value and effort: the green Do first quarter, high value and low effort, holds Apple Pay and saved cards; the blue Plan quarter, high value and high effort, holds the one-page checkout and tax by country; the grey Later quarter, low value and low effort, holds the coupon field and the receipt e-mail; the dashed grey Skip quarter, low value and high effort, holds dark mode and gift wrap as hollow dots; a Now box says Apple Pay and saved cards come first and gift wrap and dark mode are droppedEight checkout ideas on value and effort: the green Do first quarter, high value and low effort, holds Apple Pay and saved cards; the blue Plan quarter, high value and high effort, holds the one-page checkout and tax by country; the grey Later quarter, low value and low effort, holds the coupon field and the receipt e-mail; the dashed grey Skip quarter, low value and high effort, holds dark mode and gift wrap as hollow dots; a Now box says Apple Pay and saved cards come first and gift wrap and dark mode are dropped

Fits when

  • Many ideas and room for a few, and the question is which ones to start with.
  • Two things decide it: what a piece of work brings and what it costs, each a rough guess, not a measure.
  • The reader must say no to some of them, and wants to see why.

Not when

  • Work by stage today, in flight or stuck: a kanban board.
  • The months ahead, what is planned when: a roadmap.
  • Options compared on many criteria, not two: a table, a row per option and a column per criterion.

How it is drawn

  1. The axes: value up the left side, effort along the bottom, each an arrow with its name; no numbers, only more and less.
  2. The quarters: four framed boxes with a gap between them, each named in its outer corner in bold, what it means under the name. Do first is green, top left; plan is blue, top right; later is grey, bottom left; skip is grey with a dashed border, bottom right.
  3. The dots: one per piece of work, where its value and effort put it, in its quarter's colour; a skipped one is hollow. Four to twelve of them.
  4. The labels: the name in bold on its own light pill beside its dot, clear of the quarter's border and of other pills; right of the dot, or left when the right has no room.
  5. Now: a blue box under the panel says in one sentence what comes first and what is dropped.
In the author's words
  • Good, add them all. (2026-10-16 21:00)
quadrant.md

19Container sketch (C4): where the parts run

Which parts a system has, where each one runs, and what goes between them: the container level of the C4 model, drawn as a sketch.

Where the parts of a notes app run: the app, its folder and an agent box on a laptop; a router and agent machines; model and speech services on the internetWhere the parts of a notes app run: the app, its folder and an agent box on a laptop; a router and agent machines; model and speech services on the internet

Fits when

  • The question is where: which machine, which box, which service runs a part.
  • Something crosses a boundary: a laptop to a server, a box to the internet, and what goes across.
  • A newcomer needs the whole before any one part.

Not when

How it is drawn

  1. Where things run: dashed boxes with their names at the top left (a laptop, other machines, the internet).
  2. Parts: boxes inside them, a name and one line of what each is; the one the reply is about in blue.
  3. What goes between them: the project's arrows, grey, each with a few words.
  4. Names: the standard ones from the glossary of names (laptop, router, vps1, box), never a private host.

Examples

A render service as C4 containers: a user, Cloudflare and Stripe outside; inside, the proxy, the API, the render queue, the renderer, the database, the cache and the media store, each with its technology and what it doesA render service as C4 containers: a user, Cloudflare and Stripe outside; inside, the proxy, the API, the render queue, the renderer, the database, the cache and the media store, each with its technology and what it does

References

  • The C4 model, by Simon Brown, its site and examples under CC BY 4.0: this sketch draws its container level; the picture is drawn here.
In the author's words
  • Add all five. (2026-10-13, as the note of 16:29 quotes it)
  • The new diagrams, I think, should go on the pages too, only in the same format as the other diagrams; and mind the arrows: take the ones the project uses. (16:33)
containers.md

20Entity-relationship: what data there is and how it links

The kinds of data a system keeps, their main fields, and how many of one go with one of another: 1 to n, n to n, marked on each line's ends.

A note's data: a note holds messages, messages are linked in subjects, a message has filesA note's data: a note holds messages, messages are linked in subjects, a message has files

Fits when

  • The question is about data: where something is kept, what points to what.
  • A change touches a link: one becomes many, or a link goes away.
  • A newcomer reads the storage before the code.

Not when

  • Where the data lives (which machine, which service): a container sketch.
  • What happens to one record over time: a state diagram.
  • Every field of every table: keep the main ones; the schema is in the code.

How it is drawn

  1. Entities: a box per kind of data, its name in bold on a tinted band, its main fields under it.
  2. Links: plain lines, no arrowheads, a verb under the line (holds, has, linked in).
  3. Their ends, crow's feet: two short bars across the line where it is one, a three-pronged foot with a bar before it where it is many (one or more). 1 and n in bold beside them, for a reader who does not know the marks.
  4. Left to right in the order a reader meets them; a child under its parent.
In the author's words
  • Add all five. (2026-10-13, as the note of 16:29 quotes it)
  • The new diagrams, I think, should go on the pages too, only in the same format as the other diagrams; and mind the arrows: take the ones the project uses. (16:33)
entities.md

21Class diagram: the types of a program and how they link

The types of a program as boxes: each with its name, its main fields and its methods. The lines between them say how two types link: one is made of the other, one uses the other, one is a kind of the other.

How checkout pays: Order, its fields id, lines and total and its method pay, is made of OrderLine, 1 to n, and pays with PaymentMethod, an interface with charge and refund; CardPayment and GiftCardPayment are both a PaymentMethod, joined to it by dashed lines with a hollow triangle; GiftCardPayment is green, new; a Now box says a new way to pay is one more class under PaymentMethod and Order does not changeHow checkout pays: Order, its fields id, lines and total and its method pay, is made of OrderLine, 1 to n, and pays with PaymentMethod, an interface with charge and refund; CardPayment and GiftCardPayment are both a PaymentMethod, joined to it by dashed lines with a hollow triangle; GiftCardPayment is green, new; a Now box says a new way to pay is one more class under PaymentMethod and Order does not change

Fits when

  • The question is about types: what an object holds, what it can do, which other types it needs.
  • A new kind joins a family: one more class under an interface, and the reader sees that nothing else changes.
  • A newcomer reads the model of a program before its code.

Not when

  • Which function calls which: a call graph.
  • Which file needs which: a module graph.
  • What data is stored and how it links: an entity-relationship diagram; a class diagram is the code's model, not the tables.
  • Code with no types of its own, plain functions and data: there is nothing to box.

How it is drawn

  1. A type: a box in three parts. Its name in bold on a tinted band; its main fields under it, name: type; its main methods at the bottom. An interface has «interface» over its name, the name in italics, no fields.
  2. Made of: a plain line with a filled diamond at the whole; 1 and n in bold at the ends, a verb beside it.
  3. Uses: a dashed line with an arrowhead to the type used, a verb on it (pays with).
  4. A kind of: a dashed line with a hollow triangle at the interface it implements, or a plain one at the class it extends; several kinds share one triangle.
  5. What changes: a new type green, one that goes red and dashed; under it a word in its colour.
  6. Now: a blue box under the types says in one sentence what the diagram shows.

References

  • archify, by tt-a1i, Apache-2.0 licence: an agent skill that draws this kind from typed JSON into an interactive page; the kind came to this page from it, the picture is drawn here.
In the author's words
  • Which diagrams does this project have that we lack? (2026-11-02 19:24, of archify.si)
  • Let us add them then, and be sure to show me what was added and what came out. (19:29)
class.md

22Breakdown tree: a whole split into its parts

One thing on top, split into its parts, each part into its own, down to the level the question needs. Every part has one parent, so the reader sees what belongs where and what is missing an owner.

The shop, split into its parts: on top the shop, 7 parts and 3 teams; under it Catalog of team Find, Checkout of team Pay and Accounts of team Me; under Catalog Search and Products, under Checkout Cart, Payment and Coupons, under Accounts Sign-in and Orders, each with its team; Coupons is amber, no owner, and a line under the tree says it belongs to Checkout but no team owns it; a Now box says every part has one owner but CouponsThe shop, split into its parts: on top the shop, 7 parts and 3 teams; under it Catalog of team Find, Checkout of team Pay and Accounts of team Me; under Catalog Search and Products, under Checkout Cart, Payment and Coupons, under Accounts Sign-in and Orders, each with its team; Coupons is amber, no owner, and a line under the tree says it belongs to Checkout but no team owns it; a Now box says every part has one owner but Coupons

Fits when

  • A whole and its parts: a product by feature, a system by component, a team by people, a goal by its tasks.
  • The question is where each part belongs, and which part has no owner, no test, no plan.
  • One parent each: every part sits under exactly one other.

Not when

How it is drawn

  1. The root: on top, in the middle, a blue box with the whole's name and a count under it (7 parts, 3 teams).
  2. The parts: a box per part, its name in bold and one fact under it (its owner, its size); one row per level, at most three levels.
  3. The lines: from the middle of a parent's bottom down, across, and down into each child; square corners, no arrowheads.
  4. The leaves: evenly across the bottom row; each parent centred over its own.
  5. What stands out: the part the question is about amber, a line under the tree saying why.
  6. Now: a blue box under the tree says in one sentence what to do.

References

  • archify, by tt-a1i, Apache-2.0 licence: an agent skill that draws this kind from typed JSON into an interactive page; the kind came to this page from it, the picture is drawn here.
In the author's words
  • Which diagrams does this project have that we lack? (2026-11-02 19:24, of archify.si)
  • Let us add them then, and be sure to show me what was added and what came out. (19:29)
breakdown.md

23Status dashboard: where each part stands

A RAG status dashboard (red, amber, green): the state of many parts at once, each a tile coloured by its state. Big numbers on top, the tiles grouped below, the gaps gathered at the end. Two more kinds at the end: tiles coloured by where each part is, and a whole beside its gap.

The sign-in service: 4 of 8 parts in place, 212 unit tests pass, 1 browser test failed; providers and tests as tiles; the gaps, Apple's key, the browser test, the audit log and the docs, gathered at the endThe sign-in service: 4 of 8 parts in place, 212 unit tests pass, 1 browser test failed; providers and tests as tiles; the gaps, Apple's key, the browser test, the audit log and the docs, gathered at the end

Fits when

  • The question is where things stand: many parts, each in place, stale or missing.
  • The reader must find the gaps fast: a project's checks, a release, an audit of what is covered.
  • The same view is read again later, and the colours show what moved.

Not when

  • One thing and its states over time: a state diagram.
  • What happened in what order: a timeline or a sequence diagram.
  • A few parts only: a sentence or a list says it; a dashboard needs enough tiles to scan.

How it is drawn

  1. The key: green in place and checked, amber stale or unchecked, red missing or failed, in one line under the title.
  2. KPI cards: three or four big numbers on top, each a word of what it counts and a line of context, coloured like the worst it stands for.
  3. The status board: a panel per area, its name and a line of what it holds; a tile per part, its name in bold and its state in its colour.
  4. The gaps: the amber and red tiles again, gathered in a panel at the end, so the reader does not hunt for them.
  5. Real states only: a tile's word says why it has its colour ("1 failed", "no test"), never just "bad".

Coloured by where it is

When the question is where each part is, not how it is, the colours name places: production, development, the working tree. The list behind a tile opens on a click, in a panel beside the grid.

The help centre's 12 topics: 7 on production, 4 on development not released, 1 only in the working tree; Coupons and Sizes with a red dot; Gift cards selected, its questions and sources in the side panelThe help centre's 12 topics: 7 on production, 4 on development not released, 1 only in the working tree; Coupons and Sizes with a red dot; Gift cards selected, its questions and sources in the side panel
  1. A card per place, in the colour its tiles get: green, on production as it is; blue, on development and not released; amber, only in the working tree and not committed.
  2. Each tile in the colour of its latest change: its name in bold, a small word for what is not out yet ("not released").
  3. A red dot on a tile: a question it cannot answer, its data missing.
  4. The key under the grid, the red dot in it too.
  5. Details on a click: the chosen tile gets a dark outline; the panel beside the grid shows its name, a tag of where it is, and short sections, headed in small caps, of a few bullets each. The tile never grows to hold its list.

A whole and its gap

When the question is how much is covered, one bar shows the whole and what is missing from it; a row of squares counts the runs.

The help centre's 86 articles as one bar, 52 how-tos, 28 FAQs and a grey strip of 6, then a dashed red part for coupons and sizes; beside it 24 stories as squares, 19 passed, 1 failed, 4 skippedThe help centre's 86 articles as one bar, 52 how-tos, 28 FAQs and a grey strip of 6, then a dashed red part for coupons and sizes; beside it 24 stories as squares, 19 passed, 1 failed, 4 skipped
  • The bar: a segment per kind, as wide as its count, dark green, light green, a thin strip for the rest.
  • The gap: a dashed red segment at the end, hatched soft red, its label on a pill: "+ coupons, sizes".
  • A grey line under the bar names the strip and the dashed part.
  • Units as squares, in rows: filled green passed, filled red failed, empty with a red outline skipped. A grey line under them says which failed, when, and why the rest were skipped.
In the author's words
  • Let's add it to the diagrams too, but first make a few sketches. (2026-10-14 13:45, of a status dashboard)
  • Sketch: A, the full dashboard. (13:49)
  • Add all of them, only make them anonymous: nothing about the company or anything personal. (2026-10-14 23:56, of the visual-lang drafts)
dashboard.md

24Line chart: a number over time

One number over days or hours, a point for each, joined by a line; a dashed line marks the moment something changed, a deploy or a fix. The reader sees the number before and after, and whether it stayed.

The checkout page's p95 load time from 10-01 to 10-14, a point a day, 0 to 3 s up the side: before the deploy the line is red at about 2.4 s, between 2.3 and 2.6; a blue dashed line marks the deploy of 10-08; after it the line is green at about 0.9 s, between 0.8 and 1.0; a grey dashed line marks the goal of 1.5 s; a Now box says the deploy cut p95 from about 2.4 s to 0.9 s, well under the goalThe checkout page's p95 load time from 10-01 to 10-14, a point a day, 0 to 3 s up the side: before the deploy the line is red at about 2.4 s, between 2.3 and 2.6; a blue dashed line marks the deploy of 10-08; after it the line is green at about 0.9 s, between 0.8 and 1.0; a grey dashed line marks the goal of 1.5 s; a Now box says the deploy cut p95 from about 2.4 s to 0.9 s, well under the goal

Fits when

  • One number, measured again and again: a load time, an error rate, a queue's length; two numbers at most.
  • The question is before and after: did the deploy or the fix move the number, and did it stay moved.
  • A goal or a limit exists, and the reader sees which side of it the line is on.

Not when

  • One run's time by function: a flame graph.
  • When something happens by hour and day of the week: a heatmap.
  • Work planned over months: a roadmap.
  • Events from a log, not a measured number: a timeline.

How it is drawn

  1. Time: left to right along the bottom, the dates or hours under it, every other one when they crowd; a week to a month of days, or a day of hours.
  2. The number: up the side from zero, a few round values with their unit ("1 s", "2 s"), a thin line across the panel at each.
  3. The line: a dot per measurement, joined. Red before the change, green after it when the number improved; one colour when nothing changed.
  4. The change: a blue dashed line down the panel at its moment, its name and date on a blue pill at the top.
  5. The goal: a grey dashed line across, its value at the right end; only when there is one.
  6. What it says: the typical value before and after in the line's colour, next to the line, in a few words.
  7. Now: a blue box under the panel says in one sentence what changed and by how much.
In the author's words
  • Good, add them all. (2026-10-16 21:00)
linechart.md

25Bar chart: how much of each

One bar per thing counted, as long as its count, all from zero, sorted longest first. The reader compares at a glance which is biggest, by how much, and where the one the question is about stands.

Why checkout failed last week: five bars from zero on an axis to 250, card declined 212, bank timeout 148 in amber with "ours to fix", coupon invalid 96, address rejected 41, other 23; under the axis, errors last week, 520 in all; a Now box says bank timeouts are 148 of 520 and a retry on the bank call cuts the biggest part that is oursWhy checkout failed last week: five bars from zero on an axis to 250, card declined 212, bank timeout 148 in amber with "ours to fix", coupon invalid 96, address rejected 41, other 23; under the axis, errors last week, 520 in all; a Now box says bank timeouts are 148 of 520 and a retry on the bank call cuts the biggest part that is ours

Fits when

  • A count per kind: errors by cause, sign-ups by source, time by stage; three to ten kinds.
  • The question is which is biggest, and by how much it beats the next.
  • One of them matters most: the one that is ours to fix, the one that grew.

Not when

  • A number over time: a line chart.
  • Shares of one whole, where the question is what part of all: a pie chart; with many kinds a bar chart still reads better.
  • One whole and its gap, how much is covered: the bar of a dashboard.
  • Two or three numbers: say them in a sentence.

How it is drawn

  1. The bars: across, one per kind, longest on top, the same thickness, blue; the name to the left of each, its count at its end.
  2. The axis: from zero along the bottom, a few round values and a thin line up the panel at each; a bar never starts above zero.
  3. The one that matters: amber, its name bold, a few words beside its count (ours to fix).
  4. The total: under the axis, what is counted and how many in all.
  5. Now: a blue box under the chart says in one sentence what it shows.

References

  • archify, by tt-a1i, Apache-2.0 licence: an agent skill that draws this kind from typed JSON into an interactive page; the kind came to this page from it, the picture is drawn here.
In the author's words
  • Which diagrams does this project have that we lack? (2026-11-02 19:24, of archify.si)
  • Let us add them then, and be sure to show me what was added and what came out. (19:29)
barchart.md

26Pie chart: shares of one whole

One whole cut into its shares: a ring, each slice as big as its share, the biggest from the top clockwise, the total in the middle. The reader sees what part of all each share is, and whether one is most of it.

Where checkout visitors come from: a ring of 18 400 visits in October, search 46% in blue from the top, direct 27% green, e-mail 15% amber, ads 8% purple and other 4% grey; beside it a legend in the same order, each with its share and its count; a Now box says almost half come from searchWhere checkout visitors come from: a ring of 18 400 visits in October, search 46% in blue from the top, direct 27% green, e-mail 15% amber, ads 8% purple and other 4% grey; beside it a legend in the same order, each with its share and its count; a Now box says almost half come from search

Fits when

  • The parts add up to a whole: visits by source, a budget by item, time by kind of work.
  • The question is what part of all: almost half, a quarter, a sliver.
  • Two to five shares; the rest merged into one grey "other".

Not when

  • The shares are close, or the question is which is bigger by how much: a bar chart; slices that differ a little look the same.
  • More than five shares, or parts that do not add up to one whole: a bar chart.
  • A share over time: a line chart.
  • Where it goes, step by step: a sankey.

How it is drawn

  1. The ring: a pie with a hole, the total in bold in the hole and what it counts under it.
  2. The slices: the biggest from the top, clockwise, then smaller; blue, green, amber, purple, and "other" grey and last. A thin gap of the background between slices.
  3. The legend: beside the ring, in the slices' order: a swatch, the name, the share in its colour, the count in grey.
  4. Now: a blue box under the chart says in one sentence what it shows.

References

  • archify, by tt-a1i, Apache-2.0 licence: an agent skill that draws this kind from typed JSON into an interactive page; the kind came to this page from it, the picture is drawn here.
In the author's words
  • Which diagrams does this project have that we lack? (2026-11-02 19:24, of archify.si)
  • Let us add them then, and be sure to show me what was added and what came out. (19:29)
piechart.md

27Heatmap: when it happens

A week in one grid: the days as rows, the hours as columns, each cell as dark as its count. The reader sees at once which hours of which days pile up, and which stay quiet.

Checkout errors from 5 to 11 October, a row per day from Monday to Sunday and a column per two hours from 00 to 22; a legend scale runs from grey for none through five ambers to the darkest for 50 and more; most cells are pale, the weekend almost blank; a blue frame holds Monday to Friday at 08 and 10, every cell dark with its count inside, from 38 to 63; under the grid the hot spot is named, Mon to Fri 08:00 to 12:00, 493 of 684 errors; a Now box says 7 in 10 errors hit weekday mornings, while the late nightly import still runsCheckout errors from 5 to 11 October, a row per day from Monday to Sunday and a column per two hours from 00 to 22; a legend scale runs from grey for none through five ambers to the darkest for 50 and more; most cells are pale, the weekend almost blank; a blue frame holds Monday to Friday at 08 and 10, every cell dark with its count inside, from 38 to 63; under the grid the hot spot is named, Mon to Fri 08:00 to 12:00, 493 of 684 errors; a Now box says 7 in 10 errors hit weekday mornings, while the late nightly import still runs

Fits when

  • Many events, and the question is when: which hours of which days they come at.
  • A pattern repeats by the day of the week or the hour of the day, and a line of time would hide it.
  • One spot stands out, and its days and hours point at a cause: a job that runs late, a peak of visitors, a weekly report.

Not when

How it is drawn

  1. The grid: in one framed panel, a row per day from Monday to Sunday, its name in bold on the left; a column per hour, or per two hours, its start on top.
  2. The cells: one per day and hour, as dark as its count: grey for none, then pale to dark amber; five or six steps in all.
  3. The scale: on the line under the title, a swatch per step with its range, from none to the darkest.
  4. The hot spot: a blue frame around its cells, their counts inside them; under the grid, in blue, its days, its hours and its share of the whole.
  5. Now: a blue box under the panel says in one sentence when most of it happens and why.
In the author's words
  • Good, add them all. (2026-10-16 21:00)
heatmap.md

28Versions: which version runs where

A table of what is deployed: one row per part, its version, its commit and its date, and whether it is the latest. A verdict in a sentence on top, what "latest" means at the bottom.

What runs on production: api, web and worker run their latest release; the image resizer and the mail sender were deployed by hand, so no one can tell which code they runWhat runs on production: api, web and worker run their latest release; the image resizer and the mail sender were deployed by hand, so no one can tell which code they run

Fits when

  • The question is what runs now: before a release, after an incident, when a fix should already be live.
  • Some parts are deployed by hand, and the reader must see which of them no one can vouch for.
  • Many parts, each with its own version, too many to keep in mind.

Not when

How it is drawn

  1. The time it was read, under the title: a version table is true only for the moment it was taken.
  2. The verdict first: one sentence, its first half in bold, says what the table shows before the reader reads a row.
  3. A row per deployed part: its name in bold, the version big and bold, the commit in the look of a link, the date.
  4. Latest or not: a green tick and "latest", or an amber "? unknown"; never a guess. A grey note says why: "nothing on main is left out", or how it was deployed and the newest code there is.
  5. What "latest" means, in a line under the table, and where it was read from.
  6. The reader on top, agents below: the summary first; the sources of every version, the files and logs it was read from, go under a line, in a part of their own for agents.
In the author's words
  • Add all of them, only make them anonymous: nothing about the company or anything personal. (2026-10-14 23:56, of the visual-lang drafts)
versions.md

29Cloud architecture diagram: what runs where

The parts of a system inside the places they run: the internet, a CDN's edge, a cloud region, its network and subnets, the managed services beside it. Each part an icon with its name, the links as arrows.

A render service on AWS: users and Stripe on the internet, Cloudflare at the edge; in the region a VPC with the load balancer and nginx in its public subnet, the API, PostgreSQL and Redis in its private one; SQS, Lambda and S3 managed, outside the VPCA render service on AWS: users and Stripe on the internet, Cloudflare at the edge; in the region a VPC with the load balancer and nginx in its public subnet, the API, PostgreSQL and Redis in its private one; SQS, Lambda and S3 managed, outside the VPC

Fits when

  • The question is where: which region, which network, which subnet a part runs in, and what is managed by the cloud.
  • A link crosses a boundary: from the internet into the network, out to an outside service.
  • A design review or a newcomer needs the whole system on one page.

Not when

How it is drawn

  1. The places: nested dashed frames, each named inside at its top left: the internet, the edge, the region, the network, the subnets.
  2. Parts: a small icon over the name and one line of what it is.
  3. Links: the project's arrows, coloured by kind (requests blue, data green, background jobs orange), a few words on the long ones.
In the author's words
  • I am more interested in the topology of computer systems: some complex architecture with queues, Cloudflare, S3, Lambda, proxies, load balancers, databases, all of that. (2026-10-14 18:13)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
cloud.md

30Network diagram: addresses, ports, who may connect

The network engineer's view: address ranges as bands, the gateways at their borders, a security group around what it guards with what it lets in, every link with its protocol and port.

The render service's network: a VPC of 10.0.0.0/16 with a public subnet for the load balancer and nginx and a private one for the API, PostgreSQL and Redis; each security group with its rule, each link with its port: 443, 80, 3000, 5432, 6379The render service's network: a VPC of 10.0.0.0/16 with a public subnet for the load balancer and nginx and a private one for the API, PostgreSQL and Redis; each security group with its rule, each link with its port: 443, 80, 3000, 5432, 6379

Fits when

  • "Why can't X reach Y?": a port, a rule or a subnet in the way.
  • A firewall or security-group review: what is open, from where.
  • Addresses matter: ranges, gateways, what has a public address.

Not when

How it is drawn

  1. Bands: each subnet a filled band with its name and range.
  2. Guards: a security group a dashed outline around what it guards, its rule on the outline ("5432 from sg-api").
  3. Links: every arrow with its protocol and port on a pill.
In the author's words
  • I am more interested in the topology of computer systems: some complex architecture with queues, Cloudflare, S3, Lambda, proxies, load balancers, databases, all of that. (2026-10-14 18:13)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
network.md

31Layered diagram: the tiers a request passes

The parts in columns by tier, left to right in the order a request meets them: the edge, the entry, the compute, the background work, the data. The main path bold, the side paths in their own style.

The render service in five tiers: Cloudflare at the edge, the load balancer and nginx at the entry, the API in compute, SQS and Lambda for background work, PostgreSQL, Redis and S3 as data; the main path blue, the render jobs dashed greenThe render service in five tiers: Cloudflare at the edge, the load balancer and nginx at the entry, the API in compute, SQS and Lambda for background work, PostgreSQL, Redis and S3 as data; the main path blue, the render jobs dashed green

Fits when

  • How deep a request goes: which tiers it crosses before an answer.
  • Where a part belongs: a new service placed in its tier, or one in the wrong one.
  • A caching or scaling talk: what each tier absorbs.

Not when

How it is drawn

  1. Tiers: columns with a name and a line under it, left to right.
  2. Parts: boxes in their tier; outside parties outside the columns.
  3. Paths: the main one bold blue, the background one dashed green, the rest thin grey; a key under the drawing.
In the author's words
  • I am more interested in the topology of computer systems: some complex architecture with queues, Cloudflare, S3, Lambda, proxies, load balancers, databases, all of that. (2026-10-14 18:13)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
tiers.md

32Isometric diagram: the system as a model

The same parts as blocks on an isometric floor, the networks as raised platforms, the main paths along the grid: a picture to point at on a slide, read before any word.

The render service as an isometric model: users and Cloudflare on the internet; the region's VPC a slab with a platform for each subnet; the API, PostgreSQL, Redis and the replica on the private one; SQS, Lambda and S3 beside itThe render service as an isometric model: users and Cloudflare on the internet; the region's VPC a slab with a platform for each subnet; the API, PostgreSQL, Redis and the replica on the private one; SQS, Lambda and S3 beside it

Fits when

  • A slide or a talk: the whole system at once, for people who will not read a diagram's notation.
  • Groups matter more than links: what sits together on which platform.

Not when

  • Exact links, ports or order: any other kind says it better; an isometric picture hides lines behind blocks.
  • The picture will change often: the layout is slow to redraw.

How it is drawn

  1. The floor: a faint isometric grid; places as dashed outlines on it.
  2. Platforms: a raised slab per network, its name on a pill.
  3. Parts: blocks for services, cylinders for stores, a name on a pill.
  4. Paths: only the main ones, along the grid, coloured by kind.
In the author's words
  • I am more interested in the topology of computer systems: some complex architecture with queues, Cloudflare, S3, Lambda, proxies, load balancers, databases, all of that. (2026-10-14 18:13)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
isometric.md

33Service map: what talks to what, live

What a tracing tool draws from real traffic: each service a circle with a ring for its health, each link as thick as its traffic, the numbers on the links. The unwell one stands out at a glance.

The render service's map: Cloudflare 1000 requests a second, 300 through the load balancer and nginx to the API, 150 to Redis, 120 to the replica; Lambda ringed red with 3% errors, the replica orange with 0.4 s of lagThe render service's map: Cloudflare 1000 requests a second, 300 through the load balancer and nginx to the API, 150 to Redis, 120 to the replica; Lambda ringed red with 3% errors, the replica orange with 0.4 s of lag

Fits when

  • On call: which hop is slow or failing, and who depends on it.
  • Traffic matters: where the requests go, how many.
  • The real system, as measured, not as designed.

Not when

How it is drawn

  1. Services: circles laid out freely, an icon inside, the name and one number under it.
  2. Health: the ring green, orange when slow, red when failing, dashed grey for what is not traced.
  3. Links: thickness by traffic, "N req/s" on a pill; a legend.
In the author's words
  • I am more interested in the topology of computer systems: some complex architecture with queues, Cloudflare, S3, Lambda, proxies, load balancers, databases, all of that. (2026-10-14 18:13)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
servicemap.md

34Sankey diagram: where the traffic goes, how much

Traffic as bands that split and end, each as wide as its share: what a cache absorbs, what reaches each part behind it.

1000 requests a second reach Cloudflare; 700 are served from its cache, 300 go on through the load balancer and nginx to the API, which reads 150 from Redis, 120 from the replica, 30 from the primary1000 requests a second reach Cloudflare; 700 are served from its cache, 300 go on through the load balancer and nginx to the API, which reads 150 from Redis, 120 from the replica, 30 from the primary

Fits when

  • Capacity and cost: how much each layer absorbs and passes on.
  • A cache's worth: the share that never reaches the origin.

Not when

How it is drawn

  1. Columns: a thin bar per part, its name above.
  2. Bands: from bar to bar, widths to one scale, each with its number.
  3. Ends: what stops early ends at its own bar, in its own colour.
In the author's words
  • I am more interested in the topology of computer systems: some complex architecture with queues, Cloudflare, S3, Lambda, proxies, load balancers, databases, all of that. (2026-10-14 18:13)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
sankey.md

35Trace waterfall: where one request spends its time

One request traced across services: a row per span, each a bar from its start to its end on one scale of milliseconds, a called span indented under its caller. The reader sees the slowest span, what runs in turn, and the gaps where the request only waits.

A trace of POST /checkout, 1840 ms: the api's bar spans it all; under it auth checks the token in 40 ms, the cart service loads the cart in 240 ms with a database read of 180 ms indented under it, then an amber band marks 160 ms of waiting, then the payment provider charges the card in 1200 ms in red, the database saves the order in 80 ms and the mail queue takes the receipt in 30 ms; a Now box says the payment provider takes 1200 of the 1840 ms and 160 ms before it is a waitA trace of POST /checkout, 1840 ms: the api's bar spans it all; under it auth checks the token in 40 ms, the cart service loads the cart in 240 ms with a database read of 180 ms indented under it, then an amber band marks 160 ms of waiting, then the payment provider charges the card in 1200 ms in red, the database saves the order in 80 ms and the mail queue takes the receipt in 30 ms; a Now box says the payment provider takes 1200 of the 1840 ms and 160 ms before it is a wait

Fits when

  • "Why is this request slow?": one request, measured across the services it passes.
  • Calls in turn or at once: the reader sees what waits for what, and what could run side by side.
  • Time lost between spans: a gap where nothing runs is as plain as the work.

Not when

How it is drawn

  1. Time: milliseconds left to right in one framed panel, the ticks on top, faint dashed lines down from them; zero is the request's start.
  2. Rows: one per span in the order it starts, the service in bold and what it did after it; a called span indented under its caller.
  3. Milliseconds: each span's time in a column right before its bar, so the numbers read down one line.
  4. Bars: one per span from its start to its end, to one scale; a few milliseconds still get a thin bar. The slowest span is solid red, its name and time in red.
  5. Waits: a gap where no span runs is an amber band behind the rows, its length on an amber pill under them.
  6. Now: a blue box under the panel says in one sentence where the time goes.
In the author's words
  • Good, add them all. (2026-10-16 21:00)
waterfall.md

36Data flow diagram: where data crosses a trust boundary

The threat modeller's view: outside parties, processes and data stores, the flows between them labelled with the data they carry, and the trust boundaries as red dashed lines. Each crossing gets a number to discuss.

The render service's data flows: a user's login and cookie through Cloudflare into the VPC, banner JSON into PostgreSQL, render jobs to SQS, rendered PNGs to S3, a card token to Stripe; eight numbered crossings, three noted: TLS ends at the load balancer, the upload skips the WAF, only a token leavesThe render service's data flows: a user's login and cookie through Cloudflare into the VPC, banner JSON into PostgreSQL, render jobs to SQS, rendered PNGs to S3, a card token to Stripe; eight numbered crossings, three noted: TLS ends at the load balancer, the upload skips the WAF, only a token leaves

Fits when

  • A security review or a threat model: each crossing is a place to ask what can go wrong (STRIDE per crossing).
  • Privacy: where personal data goes and what leaves.

Not when

How it is drawn

  1. Notation: outside parties as boxes, processes as circles, stores as two open lines; a key.
  2. Flows: arrows named by their data ("card token"), not by protocol.
  3. Boundaries: red dashed lines; a numbered badge where a flow crosses one, the risky ones noted under the drawing.
In the author's words
  • I am more interested in the topology of computer systems: some complex architecture with queues, Cloudflare, S3, Lambda, proxies, load balancers, databases, all of that. (2026-10-14 18:13)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
dataflow.md

37Dependency matrix: every link in a grid

The parts as rows and the same parts as columns; a filled cell where the row calls the column. Every link at once, however many, with no lines to cross.

Twelve parts of the render service in a grid: users call Cloudflare on 443, the API calls Redis, PostgreSQL, the replica, SQS and Stripe; the one call below the diagonal, Lambda writing back to PostgreSQL, in orangeTwelve parts of the render service in a grid: users call Cloudflare on 443, the API calls Redis, PostgreSQL, the replica, SQS and Stripe; the one call below the diagonal, Lambda writing back to PostgreSQL, in orange

Fits when

  • Many parts: where a graph turns into a hairball.
  • Layers and cycles: with the parts in order, a call below the diagonal goes against the layers.

Not when

How it is drawn

  1. Rows and columns: the same parts in the same order, the column names turned upright, groups bracketed on the left.
  2. Cells: filled where the row calls the column, with a port or a verb when it fits.
  3. Reading: a line under it says how ("the row calls the column").
In the author's words
  • I am more interested in the topology of computer systems: some complex architecture with queues, Cloudflare, S3, Lambda, proxies, load balancers, databases, all of that. (2026-10-14 18:13)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
matrix.md

38Call graph: which function calls which

A program from its entry down: each function a box, an arrow to each one it calls, the related ones framed together, the helpers everything leans on at the bottom.

bin/build from main down: the steps for the rules pages, the glossaries and the agents pages, each with its parser and renderer, all leaning on template_fill and html_escape; 16 of its 44 functions drawn, the rest as "+N more"bin/build from main down: the steps for the rules pages, the glossaries and the agents pages, each with its parser and renderer, all leaning on template_fill and html_escape; 16 of its 44 functions drawn, the rest as "+N more"

Fits when

  • A change is planned: what calls the function, what it touches.
  • A newcomer reads a script: its steps and its shared helpers.
  • Dead code: a function nothing points at.

Not when

How it is drawn

  1. Layers: the entry at the top, each call one row lower.
  2. Groups: light frames for the functions of one step.
  3. Too many: the main ones drawn, the rest a "+N more" box.
In the author's words
  • I will also need a diagram of the topology of, say, some program, some script; how can that be done. (2026-10-14 18:15)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
callgraph.md

39Data flow of a script: files in, steps, files out

What a script reads on the left, the steps it makes of it in the middle, what it writes on the right; each arrow named by what passes along it.

bin/build: docs/rules.md, the templates, the glossaries, the guides and the pictures in; parse, read guides, render and stamp in the middle; docs/rules.html and four more pages out, and the hand-written pages stamped in placebin/build: docs/rules.md, the templates, the glossaries, the guides and the pictures in; parse, read guides, render and stamp in the middle; docs/rules.html and four more pages out, and the hand-written pages stamped in place

Fits when

  • "Where does my edit end up?": from a source file to the page.
  • A build, an import, an export: a script whose job is files.

Not when

How it is drawn

  1. Files: a page icon and the path; inputs left, outputs right, the ones rewritten in place in their own colour.
  2. Steps: rounded boxes in the middle.
  3. Arrows: named by what passes ("Markdown", "index", "HTML").
In the author's words
  • I will also need a diagram of the topology of, say, some program, some script; how can that be done. (2026-10-14 18:15)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
pipeline.md

40Module graph: which file needs which

The files of a project as boxes in their folders, an arrow from each file to each one it requires, the packages from outside in their own shape.

The rulebook's files: tests require src/make_rules_config.js and plugin.js, which require the rules and helpers; bin/build requires package.json and node-helpers and runs bin/self-check; the npm packages eslint, postcss and playwright belowThe rulebook's files: tests require src/make_rules_config.js and plugin.js, which require the rules and helpers; bin/build requires package.json and node-helpers and runs bin/self-check; the npm packages eslint, postcss and playwright below

Fits when

  • What breaks when a file changes: everything that points at it.
  • Cycles and layers: an arrow that goes back up.
  • What a script drags in from outside.

Not when

How it is drawn

  1. Folders: dashed frames named at the top left.
  2. Files and packages: a box with a folded corner for a file, a rounded one with a cube for a package.
  3. Arrows: blue for a require, dashed orange for running it as a process; "+N more" for the rest.
In the author's words
  • I will also need a diagram of the topology of, say, some program, some script; how can that be done. (2026-10-14 18:15)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
modules.md

41Change map: what a change touches

The project's folder tree, trimmed to the files one change touches: each file a row, marked added, changed or removed, its lines added and removed at the right. The reader sees where the change lands and how big it is before reading the diff.

The coupon field commit in the shop: on top 6 files, 3 added, 2 changed, 1 removed, +312 and −148 lines; under src/api, coupons.js added with +64 and old-discounts.js removed and struck through with −92, 4 more files folded; under src/checkout, checkout.vue changed with +18 −27 and coupon-field.vue added with +121; components, pages and store folded; tests/coupon.test.js added with +88; docs/coupons.md changed with +21 −29; bin and public folded; each file has a bar of green for lines added and red for lines removed; a Now box says it is mostly new code and checkout.vue is the file to checkThe coupon field commit in the shop: on top 6 files, 3 added, 2 changed, 1 removed, +312 and −148 lines; under src/api, coupons.js added with +64 and old-discounts.js removed and struck through with −92, 4 more files folded; under src/checkout, checkout.vue changed with +18 −27 and coupon-field.vue added with +121; components, pages and store folded; tests/coupon.test.js added with +88; docs/coupons.md changed with +21 −29; bin and public folded; each file has a bar of green for lines added and red for lines removed; a Now box says it is mostly new code and checkout.vue is the file to check

Fits when

  • One commit or one pull request: which files it adds, changes and removes, and where in the project they sit.
  • The question is where to look first: the big rows, the removed file, the one changed file in a folder of new ones.
  • A change spreads over folders: code, tests and docs, and the reader sees that each got its part.

Not when

  • Which file needs which: a module graph.
  • How big each part of the code is, not what one change did: a treemap.
  • A script's data flow, files in and files out: a pipeline.

How it is drawn

  1. The total: on top of the panel, the number of files, then how many added, changed and removed in their colours; the lines added in green and removed in red at the right.
  2. The tree: folders in bold with a slash, each level indented, thin grey lines from a folder to what it holds.
  3. The files: one row each, a mark and its name in colour: green + added, blue ~ changed, red − removed and struck through.
  4. The lines: at the right of each file, the lines added and removed as numbers, then a bar of green and red as long as they are.
  5. What it leaves alone: folders and files the change does not touch fold into one grey row, "… 4 more files" or "… bin/, public/".
  6. Now: a blue box under the panel says in one sentence what the change is and which file to check first.
In the author's words
  • Good, add them all. (2026-10-16 21:00)
changemap.md

42Before and after: what a change does to a system

One map of a system as it is after a change, each part marked by what the change did to it: added, changed, removed or the same. The counts on top say how big the change is before the reader looks at the map.

Checkout gets a price cache: on top pills say 1 added, 1 changed, 1 removed and 2 stay the same; the Browser sends HTTPS to the Checkout API, blue with a tilde, it reads the cache; the API reads Redis first, green with a plus, prices for 5 minutes, and MySQL by SQL, the same; the Price cron is red, dashed and struck through with a minus, gone because prices are live, its every-night line to MySQL dashed red; a Now box says prices come from Redis, filled as they change, and the nightly cron is goneCheckout gets a price cache: on top pills say 1 added, 1 changed, 1 removed and 2 stay the same; the Browser sends HTTPS to the Checkout API, blue with a tilde, it reads the cache; the API reads Redis first, green with a plus, prices for 5 minutes, and MySQL by SQL, the same; the Price cron is red, dashed and struck through with a minus, gone because prices are live, its every-night line to MySQL dashed red; a Now box says prices come from Redis, filled as they change, and the nightly cron is gone

Fits when

  • A change to how a system is built: a cache, a queue, a service added or taken out.
  • The question is what moved: which parts are new, which are gone, which work differently, and what stays as it was.
  • A review of a plan: the map after it is done, before it is started.

Not when

  • Which files a commit touches: a change map.
  • The order of the calls changes: a sequence diagram, today beside proposed.
  • A change the author sees on screen: screenshots before and after.
  • Nothing is added or removed, only settings: say it in a sentence.

How it is drawn

  1. The counts: on top, a pill per kind of change with its count (+ 1 added, ~ 1 changed, − 1 removed), then how many stay the same in grey.
  2. The parts: a box per part as in a container sketch, its name in bold and what it does under it, left to right in the order a request meets them.
  3. The marks: added green with a + on its corner; changed blue with a ~; removed red, dashed, its name struck through, with a −; the same in grey. Under the name of a marked part, what the change did to it, in its colour.
  4. The lines: as the parts they join: a new line green, a removed one red and dashed, the rest dark; a few words on each.
  5. Now: a blue box under the map says in one sentence what the system does differently.

References

  • archify, by tt-a1i, Apache-2.0 licence: an agent skill that draws this kind from typed JSON into an interactive page; the kind came to this page from it, the picture is drawn here.
In the author's words
  • Which diagrams does this project have that we lack? (2026-11-02 19:24, of archify.si)
  • Let us add them then, and be sure to show me what was added and what came out. (19:29)
delta.md

43Flame graph: where one run spends its time

One measured run: each call stack a column of bars, the caller under the callee, each bar as wide as its share of the time. The widest bars at the top are where the time goes.

One run of bin/build, 1531 ms: 889 ms waiting for bin/self-check, 363 ms in build_index_html, most of that reading whole images only to learn their sizeOne run of bin/build, 1531 ms: 889 ms waiting for bin/self-check, 363 ms in build_index_html, most of that reading whole images only to learn their size

Fits when

  • "Why is it slow?": the time of a run by function, measured.
  • Before and after a speed fix: the same bar, narrower.

Not when

How it is drawn

  1. Bars: bottom-up, the whole run at the bottom, widths to one scale, the name and the milliseconds in each.
  2. Too narrow: a letter in the bar, its name in a key; a narrow part that matters zoomed above.
  3. Self time: the bars that spend it themselves marked in orange.

References

  • Flame graphs, invented by Brendan Gregg: this guide draws his kind; the picture is drawn here.
In the author's words
  • I will also need a diagram of the topology of, say, some program, some script; how can that be done. (2026-10-14 18:15)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
flame.md

44Code map: how big each part is

A treemap of the code: each function a rectangle, its area its lines, grouped by the part of the program it belongs to.

bin/build's 44 functions by size: the guides 184 lines, the glossaries 173, the indexes 157, the shared helpers 97; glossary_from_markdown the biggest at 76bin/build's 44 functions by size: the guides 184 lines, the glossaries 173, the indexes 157, the shared helpers 97; glossary_from_markdown the biggest at 76

Fits when

  • Where the code is: the big parts to split, the parts that grow.
  • A first look at a large file or project.

Not when

How it is drawn

  1. Groups: a frame per part, its name and its lines in the header.
  2. Rectangles: one per function, area by lines, the name and the count when they fit.
  3. The small ones: merged into a dashed "N small functions" box.

References

  • Treemaps, invented by Ben Shneiderman: this guide draws his kind; the picture is drawn here.
In the author's words
  • I will also need a diagram of the topology of, say, some program, some script; how can that be done. (2026-10-14 18:15)
  • Let us add these pictures to the documentation. Which get used is not clear yet, but let them be; we will see. (19:01)
treemap.md

45Diagram Design: 25 kinds this page has no guide for

diagram-design is an agent skill that draws 50 kinds of diagram, each a page with one SVG written by hand. These are the 25 this page has no guide for, each in diagram-design's own example, recoloured into this page's colours, light and dark; the shapes, words and sizes are its own. They are not guides yet: a kind this page takes in gets a guide of its own.

How it works

Process: a step per box in the lane of the team that does it, numbered across the top, the data each hands on as a tag; the critical hand-off in the accent. Credit: diagram-design's example-process.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Order fulfilment across four teams in lanes, customer, support, warehouse and finance: place order, verify order, allocate stock in the accent, pick items, pack order, capture payment, receive shipment and close order, numbered 1 to 8 on top, each box with the data it hands on as coloured tags; a legend of the steps, the data types and the two kinds of hand-offOrder fulfilment across four teams in lanes, customer, support, warehouse and finance: place order, verify order, allocate stock in the accent, pick items, pack order, capture payment, receive shipment and close order, numbered 1 to 8 on top, each box with the data it hands on as coloured tags; a legend of the steps, the data types and the two kinds of hand-off

Service blueprint: a path in stages, what the customer does and sees above the line of visibility, what runs backstage below it; the step that fails in the accent. Credit: diagram-design's example-service-blueprint.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Trial to paid in five stages, sign up, activate, hit the limit, upgrade and first invoice: rows for evidence, customer, frontstage, backstage and support, a box per stage in each row; the backstage dunning job that times out under hit the limit in the accentTrial to paid in five stages, sign up, activate, hit the limit, upgrade and first invoice: rows for evidence, customer, frontstage, backstage and support, a box per stage in each row; the backstage dunning job that times out under hit the limit in the accent

User journey: a person's stages across, their actions and touchpoints under each, a line of how they feel that dips where it hurts. Credit: diagram-design's example-journey.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

A trial user's first week in five stages, sign up, first run, invite team, hit the limit and upgrade: a mood line high, low, high, at its lowest in the accent where the export is blocked at the usage limit, then up at upgrade; the action and the touchpoint under each stageA trial user's first week in five stages, sign up, first run, invite team, hit the limit and upgrade: a mood line high, low, high, at its lowest in the accent where the export is blocked at the usage limit, then up at upgrade; the action and the touchpoint under each stage

Event modelling: time left to right; for each stage the command, the event it leaves, named in the past tense, and the view read from that event. Credit: diagram-design's example-event-modeling.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Three stages, submit, publish and close: rows of commands, events and read models; submit finding leaves FindingSubmitted read as open findings, publish review leaves ReviewPublished in the accent read as published reviews, close case leaves CaseClosed read as closed casesThree stages, submit, publish and close: rows of commands, events and read models; submit finding leaves FindingSubmitted read as open findings, publish review leaves ReviewPublished in the accent read as published reviews, close case leaves CaseClosed read as closed cases

What it is made of

Nested: scopes inside scopes, the widest outside, the one that matters innermost. Credit: diagram-design's example-nested.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Project guidance inherits from wider scopes: rounded frames one inside another, global, vault, business, marketing, and innermost the project guidance in the accent; a note that it needs no imports and no configurationProject guidance inherits from wider scopes: rounded frames one inside another, global, vault, business, marketing, and innermost the project guidance in the accent; a note that it needs no imports and no configuration

Layer stack: levels as bands one on another, the lowest at the bottom; the layer that matters in the accent. Credit: diagram-design's example-layers.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

An AI app as five bands from silicon up to abstraction: model weights, SDK and client, prompt layer, agent harness in the accent, UI surface, each with what it holds at the rightAn AI app as five bands from silicon up to abstraction: model weights, SDK and client, prompt layer, agent harness in the accent, UI surface, each with what it holds at the right

Org chart: who reports to whom, a row per level, lines down from each lead. Credit: diagram-design's example-org-chart.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

An agent team: the command centre on top in the accent, four workstream leads under it, growth, content, commerce and systems, six specialists in the bottom row, and a dashed band for the setup gaps still to fillAn agent team: the command centre on top in the accent, four workstream leads under it, growth, content, commerce and systems, six specialists in the bottom row, and a dashed band for the setup gaps still to fill

Database schema: a box per table, its columns, types and keys; a line from each foreign key to the key it names, a group per schema. Credit: diagram-design's example-db-schema.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

A shop's tables, customers, orders, order items and products, with their columns, SQL types and key chips, and invoices in a billing schema; lines from each foreign key to its table, the cascading delete from orders into order items in the accentA shop's tables, customers, orders, order items and products, with their columns, SQL types and key chips, and invoices in a billing schema; lines from each foreign key to its table, the cascading delete from orders into order items in the accent

Exploded view: one thing's layers pulled apart in depth, each named at the side. Credit: diagram-design's example-exploded.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

An app as three slabs lifted apart in 3D: data at the bottom, logic in the middle in the accent, interface on top, each named at the right with what it holdsAn app as three slabs lifted apart in 3D: data at the bottom, logic in the middle in the accent, interface on top, each named at the right with what it holds

Axonometric plan: a floor or a site from above, at an angle, its rooms named; the one under discussion in the accent. Credit: diagram-design's example-axonometric-plan.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

An office floor drawn at an angle with walls at desk height: the lobby, the open office of 24 desks, a phone booth, the kitchen, and the meeting room of 12 seats in the accentAn office floor drawn at an angle with walls at desk height: the lobby, the open office of 24 desks, a phone booth, the kitchen, and the meeting room of 12 seats in the accent

Where it stands

Story map: the user's activities across as a backbone, the stories under each, cut into releases by lines; the riskiest story marked. Credit: diagram-design's example-story-map.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

A reporting tool's first release: four activities across, find the data, build the report, share it, trust it, the first steps under them, then rows for the MVP, release 2 and later, cut by a release line; row-level permissions in release 2 in the accent as the riskiest betA reporting tool's first release: four activities across, find the data, build the report, share it, trust it, the first steps under them, then rows for the MVP, release 2 and later, cut by a release line; row-level permissions in release 2 in the accent as the riskiest bet

Traceability: each need traced by its id to the design that meets it and the test that checks it; a need with no test in the accent. Credit: diagram-design's example-requirement-traceability.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Four columns, source, requirement, satisfied by, verified by: three rows from a review brief to a requirement, a design element and a check; the third requirement, export trace ids, has no check, an open gap in the accentFour columns, source, requirement, satisfied by, verified by: three rows from a review brief to a requirement, a design element and a check; the third requirement, export trace ids, has no check, an open gap in the accent

What it changes

Wardley map: the parts of a product from what the user sees down to what nobody sees, placed by how mature each is, from new to commodity; an arrow where one is moving. Credit: diagram-design's example-wardley.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

An AI assistant's value chain: from answer in the flow of work and chat UI at the top, visible to the user, down to GPU compute and object storage, invisible; across, genesis, custom-built, product, commodity; agent orchestration in the accent with a dashed arrow towards productAn AI assistant's value chain: from answer in the flow of work and chat UI at the top, visible to the user, down to GPU compute and object storage, invisible; across, genesis, custom-built, product, commodity; agent orchestration in the accent with a dashed arrow towards product

How much

Scatter plot: two numbers per item, a dot each, the trend as a line; the one that matters named. Credit: diagram-design's example-scatter.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Twelve teams by deploys a week across and lead time in days up: the dots fall to the right along a dashed trend, Platform in the accent at the bottom right, the best of themTwelve teams by deploys a week across and lead time in days up: the dots fall to the right along a dashed trend, Platform in the accent at the bottom right, the best of them

Radar: a few options scored on three to six criteria, a shape per option on the spokes. Credit: diagram-design's example-radar.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Four storage backends on five spokes, small-file handling, large-object reads, write throughput, operational simplicity and Iceberg integration: MinIO in the accent, the one recommended, Amazon S3, Ceph and Google Cloud Storage beside itFour storage backends on five spokes, small-file handling, large-object reads, write throughput, operational simplicity and Iceberg integration: MinIO in the accent, the one recommended, Amazon S3, Ceph and Google Cloud Storage beside it

Polar chart: one number around a cycle, the hours of a day as spokes; the peak in the accent. Credit: diagram-design's example-polar.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Requests by UTC window as eight spokes on rings from 0 to 100 per cent of the daily peak, clockwise from 00-03; the spoke for 12-15 reaches 100 in the accentRequests by UTC window as eight spokes on rings from 0 to 100 per cent of the daily peak, clockwise from 00-03; the spoke for 12-15 reaches 100 in the accent

Pyramid: levels from a wide base to a narrow top, the rare and valuable at the apex; turned over, a funnel. Credit: diagram-design's example-pyramid.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

A content pyramid: short posts daily at the base, essays weekly, long-form guides quarterly, and a flagship book every few years at the apex in the accent; how many a year at the right of each levelA content pyramid: short posts daily at the base, essays weekly, long-form guides quarterly, and a flagship book every few years at the apex in the accent; how many a year at the right of each level

Venn: what two or three sets share; the overlap that matters named. Credit: diagram-design's example-venn.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Three circles, desirable, feasible and viable: prototype, vaporware and internal tool where two meet, shippable where all three meet, filledThree circles, desirable, feasible and viable: prototype, vaporware and internal tool where two meet, shippable where all three meet, filled

Waterfall, a running total: where it starts, each step up or down as a floating bar, where it ends; not the waterfall of one request's time. Credit: diagram-design's example-waterfall.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

A cloud budget from 240 thousand a month in FY25 to 236 in the FY26 plan: headcount up 64, reserved instances down 38, ML workloads up 22, storage tiering down 52 in the accent, the biggest savingA cloud budget from 240 thousand a month in FY25 to 236 in the FY26 plan: headcount up 64, reserved instances down 38, ML workloads up 22, storage tiering down 52 in the accent, the biggest saving

For one trade

High-level data stack: a data platform end to end, from the sources through ingestion, storage and query to the dashboards, on its cluster. Credit: diagram-design's example-high-level.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Phases as chevrons across the top, data sources, ingestion, storage, transformation and visualisation: web, FTP, a database and a legacy system feed Apache NiFi, then MinIO in the accent, Trino, data modelling and dashboards, under an orchestration bar and over an identity manager, all in a Kubernetes boundaryPhases as chevrons across the top, data sources, ingestion, storage, transformation and visualisation: web, FTP, a database and a legacy system feed Apache NiFi, then MinIO in the accent, Trino, data modelling and dashboards, under an orchestration bar and over an identity manager, all in a Kubernetes boundary

Medallion: data kept in tiers by quality, from raw to aggregated, each tier's tool, format and writer. Credit: diagram-design's example-medallion.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Five tiers as columns, raw, anonymised, staging, aggregated in the accent and archive dashed, joined by arcs, mask ids, clean and join, aggregate, lifecycle; each with its tool, format, writer and an e-commerce example; an SQL path and a notebook path under themFive tiers as columns, raw, anonymised, staging, aggregated in the accent and archive dashed, joined by arcs, mask ids, clean and join, aggregate, lifecycle; each with its tool, format, writer and an e-commerce example; an SQL path and a notebook path under them

Data platform integration: the systems that feed a platform, the consumers it serves, and the protocol on each link. Credit: diagram-design's example-dp-integration.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

CRM, POS exports and an event stream at the left land in object storage inside the data platform, read by the query engine under an orchestrator; a BI tool, notebooks and a partner API at the right; the protocol on each link, an identity provider and central logging across the bottomCRM, POS exports and an event stream at the left land in object storage inside the data platform, read by the query engine under an orchestrator; a BI tool, notebooks and a partner API at the right; the protocol on each link, an identity provider and central logging across the bottom

Data platform access: roles as columns, components as rows, in each cell what the role may do. Credit: diagram-design's example-dp-security-matrix.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Five components, object storage, query engine, notebooks, BI tool and orchestrator, against five roles, data engineer, data scientist, analyst, administrator and external partner: admin, write, read or none in each cell; the partner's read of shared dashboards on the BI tool in the accent, its boundaryFive components, object storage, query engine, notebooks, BI tool and orchestrator, against five roles, data engineer, data scientist, analyst, administrator and external partner: admin, write, read or none in each cell; the partner's read of shared dashboards on the BI tool in the accent, its boundary

IT current state: today's systems by phase, the manual hand-offs between them labelled, the pains marked; the before of a proposal. Credit: diagram-design's example-it-state.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

A retailer's landscape in three zones, collection, processing and dissemination: point-of-sale exports, an online store export and supplier price lists go as CSV and XLSX to a shared drive in the accent with no version control, spreadsheet hand-offs and an on-premises database, then to a reporting portal, email report packs and regional managersA retailer's landscape in three zones, collection, processing and dissemination: point-of-sale exports, an online store export and supplier price lists go as CSV and XLSX to a shared drive in the accent with no version control, spreadsheet hand-offs and an on-premises database, then to a reporting portal, email report packs and regional managers

SBGN: a biological process in its standard notation, species as rounded boxes, the processes between them as small squares, the place it happens as a frame. Credit: diagram-design's example-sbgn.html, © 2025 Cathryn Lavery, MIT licence, recoloured.

Beta-carotene splits in two in the cytosol: beta-carotene in the accent, beta-cryptoxanthin and zeaxanthin pass through six cleavage processes to B-10-apo, B-ionone and their hydroxylated formsBeta-carotene splits in two in the cytosol: beta-carotene in the accent, beta-cryptoxanthin and zeaxanthin pass through six cleavage processes to B-10-apo, B-ionone and their hydroxylated forms

References

  • diagram-design by Cathryn Lavery, MIT licence, with its site diagramdesign.dev: an agent skill that draws 50 kinds as hand-written SVG pages and checks them with two scripts. The 25 pictures on this page are its examples, taken at commit f6db0de and recoloured; its licence is kept beside them, in diagrams/diagramdesign/LICENSE.
In the author's words
  • Which diagrams does it have that we lack? (2026-11-14 17:28, of diagramdesign.dev)
  • Show them in our colour palette. (17:39)
  • Add these pictures to the repository, and give each picture its credit; the link to the repository goes there too, as a credit, a reference. (18:45)
diagramdesign.md