c4 Diagrams.instructions

<!-- Archetype: RULES -->

# C4 Diagrams

## Scope

Apply this file when generating `c4.md` as part of the spec writer flow. This file defines which Mermaid diagram type to use at each C4 level, what each level must and must not show, and required structural elements.

**This file answers:** how to produce a syntactically correct and architecturally meaningful C4 diagram in Mermaid.

---

## Level Selection

C4 has four levels. Use the correct level for the context. Do not mix levels in one diagram.

| Level | Name | Mermaid Type | Shows |
|---|---|---|---|
| C1 | Context | `C4Context` | The system and its external actors/systems |
| C2 | Container | `C4Container` | Independently deployable units inside the system |
| C3 | Component | `C4Component` | Modules or components inside one container |
| C4 | Code | — | Classes, interfaces, methods — do not generate |

**C2 is the minimum level for every `c4.md`.** Always generate a C2 diagram when an architectural concern is confirmed.

**Generate C3 only when** the change reorganizes the internal module structure of a specific container (new module, changed public contracts between modules).

**Generate C1 only when** external actor relationships or external system integrations change.

**Never generate code-level (C4) diagrams.** Aggregates, classes, use cases, and repository interfaces belong in `implementation-plan.md` if needed, not in architectural diagrams.

---

## Code to C4 Mapping

Use this table before drawing any diagram. Misclassifying a code artifact as the wrong C4 level is the most common source of incorrect diagrams.

### C2 — what maps here

A C2 container is **any independently deployable unit** — a process boundary.

| Code artifact | C2 element? | Notes |
|:---|:---|:---|
| Entire modular monolith | Yes — ONE container | All modules live inside it; modules do not get separate C2 boxes |
| Microservice / separate process | Yes — one container per service | Each independently deployable process is one C2 container |
| Database / data store | Yes — `ContainerDb` | One per system boundary that owns it |
| Message broker (Kafka, RabbitMQ) | Yes — `Container` | When it is a first-class deployable infrastructure component |
| Solution file (`.sln`) | No | Organizational, not deployable |
| Library project inside a monolith | No | Part of the container, not its own container |
| Executable project in a microservice | Yes | It IS the deployable unit |
| Bounded context as a module in a monolith | No — belongs at C3 | The whole monolith is the container; the BC is a component inside it |
| Bounded context extracted to its own service | Yes | It has become its own deployable process |

### C3 — what maps here

A C3 component is **any logical module or bounded context inside a container** — a named, cohesive group of behavior with a public contract.

| Code artifact | C3 element? | Notes |
|:---|:---|:---|
| DDD module (e.g., `Modules/Reservations/`) | Yes | One component per module |
| Bounded context inside a monolith | Yes | The BC is the component |
| Application layer (all handlers) | No | Too fine-grained; belongs inside the component box |
| Project file inside a monolith | No | It may map to a module, but the project file is not the component |
| Aggregate | No — never shown | C4 level; never generated |
| Domain service | No — never shown | C4 level |
| Application service / command handler | No — never shown | C4 level |
| Repository interface | No — never shown | C4 level |
| Domain event | No — never shown | Events are relationships between aggregates, not boxes |

### Never generate (C4 code level)

These concepts exist in the codebase but must never appear in generated diagrams. If needed for documentation, they belong in `implementation-plan.md`.

Aggregates, entities, value objects, domain services, application services, command/query handlers, repository interfaces and implementations, domain events, integration events, infrastructure adapters, DTOs.

### DDD to C4 summary

| DDD concept | C4 level |
|:---|:---|
| System / product | C1 `System` |
| External system / third-party API | C1 `System_Ext` |
| Actor / user role | `Person` (any level) |
| Microservice | C2 `Container` |
| Modular monolith (entire) | C2 `Container` — one box |
| Bounded context (in monolith) | C3 `Component` |
| Module (in monolith) | C3 `Component` |
| Aggregate | Never shown |
| Domain service | Never shown |
| Application service | Never shown |
| Repository | Never shown |
| Domain event | Never shown |

---

## Delta scope

When generating `c4.md` for a feature that extends an existing system with a prior `c4.md` artifact:

- Show only components and relationships that are new or changed in this feature
- Mark changed components with `[NEW]` or `[EXTENDED]` in the label
- Reference the prior artifact for unchanged components: *"Unchanged modules — see prior `c4.md`"*

Simplify by reducing content, not by changing the diagram type. A C4 diagram with fewer boxes is still a C4 diagram; a `flowchart LR` is not.

---

## What Each Level Must and Must Not Show

### C2 — Container Diagram

**Must show:**
- Every independently deployable unit: API servers, databases, message queues, background services, mobile apps, external SaaS
- Relationships between containers — arrows with label and protocol
- At least one `Person` element representing the external actor(s)
- `System_Boundary` wrapping the system's own containers

**Must NOT show:**
- Internal modules, components, or bounded contexts — those belong at C3
- Aggregates, domain services, use cases, or repositories
- Method signatures or interface definitions

**For a modular monolith:** the entire application is **one container** at C2. The internal module structure is not visible at this level.

Correct C2 for a modular monolith: