Pimp My IDE / garage dispatchBack to the garage
October 9, 2026 / executable diagrams / system behavior

Make the diagram earn its arrows.

A box and arrow can explain structure. Add equations, time, and visible assumptions when the claim is about behavior.

If the argument says "eventually," the diagram needs a clock.
Review queue
8 items
4.0 per hourNew work3.0 per hourFinished work

The arrow is a claim.

Meadows is a small browser tool for stock-and-flow models. Its text language names stocks, faucets, clouds, information links, and feedback loops. Add numbers or formulas and the page plots how each stock changes over time.[1]

That extra step matters. A normal architecture diagram can say that work enters a queue and a reviewer drains it. It cannot tell you whether the queue clears. The answer depends on the arrival rate, service rate, starting backlog, and time horizon.

Structure tells you what touches what. A runnable model tells you what your assumptions predict.

Text diagrams solve a different problem.

Mermaid flowcharts define nodes and links in text. Its current flowchart syntax also covers direction, node shapes, subgraphs, link labels, and animated edges.[2] Graphviz DOT defines graphs, directed graphs, nodes, edges, attributes, subgraphs, and clusters.[3] Both are useful because the diagram source can live beside code and change in a diff.

Meadows adds state and time. In the inspected revision, a PureScript compiler turns source text into graph data. The TypeScript frontend lays out the graph, simulates it, draws stock traces, and can overlay faucet rates. We entered a queue model in the public playground and saw the named inflow, stock, and outflow appear without an error.[1]

A running model can still be wrong.

Execution proves that the model has behavior. It does not prove that the model matches production. A constant service rate can hide reviewer schedules, priority classes, retries, blocked work, batching, and correlated arrivals. A smooth curve can make a weak assumption look settled.

Write each assumption next to the control that changes it. Save the input text and exact tool revision. Compare at least one point against an independent calculation. Then compare the model with a measured run before using it for staffing or release decisions.

Give agents a model contract.

An agent can draft a diagram fast. Ask for four separate outputs: the source notation, the equations or transition rules, the initial values, and one replay result. Review the units before the layout. A beautiful feedback loop with mismatched units is still broken.

Keep a static picture for readers who need the overview. Put the runnable model beside it when the article predicts accumulation, delay, saturation, oscillation, or recovery. The code should expose the claim instead of decorating it.

Interactive makeover / static queue arrow replaced

Run the queue dyno.

This browser-local teaching model combines three native controls, a physical stock-and-flow view, a time plot, and a copyable model card. It assumes constant rates and an empty starting queue. It is not production telemetry or a staffing forecast.

Set ratesRun timeRead stockAttach evidence

Model controls

Change the arrival rate, service capacity, and time horizon. The native sliders remain the source of truth for every readout.

4.0
0 per hour10 per hour
3.0
0 per hour10 per hour
8
1 hour12 hours
Model boundary. The queue starts at zero. Rates stay constant. Completed work cannot exceed available work. The model omits priority, batching, retries, reviewer schedules, and item size.
Teaching model / browser-local / no network call

Queue behavior

New work
Review queue
8.0 items after 8 hours
Finished work
In 4.0minusOut 3.0equals+1.0 per hour
Backlog growsThe model reaches 8.0 queued items after 8 hours.
Simulated review queue over timeThe queue rises from zero to eight items over eight hours.8.000h8h
Sources read / October 9, 2026

Source log

Open the evidence boundary
  1. Meadows repository at revision bb23622 and public playground, inspected October 9, 2026. We verified the canonical MIT repository through the GitHub API, read the README and implementation, and entered | =>new work: 4 [review queue: 0] =>finished work | plus a proportional outflow formula in the public playground. The rendered page showed the named inflow, stock, and outflow with no page error. We did not install Nix, run the full repository test battery, or audit the numerical solver.
  2. Mermaid flowchart syntax, read October 9, 2026. This is the source for Mermaid's text definitions of nodes, links, direction, subgraphs, shapes, labels, and edge animation.
  3. Graphviz DOT language documentation, read October 9, 2026. This is the source for DOT's grammar for graphs, directed graphs, nodes, edges, attributes, subgraphs, and clusters.
  4. Hacker News discussion, "Meadows: a small language for stock-and-flow diagrams that run", item 50019535, read October 9, 2026. We resolved the exact item URL through the Hacker News API. The comments are reader reaction, not implementation evidence.

Scope: the queue dyno runs a small model written for this article. It does not embed Meadows, inspect a repository, read a real queue, predict staffing needs, or prove that the listed assumptions hold.