| name | c4-architecture |
| domain | development |
| skill_type | skill |
| description | Model AND decide software architecture. (1) Generate C4 documentation with Mermaid (Context/Container/Component/Deployment) — triggers "architecture diagram", "C4 diagram", "system context", "container/component/deployment diagram", "document architecture". (2) Reason about architecture DECISIONS grounded in canonical references (Hohpe, Richards/Ford, Hard Parts, Tar Pit, Kleppmann DDIA, DDD, Team Topologies) — triggers "should we split/merge/extract this service", "monolith vs microservices", "service/bounded-context boundaries", "saga / distributed transaction / consistency model", "draft an ADR", "fitness functions". Do NOT use for general flowcharts or ERD (use mermaid-diagrams), code-level refactoring, or framework picks (React vs Vue). |
| license | MIT |
| tags | ["c4","architecture","mermaid","diagrams","system-design","documentation"] |
| metadata | {"version":"1.2.1","author":"Genius"} |
C4 Architecture Documentation
This skill covers two complementary jobs. Pick by what the user is asking:
- Model the architecture → C4 diagrams (the rest of this file). Use when the
ask is to document / visualize / diagram a system.
- Decide the architecture → see Architecture Decisions
at the bottom. Use when the ask is a forward-looking "should we split / merge /
extract this?", a saga/consistency-model choice, or an ADR — questions about the
structure of the system, not how to draw it.
Generate software architecture documentation using the C4 model. C4 describes architecture at four zoom levels: Context → Container → Component → Code (deployment). Use Mermaid syntax for all diagrams.
KG-Backed Extraction (Source of Truth)
To ensure 100% accuracy, you MUST build your C4 diagrams using real data from the Knowledge Graph rather than relying solely on static analysis.
- Query the Graph: Use the
kg_query or kg_pillar_view tools from the agent-utilities-kg MCP server to extract the actual component nodes, container boundaries, and DEPENDS_ON relationships.
- Translate to Mermaid: Map the returned graph topology directly into the C4 Mermaid syntax. This guarantees the diagram perfectly reflects the real, running system architecture.
C4 Diagram Levels
Select the appropriate level based on the audience and documentation need:
| Level | Diagram Type | Audience | Shows | When to Create |
|---|
| 1 | C4Context | Everyone | System + external actors | Always (required) |
| 2 | C4Container | Technical | Apps, databases, services | Always (required) |
| 3 | C4Component | Developers | Internal components | Only when it adds value |
| 4 | C4Deployment | DevOps | Infrastructure nodes | For production systems |
| - | C4Dynamic | Technical | Request flows (numbered) | For complex workflows |
[!TIP]
Context + Container diagrams are sufficient for most software development teams. Only create Component/Code diagrams when they genuinely add value.
Quick Start Examples
Level 1: System Context
C4Context
title System Context - E-Commerce Platform
Person(customer, "Customer", "Places and tracks orders")
Person(admin, "Admin", "Manages products and orders")
System(store, "E-Commerce Platform", "Handles product browsing, orders, and payments")
System_Ext(payment, "Payment Gateway", "Stripe — processes card payments")
System_Ext(email, "Email Service", "SendGrid — sends order notifications")
Rel(customer, store, "Browses and orders")
Rel(admin, store, "Manages catalog and orders")
Rel(store, payment, "Processes payments", "HTTPS")
Rel(store, email, "Sends notifications", "HTTPS")
Level 2: Container Diagram
C4Container
title Container Diagram - E-Commerce Platform
Person(customer, "Customer", "Places orders")
Container_Boundary(app, "E-Commerce Platform") {
Container(spa, "Web App", "React, TypeScript", "Single-page storefront")
Container(api, "API Service", "Python/FastAPI", "REST API for business logic")
ContainerDb(db, "Database", "PostgreSQL", "Orders, products, users")
ContainerQueue(queue, "Message Queue", "Redis", "Async job processing")
}
System_Ext(payment, "Payment Gateway", "Stripe")
Rel(customer, spa, "Uses", "HTTPS")
Rel(spa, api, "API calls", "JSON/HTTPS")
Rel(api, db, "Reads/writes", "SQL")
Rel(api, queue, "Enqueues jobs")
Rel(api, payment, "Charges cards", "HTTPS")
Level 3: Component Diagram
C4Component
title Component Diagram - API Service
Container_Boundary(api, "API Service") {
Component(auth, "Auth Controller", "FastAPI router", "Handles login and JWT")
Component(orders, "Order Controller", "FastAPI router", "CRUD for orders")
Component(orderSvc, "Order Service", "Business logic", "Validates and processes orders")
Component(repo, "Order Repository", "SQLAlchemy", "Database access layer")
}
ContainerDb(db, "Database", "PostgreSQL")
Rel(auth, orderSvc, "Authenticates requests")
Rel(orders, orderSvc, "Delegates to")
Rel(orderSvc, repo, "Reads/writes")
Rel(repo, db, "Queries", "SQL")
Dynamic Diagram (Request Flow)
C4Dynamic
title Dynamic Diagram - Order Checkout Flow
Container(spa, "Web App", "React")
Container(api, "API Service", "FastAPI")
Container(db, "Database", "PostgreSQL")
System_Ext(payment, "Payment Gateway", "Stripe")
Rel(spa, api, "1. POST /orders", "JSON/HTTPS")
Rel(api, db, "2. Save order", "SQL")
Rel(api, payment, "3. Charge card", "HTTPS")
Rel(api, spa, "4. Return order ID", "JSON/HTTPS")
Deployment Diagram
C4Deployment
title Deployment - Production on AWS
Deployment_Node(browser, "Customer Browser", "Chrome/Firefox") {
Container(spa, "Web App", "React", "Hosted on CloudFront")
}
Deployment_Node(aws, "AWS us-east-1") {
Deployment_Node(ecs, "ECS Fargate") {
Container(api, "API Service", "FastAPI", "REST API")
}
Deployment_Node(rds, "RDS db.r5.large") {
ContainerDb(db, "Database", "PostgreSQL", "Application data")
}
}
Rel(spa, api, "API calls", "HTTPS")
Rel(api, db, "Reads/writes", "TCP/SSL")
Element Syntax
People and Systems
Person(alias, "Label", "Description")
Person_Ext(alias, "Label", "Description") # External person
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description") # External system
SystemDb(alias, "Label", "Description") # Database system
SystemQueue(alias, "Label", "Description") # Queue system
Containers
Container(alias, "Label", "Technology", "Description")
Container_Ext(alias, "Label", "Technology", "Description")
ContainerDb(alias, "Label", "Technology", "Description")
ContainerQueue(alias, "Label", "Technology", "Description")
Components
Component(alias, "Label", "Technology", "Description")
Component_Ext(alias, "Label", "Technology", "Description")
ComponentDb(alias, "Label", "Technology", "Description")
Boundaries
Enterprise_Boundary(alias, "Label") { ... }
System_Boundary(alias, "Label") { ... }
Container_Boundary(alias, "Label") { ... }
Relationships
Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")
BiRel(from, to, "Label") # Bidirectional
Rel_U(from, to, "Label") # Upward
Rel_D(from, to, "Label") # Downward
Rel_L(from, to, "Label") # Leftward
Rel_R(from, to, "Label") # Rightward
Styling and Layout
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")
UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")
Best Practices
- Every element must have — name, technology (where applicable), and description
- Use unidirectional arrows — bidirectional arrows create ambiguity; use two arrows if truly bidirectional
- Label arrows with action verbs — "Sends events to", "Reads from", "Authenticates via"
- Include technology labels — "JSON/HTTPS", "SQL", "gRPC"
- Stay under 20 elements per diagram — split complex systems into multiple diagrams
- Always include a title —
title System Context diagram for [System Name]
- Start at Level 1 — context diagrams frame the scope before drilling into containers
Common Mistakes to Avoid
- Confusing containers (deployable units) with components (non-deployable logical parts)
- Modeling shared libraries as containers
- Showing a message broker (Kafka) as a single box instead of individual topics
- Adding undefined abstraction levels (e.g., "subcomponents")
- Removing type labels to "simplify" — they communicate essential technology context
Output Location
Write architecture documentation to docs/architecture/ with this naming convention:
c4-context.md — System context diagramc4-containers.md — Container diagramc4-components-{feature}.md — Component diagrams per featurec4-deployment.md — Deployment diagramc4-dynamic-{flow}.md — Dynamic diagrams for specific flows
Audience-Appropriate Detail
| Audience | Recommended Diagrams |
|---|
| Executives | System Context only |
| Product Managers | Context + Container |
| Architects | Context + Container + key Components |
| Developers | All levels as needed |
| DevOps | Container + Deployment |
Architecture Decisions
For decision questions (split/merge/extract, monolith-vs-microservices, saga &
consistency design, ADR drafting) — not diagram requests — reason from canonical
references rather than intuition. Grounded in the software-architect skill by
Chris Graffagnino (MIT); the seven distilled sources live under
references/architecture-decisions/ (see its ATTRIBUTION.md).
The seven references — progressive disclosure
Load the first two always; load the rest only when the question touches their
domain (keeps reasoning grounded without overload).
Reference (references/architecture-decisions/…) | Gives you | Load when |
|---|
hohpe-architect-principles.md | Posture, framing, "map the map" | Always |
richards-ford-architect-principles.md | Trade-off method, ADR template, "-ilities" | Always |
hard-parts-pattern-catalog.md | Distributed-systems pattern lookup | Patterns at stake |
moseley-marks-tar-pit.md | Essential vs accidental complexity | Every design |
kleppmann-data-intensive-applications.md | Consistency, replication, isolation | Data flow involved |
evans-vernon-ddd-distilled.md | Bounded contexts, aggregates | Boundaries at stake |
skelton-pais-team-topologies.md | Conway's Law, fracture planes, cognitive load | Team structure involved |
Decision workflow
- Reframe before answering. Reject false binaries ("micro vs mono" = design-time
modularity × runtime modularity). Name the architecture characteristics actually at
stake. Call out an answer-in-search-of-a-question (a pre-committed tech being
rationalized).
- Name the trade-off dimensions — for distributed questions, the three coupling
axes: communication (sync/async), consistency (atomic/eventual), coordination
(orchestrated/choreographed); plus coupling, complexity, responsiveness, scale.
- Walk the four lenses (load each reference as its lens activates):
- Semantic (DDD) — does the boundary follow the domain / ubiquitous language?
- Data (DDIA) — what consistency model does this implicitly require? Name it
(linearizable / causal / eventual); is "exactly-once" really "effectively-once via
idempotence"?
- Complexity (Tar Pit) — essential vs accidental state for every cache/projection;
could it be re-derived? Applies to every question.
- Org (Team Topologies) — how many stream-aligned teams does this need? Aligned to
a real fracture plane? If team count is unknown, ask before recommending a split.
- Recommend as the least-worst combination of trade-offs, not "the best." Name the
conscious trade-offs and what evidence would flip the decision (latency > X, team
count < N). State what you don't know (SLOs, team count, domain framing).
Mode cheatsheet
- Review — Hohpe §10: an architecture is suitable or not, not good/bad. Check they
understood needs and made trade-offs consciously; don't hunt for flaws to justify the review.
- Decomposition — is there a real modularity driver? Walk disintegrators and
integrators; match the boundary to a DDD context and a team fracture plane.
- Distributed transaction / consistency — distributed ACID is rarely affordable; prefer
event-based eventual consistency + sagas; name the consistency level precisely; inventory
the accidental state a saga adds (log, compensations, DLQs).
- Complexity diagnosis — locate state, locate control, classify essential/accidental,
apply Avoid + Separate.
ADR template (offer this as the output artifact)
Context — The problem, in one or two sentences. Alternatives considered.
Decision — The decision and its detailed justification.
Consequences — What changes after this; the trade-offs accepted.
Optionally: the fitness functions that will guard it.
Keep ADRs to one or two pages of plain markdown; write to docs/architecture/adr/.
