C4ModelStructurizr

---

title: C4 Model and Structurizr type: technique created: 2026-05-21 last_updated: 2026-05-26 related: ["radar/techniques/ArchitecturalDecisionRecords", "radar/techniques/RequestForDiscussion"] sources: ["https://dev.to/dorneanu/documentation-as-code-for-cloud-c4-model-structurizr-1ipe", "https://itnext.io/software-architecture-diagrams-with-c4-model-898adcb534c2"] radar_quadrant: Techniques radar_ring: Assess radar_position: inner

C4 Model and Structurizr

A technique for producing cloud architecture documentation as version-controlled code. The C4 Model provides a four-level abstraction hierarchy; Structurizr renders diagrams from a text DSL, enabling architecture diagrams to be stored alongside the systems they describe.

The C4 Model

C4 (Context, Containers, Components, Code) was introduced by Simon Brown as a way to produce consistent, audience-appropriate architecture diagrams without forcing a choice between detail and overview.

The four levels:

Level	Audience	Shows
1 — System Context	Non-technical stakeholders	The system and its external actors
2 — Container	Developers, architects	Deployable units (apps, services, databases)
3 — Component	Developers	Logical groupings inside a container
4 — Code	Developers	Class or module internals (rarely used)

Each level zooms in on the previous. Levels 1 and 2 cover most communication needs; level 3 documents implementation decisions within a service.

Structurizr DSL

Structurizr translates a plain-text workspace DSL into diagrams. A workspace defines elements (people, software systems, containers, components), relationships between them, and named views at each C4 level. The DSL is stored in a text file under version control.

workspace {
  model {
    user = person "End User"
    system = softwareSystem "Order Management" {
      api = container "API Service" "Python FastAPI"
      db  = container "Database" "PostgreSQL" "Database"
    }
    user -> api "Places order"
    api  -> db  "Reads and writes"
  }
  views {
    systemContext system "Context" { include * }
    container    system "Containers" { include * }
  }
}

The source article demonstrates using Structurizr Lite (self-hosted, free) with a docker-compose.yml to render diagrams locally without a cloud account.

Documentation as Code Benefits

Storing architecture diagrams as DSL text files rather than image exports produces three benefits:

1. Diff-ability. Architectural changes appear in pull requests as text diffs, reviewable alongside code changes.
2. Single source of truth. All four C4 views render from one workspace file; updating a component name propagates to every diagram automatically.
3. No diagram drift. Diagrams are regenerated from the authoritative model, not manually updated images that fall out of sync.

Relationship to ADR

C4 and Structurizr document the current architecture. radar/techniques/ArchitecturalDecisionRecords document why it is that way. The two techniques complement each other: ADRs explain the reasoning; C4 diagrams show the result.

Radar Assessment

C4 Model and Structurizr sit in the Assess ring of the Techniques quadrant, at inner position. First studied via the DEV Community article by Victor Dorneanu (2023-11-03). C4 is a mature model — Thoughtworks placed it in Adopt in 2021 — and Structurizr Lite is self-hostable and free. That maturity is third-party evidence, not first-person use: no Structurizr workspace has been built here, and the Trial ring requires that, so it stays at Assess. Inner position reflects a very low barrier to trial (Docker Compose, one DSL file), direct applicability to any cloud service documentation need, and strong complementarity with ADR already in this stack. The gate to Trial is a completed workspace covering at least one active project's architecture.