Systems blocks

Generated Markdown for references/fact_system_blocks.md.

Open book page Back to the skill graph

# 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).

## Related

- [The C4 drill-down](../references/concept_c4_drilldown.md)

[← Back to SKILL.md](../SKILL.md)