Systems blocks
| Block | Fields | Notes |
|---|---|---|
| system | name, summary, owner?, repos[], body? | C4 level 1 — one box to an outsider |
| container | system, name, summary, kind, technology?, repo?, body? | C4 level 2 — an independently runnable unit: a service, a database, a web app, a CLI, a queue |
| component | container, name, summary, kind?, technology?, body? | C4 level 3 — a cohesive part with no deployment identity |
| code_item | component? or container?, name, summary?, kind, payload children, body? | C4 level 4 — extractor-generated, public interface only; kind selects the payload family below |
| screen | name, summary?, component?, container?, route?, personas[], nav_to[], body? | a user-facing surface — web page, CLI command, TUI screen; attach it to its component (or container when components aren't modelled); the body holds the wireframe or terminal mock-up |
A code_item's kind selects which payload children the renderer reads:
| kind | payload children | renders as |
|---|---|---|
| :module_graph | code_node (name, deps[], summary?) | layered dependency diagram |
| :db_schema | db_table → db_column (type, pk, nullable, ref_table?, ref_column?) | node tables with FK edges on row-level ports |
| :class_diagram | code_node with members[] | class boxes with member rows, dep edges |
| :api | api_endpoint (method, path, summary, request?, response?) | endpoint table + detail |
| :other | — | just the body |
Who populates: systems/containers/components by hand (interview or scan); code items by extractor, and they document the public interface — internals are read from the code, not mirrored into the WAD. Code items and screens both live at component level: a component's page renders each owned code item's diagram in place (drill into the code item's own page for detail) and the component's screen-flow diagram (never on the system or container page — wrong altitude).