C4 Diagrams¶
The C4 model is a framework for visualising software architecture at four levels of detail. Each level zooms into the previous one, progressively revealing more implementation detail. The name comes from the four diagram types: Context, Containers, Components, and Code.
The four levels¶
| Level | Name | Audience | Answers |
|---|---|---|---|
| L1 | System Context | Everyone | What is the system, who uses it, and what does it depend on? |
| L2 | Containers | Engineers, architects | What deployable units make up the system and how do they communicate? |
| L3 | Components | Engineers | What are the significant internal parts of each container? |
| L4 | Code | Engineers | How is a specific component implemented? |
How we use C4 diagrams¶
We maintain diagrams at L1, L2, and L3. These levels give a consistent picture of PetFolio's architecture without becoming a maintenance burden.
| Level | Page | Status |
|---|---|---|
| L1 – System Context | System Context | Maintained |
| L2 – Containers | Containers | Maintained |
| L3 – Components | Components | Maintained |
| L4 – Code | - | Not maintained (see below) |
Why we do not maintain L4 diagrams¶
L4 diagrams are UML-style class or sequence diagrams that map directly to code. In practice they go stale quickly as implementation details change, and maintaining them alongside the codebase adds overhead without proportional benefit.
Instead, we cover L4 concerns through:
- Architecture layer docs: the Backend architecture layers pages explain how each layer is structured and what its responsibilities are
- The codebase itself: the clean architecture and CQRS patterns in
petfolio-servicemake the code structure self-documenting - ADRs: significant design decisions are recorded in Architecture Decision Records
If a specific component warrants a sequence or interaction diagram, add it to the relevant component or architecture page rather than maintaining a separate L4 section.