| name | c4-architecture |
| description | Generate architecture documentation using C4 model ASCII diagrams including C4 Dynamic Diagrams for detailed interface communication. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, describe interface communication, show request flows, or generate context/container/component/deployment/dynamic diagrams. Triggers include 'architecture diagram', 'C4 diagram', 'system context', 'container diagram', 'component diagram', 'deployment diagram', 'dynamic diagram', 'interface communication', 'Schnittstellenkommunikation', 'request flow', 'sequence', 'interaction', 'document architecture', 'visualize architecture'. Target audience: Integration Architects, Solution Architects. |
C4 Architecture Documentation
Generate software architecture documentation using C4 model diagrams in ASCII notation.
Workflow
- Understand scope - Determine which C4 level(s) are needed based on audience
- Analyze codebase - Explore the system to identify components, containers, and relationships
- Generate diagrams - Create ASCII C4 diagrams at appropriate abstraction levels
- Document - Write diagrams to markdown files with explanatory context
C4 Diagram Levels
Select the appropriate level based on the documentation need:
| Level | Diagram Type | Audience | Shows | When to Create |
|---|
| 1 | Context | Everyone | System + external actors | Always (required) |
| 2 | Container | Technical | Apps, databases, services | Always (required) |
| 3 | Component | Developers | Internal components | Only if adds value |
| 4 | Deployment | DevOps | Infrastructure nodes | For production systems |
| - | Dynamic | Integration/Solution Architects | Request flows (numbered, temporal) | For interface communication & complex workflows |
Key Insight: "Context + Container diagrams are sufficient for most software development teams." Only create Component/Code diagrams when they genuinely add value. Use Dynamic diagrams when temporal interaction sequences or detailed interface communication must be documented.
ASCII Notation Reference
Element Types
Akteur (Person): โโโโโโโโโโโโโโโโโโโโโโโโ
โ โบ Name โ
โ [Rolle/Beschreibung]โ
โโโโโโโโโโโโโโโโโโโโโโโโ
Zentrales System: โโโโโโโโโโโโโโโโโโโโโโโโ
โ <<system>> โ
โ Systemname โ
โ [Kurzbeschreibung] โ
โโโโโโโโโโโโโโโโโโโโโโโโ
Internes System: โโโโโโโโโโโโโโโโโโโโโโโโ
โ <<system>> โ
โ Systemname โ
โ [Beschreibung] โ
โโโโโโโโโโโโโโโโโโโโโโโโ
Externes System: โ โ โ โ โ โ โ โ โ โ โโ
โ <<external system>> โ
โ Systemname โ
โ [Beschreibung] โ
โ โ โ โ โ โ โ โ โ โ โโ
Container: โโโโโโโโโโโโโโโโโโโโโโโโ
โ <<container>> โ
โ Name โ
โ [Technologie] โ
โ Beschreibung โ
โโโโโโโโโโโโโโโโโโโโโโโโ
Container (Datenbank): โโโโโโโโโโโโโโโโโโโโโโโโ
โ <<database>> โ
โ Name โ
โ [Technologie] โ
โ Beschreibung โ
โโโโโโโโโโโโโโโโโโโโโโโโ
Container (Queue): โโโโโโโโโโโโโโโโโโโโโโโโ
โ <<queue>> โ
โ Name โ
โ [Technologie] โ
โ Beschreibung โ
โโโโโโโโโโโโโโโโโโโโโโโโ
Component: โโโโโโโโโโโโโโโโโโโโโโโโ
โ <<component>> โ
โ Name โ
โ [Technologie] โ
โ Beschreibung โ
โโโโโโโโโโโโโโโโโโโโโโโโ
Relationships
Synchron: โโโโโโ Beschreibung โโโโโโโ
[Protokoll]
Asynchron: โ โ โ Beschreibung โ โ โโ
[Protokoll]
Bidirektional: โโโโโโ Beschreibung โโโโโโ
[Protokoll]
Synchrone Antwort: โโโโโโ Antwort โโโโโโโโโโ
[Protokoll]
Asynchrone Antwort: โโ โ โ Antwort โ โ โ โ โ
[Protokoll]
Boundaries
System Boundary: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ [System Name] โ
โ โโโโโโโโโโ โโโโโโโโโโ โ
โ โ Elem A โ โ Elem B โ โ
โ โโโโโโโโโโ โโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Trust Boundary: โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Boundary Name โ
โ ...Elemente... โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Enterprise Boundary: โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Enterprise Name โ
โ โโโโโโโโโโ โโโโโโโโโโ โ
โ โ Sys A โ โ Sys B โ โ
โ โโโโโโโโโโ โโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Deployment Nodes
Deployment Node: โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ <<node>> โ
โ Name [Type] โ
โ โโโโโโโโโโ โโโโโโโโโโ โ
โ โ Cont A โ โ Cont B โ โ
โ โโโโโโโโโโ โโโโโโโโโโ โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Quick Start Examples
System Context (Level 1)
โโโโโโโโโโโโโโโโโโโโ
โ โบ User โ
โ [Tracks workoutsโ
โ and exercises] โ
โโโโโโโโโโฌโโโโโโโโโโ
โ
Uses โโโโโโโ
[HTTPS]
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ <<system>> โ
โ Workout Tracker โ
โ [Vue PWA for tracking โ
โ strength & CrossFit โ
โ workouts] โ
โโโโโโโโโโโโโโคโโโโโโโโโโโโโโ
โ
Persists โโโโโโ
data to
[IndexedDB]
โ
โผ
โ โ โ โ โ โ โ โ โ โ โ โ โ
โ <<external system>> โ
โ Web Browser โ
โ [Stores data in โ
โ IndexedDB] โ
โ โ โ โ โ โ โ โ โ โ โ โ โ
Container Diagram (Level 2)
โโโโโโโโโโโโโโโโโโโโ
โ โบ User โ
โ [Tracks โ
โ workouts] โ
โโโโโโโโโโฌโโโโโโโโโโ
โ
Uses โโโโโโ
[HTTPS]
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ [Workout Tracker PWA] โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โ โ <<container>> โ โ <<container>> โ โ
โ โ SPA โโโโโ State Mgmt โ โ
โ โ [Vue 3, TS] โ โ [Pinia] โ โ
โ โ Single-page app โ โ App state โ โ
โ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโฌโโโโโโโโโโ โ
โ โ โ
โ Persists โโ โ
โ [Dexie ORM] โ
โ โ โ
โ โผ โ
โ โโโโโโโโโโโโโโโโโโโโ โ
โ โ <<database>> โ โ
โ โ IndexedDB โ โ
โ โ [Dexie] โ โ
โ โ Local workout โ โ
โ โ storage โ โ
โ โโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Component Diagram (Level 3)
โโโโโโโโโโโโโโโโโโโโ
โ <<container>> โ
โ Views โ
โ [Vue Router] โ
โโโโโโโโโโฌโโโโโโโโโโ
โ
Uses โโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ [Workout Feature] โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โ โ <<component>> โ โ <<component>> โ โ
โ โ useWorkout โโโโ useTimer โ โ
โ โ [Composable] โ โ [Composable] โ โ
โ โ Workout exec. โ โ Timer state โ โ
โ โ state โ โ machine โ โ
โ โโโโโโโโโโฌโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ Saves โโโโ โ
โ to โ
โ โ โ
โ โผ โ
โ โโโโโโโโโโโโโโโโโโโโ โ
โ โ <<component>> โ โ
โ โ WorkoutRepo โ โ
โ โ [Dexie] โ โ
โ โ Workout persist.โ โ
โ โโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Deployment Diagram
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ <<node>> Customer Browser โ
โ [Chrome/Firefox] โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโ โ
โ โ <<container>> โ โ
โ โ SPA โ โ
โ โ [React] โ โ
โ โ Web application โ โ
โ โโโโโโโโโโฌโโโโโโโโโโ โ
โฐโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ
API calls โ
[HTTPS]
โ
โผ
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ <<node>> AWS Cloud [us-east-1] โ
โ โ
โ โญโโโโโโโโโโโโโโโโโโโโโโฎ โญโโโโโโโโโโโโโโโโโโโโโโฎโ
โ โ <<node>> ECS Clusterโ โ <<node>> RDS โโ
โ โ [Fargate] โ โ [db.r5.large] โโ
โ โ โ โ โโ
โ โ โโโโโโโโโโโโโโโโโโโโโ โ โโโโโโโโโโโโโโโโโโโโโโ
โ โ โ <<container>> โโ โ โ <<database>> โโโ
โ โ โ API Service โโโโโ โ Database โโโ
โ โ โ [Node.js] โโ โ โ [PostgreSQL] โโโ
โ โ โ REST API โโ โ โ Application data โโโ
โ โ โโโโโโโโโโโโโโโโโโโโโ โ โโโโโโโโโโโโโโโโโโโโโโ
โ โฐโโโโโโโโโโโโโโโโโโโโโโฏ โฐโโโโโโโโโโโโโโโโโโโโโโฏโ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
C4 Dynamic Diagram (Interface Communication)
Purpose
C4 Dynamic Diagrams show the runtime interactions between elements (persons, systems,
containers, components) for a specific use case or business process. Interactions are
numbered to visualize temporal sequence โ similar to UML Sequence Diagrams, but in
C4 style and at the desired abstraction level.
Target Audience
- Integration Architects: Interface communication, protocols, data flows between systems
- Solution Architects: End-to-end flow of a use case across system boundaries
When to Use
Use Dynamic Diagrams when:
- The temporal sequence of interactions between systems or components must be described
- Interface communication needs detailed documentation (which system calls what, when?)
- A specific use case / business process across multiple systems must be visualized
- Integration scenarios are analyzed or documented (e.g., onboarding flow, order process, data synchronization)
- The question is: "How do the systems communicate?" (not just "with whom?")
Abstraction Levels
| Level | Elements | Typical Use |
|---|
| System Context | Persons โ Systems | Overview: Which systems participate in a process? |
| Container | Containers within systems (Web-App, API, DB, Queue) | Detail: How do calls flow within and between systems? |
| Component | Components within a container (Controller, Service, Repository) | Fine detail: How is a call processed within a container? |
Interactive Dialog
When creating a Dynamic Diagram, follow this structured process:
Step 1: Identify Use Case / Scenario
Ask:
- Which use case or business process should be depicted?
(e.g., "User signs in", "Order is placed", "Master data is synchronized")
- What is the triggering event (trigger)? (e.g., user action, timer, incoming message)
- What is the expected outcome at the end of the flow?
Step 2: Determine Abstraction Level
Ask:
- At which level should the diagram be created?
- System Context: Interactions between whole systems (overview)
- Container: Interactions between containers like web-app, API, database (recommended for interface documentation)
- Component: Interactions between components within a container (fine detail)
If a C4 System Context Diagram has already been created in the conversation, reference
the identified systems and suggest the Container level as the next detail step.
Step 3: Identify Participating Elements
Ask (adapted to chosen level):
Collect elements in a table:
| # | Element | Type | Belongs to | Description |
|---|-----------------|----------------------|----------------|--------------------------|
| 1 | Sachbearbeiter | Actor | โ | Triggers the process |
| 2 | Web-Frontend | Container (SPA) | Portal-System | Angular-based UI |
| 3 | API-Gateway | Container (Service) | Portal-System | Kong Gateway, Routing |
| 4 | Fachservice | Container (Service) | Backend-System | Spring Boot REST-API |
| 5 | PostgreSQL | Container (Database) | Backend-System | Business data |
| 6 | SAP ERP | External System | โ | Financial accounting |
Confirm the table with the user before proceeding.
Step 4: Capture Interaction Steps
Ask:
- Describe the flow step by step:
- Who calls whom?
- What is transmitted/requested?
- Which protocol/technology is used? (REST/JSON, gRPC, AMQP, SQL, JDBC, GraphQL, SOAP, SFTP, ...)
- Is the call synchronous or asynchronous?
- Is there a response/return? (e.g., "returns order confirmation")
Collect steps in a numbered table:
| Step | From | To | Action | Protocol | Sync/Async | Response |
|------|----------------|----------------|------------------------------|------------|------------|-------------------------|
| 1 | Sachbearbeiter | Web-Frontend | Opens order form | HTTPS | Sync | โ |
| 2 | Web-Frontend | API-Gateway | POST /api/orders | REST/JSON | Sync | 202 Accepted |
| 3 | API-Gateway | Fachservice | Forward POST /orders | REST/JSON | Sync | 202 Accepted |
| 4 | Fachservice | PostgreSQL | INSERT INTO orders | JDBC/SQL | Sync | OK |
| 5 | Fachservice | SAP ERP | Create booking | SOAP/XML | Async | โ |
| 6 | SAP ERP | Fachservice | Booking confirmation (CB) | REST/JSON | Async | Booking number |
| 7 | Fachservice | PostgreSQL | UPDATE orders SET status=... | JDBC/SQL | Sync | OK |
Confirm with user before proceeding.
Step 5: Error Cases and Alternative Paths (optional)
Ask:
- Are there error cases to be shown? (e.g., "What happens if SAP is unreachable?")
- Are there alternative paths? (e.g., "If customer already exists, step X is skipped")
If yes, capture as additional steps with marking (e.g., "5a" for alternative to step 5).
Step 6: Generate Diagram
Dynamic Diagram Notation
Participating elements as columns (similar to Sequence Diagram):
โโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โ โ โ โ โ โ โโ
โ โบ Name โ โ <<container>> โ โ <<external>> โ
โ [Rolle] โ โ Servicename โ โ Systemname โ
โโโโโโฌโโโโโโ โโโโโโโโฌโโโโโโโโโ โ โ โ โโฌโ โ โ โ
โ โ โ
โ โ โ
Synchronous call (numbered):
โโโ 1. Description โโโโ
โ [Protocol] โ
โโโโ Response โโโโโโโโโ
Asynchronous call (numbered):
โโ โ 2. Description โ โโโ
โ [Protocol] โ
Asynchronous response:
โโโ โ โ Response โ โ โ โโ
Self-call:
โโโโ 3. Validation
โ โ [internal]
โโโโ
Grouping (optional, for loops/conditions):
โโโ[loop: for each item]โโโโโโโโโโโโโโโโโโโโโ
โ โโโ 4. Check item โโโโ โ
โ โโโโ Stock level โโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โโโ[alt: customer exists]โโโโโโโโโโโโโโโโโโโโ
โ โโโ 5a. Load customer data โโโโ โ
โ โโ[else]โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ โโโ 5b. Create customer โโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
System Boundaries in Dynamic Diagrams
โ Portal-System โ Backend-System โ External
โ โ โ
โโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ โ โ โ โ โโ
โ Web- โ โ API-Gateway โ โ Fach- โ โ Postgres โ โ SAP ERP โ
โ Frontend โ โ โ โ service โ โ โ โ โ
โโโโโโฌโโโโโโ โโโโโโโโฌโโโโโโโโ โโโโโโฌโโโโโโ โโโโโโฌโโโโโโ โ โ โโฌโ โ โโ
โ โ โ โ โ
Dynamic Diagram Example: User Sign In Flow
โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
โ <<container>> โ โ [API Application] โ โ <<database>> โ
โ Single-Page โ โ โ โ Database โ
โ App โ โ โโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โ โ [PostgreSQL] โ
โ [Angular] โ โ โ <<component>> โ โ <<component>> โ โ โ User โ
โ Banking UI โ โ โ Sign In โ โ Security โ โ โ credentials โ
โ โ โ โ Controller โ โ Service โ โ โ โ
โโโโโโโโฌโโโโโโโโ โ โ [Spring MVC] โ โ [JWT] โ โ โโโโโโโโฌโโโโโโโโ
โ โ โโโโโโโโฌโโโโโโโโโ โโโโโโโโโโฌโโโโโโโโโ โ โ
โ โโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโ โ
โ โ โ โ
โโโ 1. Submit โโโโโโโโ โ โ
โ credentials โ โ โ
โ [JSON/HTTPS] โ โ โ
โ โโโ 2. Validate โโโโโโ โ
โ โ โ โ
โ โ โโโ 3. Query user โโโโ
โ โ โ [JDBC] โ
โ โ โ โ
โ โ โโโโ User data โโโโโโโ
โ โโโโ Auth result โโโโ โ
โโโโ JWT Token โโโโโโ โ โ
โ [JSON/HTTPS] โ โ โ
Dynamic Diagram Example: Order Processing (Event-Driven)
โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
โ <<container>> โ โ <<container>> โ โ <<container>> โ โ <<container>> โ
โ Order โ โ Inventory โ โ Payment โ โ Shipping โ
โ Service โ โ Service โ โ Service โ โ Service โ
โ [Java] โ โ [Go] โ โ [Node.js] โ โ [Python] โ
โโโโโโโโฌโโโโโโโโ โโโโโโโโฌโโโโโโโโ โโโโโโโโฌโโโโโโโโ โโโโโโโโฌโโโโโโโโ
โ โ โ โ
โโ โ 1. Publish โ โ โ โ โ โ โ โ โ โ โ โ โ โ โ โ โ โ โ โ โโ
โ order.created โ โ
โ [Kafka/Avro] โ โ โ
โ โ โ โ
โ 2. Consume โโ โ โ โ โ โ โโ โ
โ order.created โ โ
โ [Kafka/Avro] โ โ
โ โ โ โ
โ โโ โ 3. Publish โ โ โ โ โ โ โ โ โ โโโ
โ โ inventory.reserved โ
โ โ [Kafka/Avro] โ โ
โ โ โ โ
โ โ 4. Consume โโ โ โ โ โ โ โโ
โ โ inventory.reserved โ
โ โ [Kafka/Avro] โ
โ โ โ โ
โ โ โโ โ 5. Publish โโโ
โ โ โ payment.done โ
โ โ โ [Kafka/Avro] โ
โ โ โ โ
โ โ โ 6. Consume
โ โ โ payment.done
โ โ โ [Kafka/Avro]
Dynamic Diagram Example: OAuth2 Authorization Code Flow
โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โ โ โ โ โ โ โ โโ โโโโโโโโโโโโโโโโ
โ <<container>> โ โ <<container>> โ โ <<external>> โ โ <<database>> โ
โ SPA โ โ API โ โ Auth0 โ โ User DB โ
โ [React] โ โ [Node.js] โ โ [AuthZ Server] โ โ [PostgreSQL] โ
โโโโโโโโฌโโโโโโโโ โโโโโโโโฌโโโโโโโโ โ โ โ โโฌโ โ โ โโ โโโโโโโโฌโโโโโโโโ
โ โ โ โ
โโโ 1. Redirect โ โ โ โ โ โ โ โ โโโ โ
โ to /authorize โ โ
โ โ โ โ
โโโ 2. Redirect โ โ โ โ โ โ โ โ โโ โ
โ with auth code โ โ
โ โ โ โ
โโโ 3. Exchange code โโโโ โ โ
โ for tokens โ โ โ
โ [HTTPS] โ โ โ
โ โโโ 4. POST โ โ โ โ โ โ โ โ โโโ
โ โ /oauth/token โ
โ โ [HTTPS] โ โ
โ โ โ โ
โ โโโ tokens โ โ โ โ โ โ โ โ โ โโ
โ โ โ โ
โโโโ 5. Access + โโโโโโโ โ โ
โ refresh tokens โ โ โ
โ โ โ โ
โโโ 6. API request โโโโโโ โ โ
โ with access token โ โ โ
โ [HTTPS] โ โ โ
โ โโโ 7. Fetch โโโโโโโโโโโโโโโโโโโโ
โ โ user data โ
โ โ [SQL] โ โ
โ โ โ โ
โ โโโโ user data โโโโโโโโโโโโโโโโโโ
โโโโ response โโโโโโโโโโ โ โ
Heuristics (MUST)
General Rules
- Every element must have: Name, Type, Technology (where applicable), and Description
- Use unidirectional arrows - Bidirectional arrows create ambiguity; show call and response separately
- Label arrows with action verbs - "Sends email using", "Reads from", not just "uses"
- Include technology labels - "JSON/HTTPS", "JDBC", "gRPC"
- Stay under 20 elements per diagram - Split complex systems into multiple diagrams
Dynamic Diagram Rules
- Numbering is mandatory: Every interaction step must have a sequential number showing temporal order.
- One use case per diagram: A Dynamic Diagram describes exactly one use case or business process.
- Protocol mandatory: Every call must specify the protocol/technology used.
- Sync/Async marking: Synchronous calls as solid arrows (
โโโ), asynchronous as dashed arrows (โ โ โ).
- Direction mandatory: Every arrow must have a clear direction.
- Responses explicit: If a call has a relevant response (data, confirmation), show it as a return arrow.
- Consistent abstraction level: All elements must be at the same C4 abstraction level.
- Trigger recognizable: The triggering actor/event must be clearly recognizable (leftmost position).
- Layout: Elements from left (trigger) to right (target systems). Frequently interacting elements side by side.
- Compactness: Maximum 7ยฑ2 elements per diagram. With more elements, switch to a higher abstraction level or split the use case.
Clarity Guidelines
- Start at Level 1 - Context diagrams help frame system scope
- One diagram per file - Keep diagrams focused on a single abstraction level
- Meaningful names - Use descriptive names (e.g., "Order Service" not "Svc1")
- Concise descriptions - Keep descriptions under 50 characters when possible
- Always include a title - "System Context diagram for [System Name]"
What to Avoid
See references/common-mistakes.md for detailed anti-patterns:
- Confusing containers (deployable) vs components (non-deployable)
- Modeling shared libraries as containers
- Showing message brokers as single containers instead of individual topics
- Adding undefined abstraction levels like "subcomponents"
- Removing type labels to "simplify" diagrams
Legend
Always add a legend below every diagram:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ LEGEND โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฃ
โ โบ = Actor / Person โ
โ โโโ = Central System (scope) โ
โ โโโ = Internal Element (System/Container/Comp.) โ
โ โ โ = External System โ
โ โโโโ = Synchronous call โ
โ โ โโ = Asynchronous call โ
โ โโโโ = Synchronous response โ
โ โโ โ = Asynchronous response / Callback โ
โ [n] = Step number (temporal order) โ
โ โโโ[x]โโ = Grouping (loop/alt/opt) โ
โ โโโ = Trust Boundary โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Microservices Guidelines
Single Team Ownership
Model each microservice as a container within a single system:
โโโโโโโโโโโโโโโโโโโโ
โ โบ Customer โ
โ [Online shopper]โ
โโโโโโโโโโฌโโโโโโโโโโ
โ
Uses โโโโโ
[HTTPS]
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ [E-commerce Platform] โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโ โ
โ โ <<container>> โ โ
โ โ API Gateway โ โ
โ โ [Kong] โ โ
โ โ Routing, auth, โ โ
โ โ rate limiting โ โ
โ โโโโโโฌโโโโโโโฌโโโโโโโ โ
โ โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ โ โ โ โ
โ โผ โผ โผ โ โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ โ โ
โ โ Order โ โ Product โ โ User โ โ โ โ
โ โ Service โ โ Service โ โ Service โ โ โ โ
โ โ [Node.js]โ โ [Go] โ โ [Java] โ โ โ โ
โ โโโโโโฌโโโโโโ โโโโโโฌโโโโโโ โโโโฌโโโโฌโโโ โ โ โ
โ โ โ โ โ โ โ โ
โ โผ โผ โผ โผ โ โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ โ
โ โ<<database>>โโ<<database>>โโ<<database>>โโ<<database>>โ โ โ
โ โ Order DB โ โ Product โ โ User DB โ โ Cache โ โ โ
โ โ[Postgres]โ โ DB โ โ[Postgres]โ โ [Redis] โ โ โ
โ โโโโโโโโโโโโ โ[MongoDB] โ โโโโโโโโโโโโ โ Sessions โ โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Multi-Team Ownership
Promote microservices to software systems when owned by separate teams:
โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
โ โบ Customer โ โ โบ Admin โ
โ [Online shopper]โ โ [Store manager] โ
โโโโโโโโโโฌโโโโโโโโโโ โโโโโโโโโโฌโโโโโโโโโโ
โ โ
โโโโโ Places orders โโโโโโ โโโโโโโโโโโโโโโโงโโโโโโโโโโโ
โ โ <<system>> โ
โ โ Order System โ
โ โ [Team Alpha] โ
โ โโโโโโโโโคโโโโโโโโโโโโโโโโโโ
โ โ
โ Checks stock โโ Processes payment โโ
โ โ โ
โ โผ โผ
โ โโโโโโโโโโโโโโโโโโโโ โ โ โ โ โ โ โ โ โโ
โ โ <<system>> โ โ <<external>> โ
โ โ Inventory Systemโ โ Stripe โ
โ โ [Team Beta] โ โ [Payment proc.] โ
โ โโโโโโโโโโโโโโโโโโโโ โ โ โ โ โ โ โ โ โโ
โ
โโโโโ Browses products โโโ โโโโโโโโโโโโโโโโโโโโ
โ <<system>> โ
โ Product System โ
โ [Team Beta] โ
โโโโโโโโโโโโโโโโโโโโ
Event-Driven Architecture
Show individual topics/queues as containers, NOT a single "Kafka" box:
โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ
โ <<container>> โ โ <<container>> โ โ <<container>> โ
โ Order โ โ Inventory โ โ Payment โ
โ Service โ โ Service โ โ Service โ
โ [Java] โ โ [Java] โ โ [Java] โ
โโโโฌโโโโโโโโฌโโโโ โโโโฌโโโโโโโโฌโโโโ โโโโฌโโโโโโโโโโโโ
โ โ โ โ โ
โ โ โฒ โ โฒ
โ Publishes โ Publishes โ
โ [Avro] โ [Avro] โ
โ โ Consumes โ Consumes
โ โ [Avro] โ [Avro]
โ โผ โ โผ โ
โ โโโโโโโโโโโโโโโโดโโโ โโดโโโโโโโโโโโโโโโ
โ โ <<queue>> โ โ <<queue>> โ
โ โ order.created โ โ stock.reservedโ
โ โ [Kafka] โ โ [Kafka] โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ
โ
โ Consumes payment.complete [Avro]
โ โ
โ โผ
โ โโโโโโโโโโโโโโโโโโโ
โ โ <<queue>> โ
โ โ payment. โ
โ โ complete โ
โ โ [Kafka] โ
โ โโโโโโโโโโโโโโโโโโโ
โ โฒ
โ โ Publishes [Avro]
โ โ
โโโโโโโโโโโ (from Payment Service)
Cross-References Between Diagram Types
- After Context Diagram: "In the System Context diagram we identified systems X, Y, Z.
Shall I create a Dynamic Diagram showing how these systems interact for a specific use case?"
- Dynamic โ ADR: When complex integration patterns are identified in a Dynamic Diagram
(e.g., Orchestration vs. Choreography), suggest an ADR for the pattern decision.
- Dynamic โ NFR: From the Dynamic Diagram, derive performance requirements
(e.g., "Step 3โ4 must complete in < 100ms").
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 |
| Integration Architects | Context + Container + Dynamic |
| Solution Architects | Context + Container + Dynamic + key Components |
| Developers | All levels as needed |
| DevOps | Container + Deployment |
References
