Pictures

Pictures

Reading the map

Columns, left to right: what people use, entry points, logic, data access, stored data, outside the system. A box is a part, with its file count and (for an entry point) its routes grouped by path. Lines: calls (grey), reads and writes data (blue), over the network (amber, dashed). Each part keeps only its strongest connections (top_flows); all of them are in system.json.

Reading the diff

Only what changed is drawn, lit: + added, ~ changed, − removed. The parts it touches stand beside it unlit, for context. New routes, settings and table changes are listed inside their boxes. Deployment files that changed are named under the picture.

Your own pictures

system-diff draw SPEC.json draws a JSON spec in the same look, as SPEC.svg beside it. A spec has a picture key and an optional label.

map: boxes in columns.

{"picture": "map", "label": "Where state lives",
 "columns": [["logic", "Logic"], ["store", "Stored data"]],
 "nodes": [{"id": "api", "col": "logic", "title": "API", "sub": "3 files", "lines": ["orders", {"code": "GET /orders"}]},
           {"id": "db", "col": "store", "title": "PostgreSQL", "type": "store"}],
 "edges": [{"from": "api", "to": "db", "kind": "data"}]}

Node type: component, store or host. Node style: new, legacy, shared or undeclared. Edge kind: call, data or network.

stages: a process left to right.

{"picture": "stages", "label": "Release",
 "stages": [{"title": "Build", "lines": ["tests", "wheel"]}, {"title": "Review", "hi": true}, {"title": "Ship"}],
 "loops": [{"from": 1, "to": 0, "label": "changes asked"}],
 "exits": [{"label": "Abandoned", "note": "closed without merge"}],
 "gate": {"text": "A person approves", "from": [1]}}

sequence: who talks to whom, in order.

{"picture": "sequence", "label": "Sign in",
 "lanes": [{"id": "you", "title": "You", "person": true}, {"id": "web", "title": "Web app"}, {"id": "idp", "title": "Identity provider"}],
 "steps": [{"from": "you", "to": "web", "text": "opens the app"},
           {"from": "web", "to": "idp", "text": "redirects to sign in"},
           {"note": "the session lasts 8 hours", "over": ["web", "idp"]}]}

Layouts are deterministic and keyed by id, so a box that did not change does not move.