Skip to content
arcade-agent

The C4 model

Once you accept that “architecture” needs describing at all, the next problem is scale: one diagram can’t show a whole system without turning into an unreadable wall of boxes and arrows. The C4 model, created by Simon Brown, fixes this by describing a system at four zoom levels instead of one:

  • Context — the system as a single box, plus the people and other systems it talks to. The view you’d show someone who’s never seen the codebase.
  • Containers — the system broken into its deployable/runnable units: the web app, the API, the database, a background worker. Still no code-level detail.
  • Components — each container broken into its major structural groupings and how they depend on each other. This is where most of the day-to-day design decisions actually live — which module can call which, where a boundary is supposed to hold.
  • Code — class diagrams, if you need them at all. C4’s own guidance treats this level as optional and often auto-generated, precisely because it changes too fast to hand-maintain.

The diagram below steps through all four levels for a generic AI coding agent, zooming from “who talks to it” down to “what’s inside the CLI process”:

The four C4 zoom levels — Context, Containers, Components, Code — stepped from a generic AI coding agent's context down to its internals L1 — Context Developer Coding agent LLM API Code repository L2 — Containers CLI app Local MCP servers zoom L3 — Components (inside the CLI) Planner Tool router Context memory zoom L4 — Code classes & functions zoom

Simplified — illustrative, not a complete architecture. No real vendor’s coding agent is named or claimed to match this exactly.

The level that matters for the day-to-day question “am I allowed to import this?” is Components — one level up from raw code, one level down from “which service is this.” It’s also the level most teams never get to: Context and Containers get a diagram during initial design, and then the component-level picture is left as tribal knowledge, because keeping a component diagram in sync with a changing codebase by hand is a losing battle. That’s the same drift problem from What is software architecture? showing up again, at the specific level where it hurts the most.

Honesty check: arcade-agent is not a C4 tool, and it doesn’t claim to implement C4’s Context or Container levels — it has no notion of “system,” “person,” or “deployable unit.” That’s the honest scope: one level of C4, kept current automatically, not a replacement for the model.

In arcade-agent: what it recovers — components and the dependencies between them — corresponds to C4’s Component level, and only that level. visualize exports that recovered structure as Mermaid or DOT, which you can drop straight into a C4 component diagram alongside hand-drawn Context and Container diagrams for the levels above it. See Agent tools for visualize.