c4-model

name

c4-model

description

Create, revise, and review C4 model software architecture diagrams and supporting architecture documentation. Use when Codex needs to describe static software structure with System Context, Container, Component, Code, Deployment, System Landscape, or runtime diagrams; choose diagram scope and audience; turn codebase knowledge into C4 views; critique architecture diagrams for unclear vocabulary, missing relationships, absent technology details, or model-code gaps.

C4 Model

Overview

Use this skill to create and assess C4 model architecture diagrams for software systems. The guidance is distilled from Simon Brown's "The C4 model for visualising software architecture", parsed from assets/c4_model.pdf with lit.

Core Workflow

1. Establish the system in scope, the audience, and whether the work is design-time, documentation of an existing system, or review of existing diagrams.
2. Use a shared vocabulary before drawing: people use software systems; software systems contain containers; containers contain components; components are implemented by code elements.
3. Start with System Context and Container diagrams for most systems. Add Component diagrams only for containers where the internal structure clarifies the story. Add Code diagrams rarely, for complex components or reusable implementation patterns.
4. Keep each diagram at one level of abstraction. Split large diagrams by bounded context, feature, use case, controller, workflow, or other focused story instead of enlarging the canvas.
5. Add enough text to remove ambiguity: every element should have a name and short responsibility; containers and components should include technology when known; important relationships should have labelled intent and, when useful, communication style or protocol.
6. Check that the diagram reflects reality: each architectural element should map to something real in the code, deployment, or ownership model.

Reference Routing

• Read references/vocabulary-and-levels.md when deciding which C4 diagram level to create, what elements belong on each level, or how to model microservices, serverless functions, data stores, and shared components.