System maps for React Flow and Next.js

Draw systems
people can follow.

A starter for hand-placed maps: typed data, cards that say what they are, wires that say what they carry, and the whole canvas exported as PNG or SVG in either theme.

Open the live demo Source

Free & open source · MIT · Next.js 16 · React Flow 12 · v0.1.0

system-map.nichtlegacy.com/demo/example

The example map: a client outside the system, a request API inside an edge host frame, a processing frame with a worker and two readings, one primary orchestrator card, and object storage with the rendered report beneath it.

Pan, zoom, export

Ten cards, three wires

Each card kind is a React component with a fixed size, so layouts stay on a grid and the audits know what they measure. Colour says which family a card belongs to; the wire says what moves.

serviceA normal running service
primaryServiceThe main decision point
externalOutside the boundary
storageA path or a capacity
artefactThe output, as a picture
infraA host with its listeners
clusterA frame around related cards
laneReading order, left to right
statOne derived figure
barsRanked values, numbers shown

dataPayloads, jobs, stored records
managementControl, state and health signals
externalAnything crossing the boundary

Cards that say what they are

Identity apart from state

Name, role and address live in the topology. Latency, status and throughput live in state, ready to be fed by something live.

The Request API service card: an Online status, its role, a one-line description, latency and acceptance rate, and its address in mono

One card decides

The primary card gets the room: headline figures, the states work moves through, and what came out the other end.

The Orchestrator primary card with throughput, retries and success rate, then queued and running states beside completed and failed outcomes

Numbers you can read

Readings print their values. Colour is never the only cue: every bar carries its figure, every status its word.

The Queue health bars card: completed 84 percent, waiting 12 percent, failed 4 percent, each with a bar and its number

The export panel: dark or light, filled or transparent, 1x, 2x or 3x, then Save PNG, SVG or Copy

Export the
whole canvas.

PNG or SVG at 1×, 2× or 3×, dark or light, filled or transparent — the full graph, not the part on screen. The images on this page come out of that same panel.

Measured,
not eyeballed.

Positions are yours to place. Four audits check the result: wires through cards, labels crowding a plate, clipped text, and pages that scroll sideways on a phone. The first needs no browser and runs in CI.

system-map

$ npm run audit:geometry

example — 8 cards · 2 frames · 7 flows · extent 2352 × 736
  tightest passes:
    worker-accepted        144px from queue-health
    worker-orchestrator    180px from queue-health
    api-worker             180px from accepted
    orchestrator-archive   180px from report
    archive-report         256px from orchestrator
  no geometry problems

data/example/topology.ts

// a card: who it is, and where
{
  id: "api",
  position: { x: 464, y: 240 },
  name: "Request API",
  category: "Validation · routing",
  host: "192.0.2.10:443",
  icon: Workflow,
},

// a wire: what it carries, and in which order
{
  id: "api-worker",
  stage: 2,
  source: "api", target: "worker",
  flavor: "data",
  label: "job",
},

Four files,
one map.

No editor, no layout engine, no runtime service. A map is typed data you can review in a pull request.

topology.tsCards, frames, lanes and wires
state.tsThe values that change
index.tsReact Flow nodes, with sizes
counts.tsEvery number, derived

Run it

Clone the repository, install, and open localhost:3000/example:

Node.js 22.18 or newer. Nothing else: no database, no account.

Run it in Docker

Every green build on main publishes an image to the GitHub Container Registry:

Or docker compose up -d with the included compose.yaml — read-only, no capabilities. Add --build to serve your own map.

Make it yours

Copy data/example/ and app/example/, then edit the four files. The renderer never imports your data, so a second map costs a folder and a route. Drawing it with a coding agent? The react-flow skill teaches it the @xyflow/react API underneath:

Fictional by design

The example uses example.com, 192.0.2.0/24 and 2001:db8::/32 — addresses reserved for documentation — so a fork never starts out exposing a real network.

Releases

Versioned with release-please from Conventional Commits. Each release tags the image with its version and adds a changelog entry.

What it is not

Not a dashboard, not a diagram editor, not a live monitor. No analytics, no authentication, no telemetry. A map drawn once, so the next person can find their way without asking you.

Draw systemspeople can follow.