docs/architecture — how Ranger fits together
Written: 2026-08-15 · Established by: reading src/, rust/ and src-tauri/ at commit
93a9a67. Each diagram states its own sources in the same header.
Six diagrams, in Mermaid, each answering one question that would otherwise be answered by reading
source. They describe what is true, and decide nothing — docs/README.md's charter applies here in
full, so a file in this directory may be wrong or superseded without anything downstream breaking.
Read them in whatever order the question wants. There is no dependency between them except that 3 sits in the middle of 2 and 4.
GitHub renders these in an article column and gives you no way to enlarge them, so the wider ones
read better on the published site, where each diagram is full width with pan, zoom and full screen.
.github/workflows/architecture.yml builds and publishes
it from this directory on every push to main, and npm run architecture:build builds it locally
into dist-architecture/. npm run diagrams is the quicker local option — PNGs into .diagrams/,
no site.
| # | Diagram | The question it answers |
|---|---|---|
| 1 | What runs where | Which thread, which worker, which WebAssembly module, what survives a reload |
| 2 | How a dropped file becomes a picture | The parse pipeline, in order, and what each stage produces |
| 3 | The store, and who owns which state | The six slices, who reads them, what resets when |
| 4 | How a change to the program lands | Five controls, two store actions, one re-parse |
| 5 | The simulation pipeline | Where the time goes, and what a verdict is allowed to claim |
| 6 | What may import what | The measured dependency direction, and the four edges against it |
Why these six
They correspond to questions actually asked of this codebase. Cutting any one leaves a question answered only by reading source, and adding a seventh at this level of zoom would repeat one of them. Issue #349 has the full reasoning, including the alternatives that lost.
How these stay true
A diagram drawn once starts drifting the day it lands. This directory has two defences, and neither is care.
src/__tests__/pure/architecture-diagrams.test.ts is the mechanical half. It fails when a diagram
names a path that does not exist, when a top-level directory under src/ appears in no diagram, when
a numbered file loses its provenance header or its diagram, and when a diagram is missing from the
table above. So renaming a module or adding a subsystem breaks the build until the diagrams catch up.
What it cannot check is whether an edge is still real. A module that stops calling another leaves every path in the diagram valid and the arrow between them wrong.
The system-diagrams skill is the other half. It
is the process for re-deriving a diagram from current source rather than editing the picture that is
already there, and it is what catches a stale arrow. Run it when a subsystem changed shape, not on a
schedule — a recurring pass with nothing to find trains people to ignore it.
What is deliberately not here
Anything that decides. A diagram that says what the architecture should be is an ADR, and
belongs in adr/.
Rendered images. Mermaid renders natively on GitHub, and a committed PNG is a second copy that drifts against the first.
A repeat of CLAUDE.md's Source layout. That section is a directory listing and is currently
stale in both directions; correcting it is its own change, noted as out of scope on issue #349.