# 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

```bash
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

```bash
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.


---
Source: .claude/skills/leumas-architecture/SKILL.md
Canonical: https://docs.leumas.tech/p/skills/leumas-architecture