Leumas Architecture

Read or change the Leumas architecture graph — add a node, wire two things together, bind a node to real code. Use for architecture map, ecosystem graph, ops/architecture, pnpm arch.

The architecture graph

ops/architecture/*.graph.json is the map of the Leumas ecosystem: Leumas at the root, products branching off it, each product owning its own subtree. Leumas Admin renders and edits it at /architecture. It is a repo file, so your edit and a canvas edit are the same edit.

Use the CLI. Do not hand-edit the JSON. Position, lane, colour, card shape, region and edge ids are all derived — say what a thing is and what owns it, and the tools do the rest.

Read

pnpm arch ls                      # every node: id, kind, owner, label
pnpm arch show studio             # one node + every wire touching it
pnpm arch next                    # planned work whose owner is already built — start here

Graphs: ecosystem (default — Leumas → products → domains → tabs → sub-tabs, every one the nav manifests declare) · leumas-api · shared-code.

The tree under Studio and Admin is generated: node ops/architecture/import-nav.mjs --write walks both nav manifests. It never overwrites a label, blurb, note, status, proof or position you set by hand — so add a domain to a manifest, re-run it, and only the new nodes appear.

Change

pnpm arch add <id> --owner <id> --label "..." --refs <repo/path> [--uses <id>] [--blurb "..."]
pnpm arch wire <from> <to> --uses          # also: --owns --governs --exposes
pnpm arch unwire <from> <to>
pnpm arch mv <id> --owner <newOwner>       # re-parent; lane/region/position recomputed
pnpm arch set <id> --label "..." --refs <path>
pnpm arch rm <id> [--force]                # --force also removes what it owns
pnpm arch tidy                             # place anything new; --only all re-ranks the whole graph
pnpm arch status <id> --done               # also --planned --building --verified
pnpm arch status <id> --verified --proof "pnpm check:nav"
pnpm check:architecture                    # always finish with this

Status — this is a worklist, keep it true

Every node is planned → building → done → verified, and the guard checks the claim against the filesystem:


`planned`	not built. If its code turns up, the guard says "mark it done".
`building`	someone is on it. Unchecked — the one honest gap.
`done`	[critical] hard fail if any exact ref does not resolve
`verified`	[critical] hard fail without `--proof "<a pnpm script that exists>"`

When you finish a piece of work, mark its node. That is what makes pnpm arch next mean something, and it is the only reason the graph can tell the next agent what is left.

Every node has exactly one owner, so --owner is required on add. --refs are repo-relative paths; prefix one with ? if it is planned rather than built.

The four relationships

flag	means
`--owns`	the target belongs to the source — this is the tree, one owner per node
`--governs`	the source sets policy for something it does not own
`--uses`	the source imports or calls the target
`--exposes`	the target is a faculty the source offers

Two rules

Never invent a position. add writes no coordinate; pnpm arch tidy places whatever is new, and the canvas has the same button. The layout is deterministic and idempotent, so running it twice is a no-op — that is what makes a tidied graph committable.

When a graph gets big, go deeper, not wider. Move detail into a new <id>.graph.json and point the parent node at it with --into <graphId>. The root graph is meant to stay the same size however large Leumas gets.

If you must touch the file

Every node and edge is exactly one line, so grep -n '"id":"studio"' ops/architecture/ecosystem.graph.json gives you the line to edit. Never read the whole file. Run pnpm check:architecture --fix afterwards to restore canonical form — a reflowed file breaks every line anchor and turns a one-node change into a whole-file diff.