Context
ApexStack-managed projects should include architecture diagrams in their documentation. The CEO prefers the C4 model but is open to alternatives.
C4 Model Overview
The C4 model (Context, Container, Component, Code) provides 4 levels of zoom:
| Level |
What it shows |
Audience |
| L1 — Context |
System + external actors (users, third-party services) |
Everyone |
| L2 — Container |
High-level tech choices (frontend, backend, database, CDN) |
Dev team |
| L3 — Component |
Internal structure of a container (services, repositories, handlers) |
Dev team |
| L4 — Code |
Class/function level (rarely needed, auto-generated) |
Deep-dive |
Acceptance Criteria
Options to evaluate via /decide
| Tool |
Format |
Rendering |
Pros |
Cons |
| Structurizr DSL |
Custom DSL |
Structurizr Lite (Docker) or CLI |
Purpose-built for C4, best model |
Requires Java/Docker for rendering |
| Mermaid C4 |
Markdown-embeddable |
GitHub renders natively |
Zero setup, GitHub preview |
Limited C4 support, less precise |
| PlantUML C4 |
Text DSL |
plantuml.jar or server |
Mature C4 library, widely used |
Java dependency |
| D2 |
Text DSL |
d2 CLI (Go binary) |
Modern, beautiful output, no Java |
Not C4-native (general purpose) |
Recommendation
Mermaid C4 for L1/L2 (GitHub renders it inline, zero setup) + Structurizr DSL for L3+ when precision matters. Start with Mermaid — it's good enough for context and container diagrams, and every GitHub user can see them without tooling.
AgDR required
This is an architectural decision — diagramming tool choice affects the entire portfolio.
Context
ApexStack-managed projects should include architecture diagrams in their documentation. The CEO prefers the C4 model but is open to alternatives.
C4 Model Overview
The C4 model (Context, Container, Component, Code) provides 4 levels of zoom:
Acceptance Criteria
Options to evaluate via /decide
Recommendation
Mermaid C4 for L1/L2 (GitHub renders it inline, zero setup) + Structurizr DSL for L3+ when precision matters. Start with Mermaid — it's good enough for context and container diagrams, and every GitHub user can see them without tooling.
AgDR required
This is an architectural decision — diagramming tool choice affects the entire portfolio.