Skip to content

Commit 8b8aec7

Browse files
author
CHANGE_ME
committed
docs: add C4 abstraction and diagram concept pages
Made-with: Cursor
1 parent cd02bdf commit 8b8aec7

14 files changed

Lines changed: 300 additions & 0 deletions

‎pages/C4.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
alias:: [[C4 Model]]
4+
created-by:: [[Person/Simon Brown]]
5+
see-also:: [[Structurizr]], [[diagrams]], [[D2]], [[Diagram/Mermaid]]
6+
7+
- # **[C4 model](https://c4model.com/)**
8+
- ## Official High Level Overview
9+
- The C4 model is an easy to learn, developer friendly approach to software architecture diagramming:
10+
- Hierarchical abstractions
11+
- [[C4/Abstraction]]
12+
- [[C4/Abstraction/1 - Software System]]
13+
- [[C4/Abstraction/2 - Container]]
14+
- [[C4/Abstraction/3 - Component]]
15+
- [[C4/Abstraction/4 - Code]]
16+
- Hierarchical diagrams (core)
17+
- [[C4/Diagram]]
18+
- [[C4/Diagram/1 - System context]]
19+
- [[C4/Diagram/2 - Containers]]
20+
- [[C4/Diagram/3 - Components]]
21+
- [[C4/Diagram/4 - Code]]
22+
- Supporting diagrams
23+
- [[C4/Diagram/System landscape]]
24+
- [[C4/Diagram/Dynamic]]
25+
- [[C4/Diagram/Deployment]]
26+
- [Notation independent](https://c4model.com/diagrams/notation).
27+
- [Tooling independent](https://c4model.com/tooling).
28+
- ## Context
29+
- Fits **team communication**, **onboarding**, **alignment with non-developers**, and **architecture-as-code** workflows (e.g. **[[Structurizr]]** DSL) where the same model drives **multiple consistent views**.
30+
- Sits alongside other diagram idioms: **[[Diagram/Mermaid]]**, **[[D2]]**, **[[diagrams]]** (Python), **PlantUML**, etc.—C4 answers **what to show at which scope**, not which renderer to use.
31+
- Complements **ADRs**, **threat modeling**, and **API catalogs**: C4 is primarily **structural** and **decomposition-oriented**, not a full security or runtime-behavior notation by itself.
32+
- ## Key principles
33+
- **1. Context** — The system as a **box** among **users** and **external systems**; answers *what does this software do for whom* and *what does it talk to*.
34+
- **2. Containers** — **Deployable/runnable things** (apps, databases, file stores, browsers, server processes) and **how they communicate**; answers *what are the major pieces that ship or run*.
35+
- **3. Components** — **Logical building blocks inside a single container** (services, modules, facades) and their relationships; answers *how is this container structured internally*.
36+
- **4. Code** — **Classes, interfaces, files, or modules** (UML-style detail is optional here); answers *how is a component implemented*—often **skipped** or **generated** when auto-layout or IDE views suffice.
37+
- **Notation discipline** — Prefer **simple shapes** (person, software system, container, component), **clear relationships** (sync/async, protocols where useful), and **explicit scope** so diagrams stay readable.
38+
- ## Mechanism
39+
- **Zooming in** adds detail **inside** a boundary drawn at the previous level: a **system** in context becomes a **container diagram**; a **container** becomes a **component diagram**.
40+
- **Supplementary views** (deployment, dynamic sequences) are **add-ons** when needed; the **core** model stays **structural** and **static** at each level.
41+
- **Tooling** can **validate** that elements exist at the right level and that **relationships** are consistent across views—this is where **architecture-as-code** shines.
42+
- ## Examples
43+
- **[[Structurizr]]** — DSL and exports aligned with C4 views (context, container, component, deployment, etc.).
44+
- **Diagrams-as-code** in [[Mermaid]] or [[PlantUML]] often **imitate** C4 levels even when not using a C4-specific toolchain—same **separation of concerns**, lighter enforcement.
45+
- ## Misconceptions
46+
- “C4 **is** four mandatory diagrams for every system” — **Overstated**; the levels are **lenses**. Teams routinely **omit** code-level C4 or **collapse** steps when the audience does not need them.
47+
- “C4 replaces **UML**” — **Misleading**; C4 **overlaps** some deployment/component ideas but aims at **communication defaults**, not full **behavioral** or **formal** modeling.
48+
- “If it’s not C4, it’s wrong” — **False**; many good architecture descriptions use **other** abstractions (DDD bounded contexts, data flows, threat surfaces). C4 is one **structured** option.

‎pages/C4___Abstraction.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
see-also:: [[C4]], [[C4/Diagram]]
4+
5+
- # **[Abstractions | C4 model](https://c4model.com/abstractions)**
6+
- ## Overview
7+
- The C4 model describes static structure using a small hierarchy: a **software system** contains **containers** (runnable apps and data stores), which contain **components**, which are implemented by **code** elements.
8+
- ## Numbered abstraction entities in this graph
9+
- [[C4/Abstraction/1 - Software System]]
10+
- [[C4/Abstraction/2 - Container]]
11+
- [[C4/Abstraction/3 - Component]]
12+
- [[C4/Abstraction/4 - Code]]

‎pages/C4___Abstraction___1 - Software System.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
see-also:: [[C4/Diagram/1 - System context]], [[C4/Abstraction/2 - Container]]
4+
5+
- # **[Software system](https://c4model.com/abstractions/software-system)** (C4 abstraction)
6+
- ## Overview
7+
- The **highest** C4 abstraction: something that **delivers value** to its users (human or not), including the system you are modelling and **other** systems it depends on (or that depend on it).
8+
- Often aligned with what a **single team** builds, owns, and can change—sometimes approximated by one repo or a **single deploy boundary**, though organisations use different words (“application”, “product”, “service”, …).
9+
- ## Context
10+
- Sits at the top of the decomposition chain under [[C4]]; **not** the same as DDD **bounded contexts**, org **tribes**, or **feature teams**—those may slice reality differently.
11+
- The usual **zoom-in** target is **containers** inside this boundary ([[C4/Abstraction/2 - Container]]).
12+
- ## Key principles
13+
- **Value-oriented** — If it doesn’t plausibly “ship” as a coherent thing users or other systems rely on, it may not be a software system in C4 terms.
14+
- **Boundary discipline** — External collaborators appear as **other software systems** or **people** at the **context** view, not as vague blobs.
15+
- ## Mechanism
16+
- In diagrams, a software system is typically a **single major box** at [[C4/Diagram/1 - System context]]; opening it yields the [[C4/Diagram/2 - Containers]] view.
17+
- ## Examples
18+
- An internal **HR portal**, a **customer API platform**, or a **billing service** each might be one software system if teams and ownership match the C4 boundary.
19+
- ## Misconceptions
20+
- “**Every** bounded context is a software system” — **Often wrong**; contexts are a modelling tool, not identical to C4’s deploy/ownership box.
21+
- “**Microservice = software system**” — **Sometimes**; many systems contain **multiple** deployables—those are usually **containers**, not separate software systems, unless ownership and boundary truly differ.

‎pages/C4___Abstraction___2 - Container.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
see-also:: [[C4/Diagram/2 - Containers]], [[C4/Abstraction/1 - Software System]], [[C4/Abstraction/3 - Component]]
4+
5+
- # **[Container](https://c4model.com/abstractions/container)** (C4 abstraction)
6+
- ## Overview
7+
- A **container** is an **application** or **data store**—something that must **run** (or be hosted) to exist: web apps, APIs, mobile apps, databases, file stores, browser clients, server processes, etc.
8+
- Containers are the **deployable / runnable** pieces that together implement a [[C4/Abstraction/1 - Software System]].
9+
- ## Context
10+
- The second zoom level of [[C4]]: answers *what major things **ship** or **run*** and *how they **communicate*** (protocols, sync/async).
11+
- **Inside** a container, structure is expressed with [[C4/Abstraction/3 - Component]] elements.
12+
- ## Key principles
13+
- **Independently runnable** — If it doesn’t start, listen, store, or render as a unit, it is probably not a container.
14+
- **Technology explicit enough to be useful** — e.g. “PostgreSQL”, “Spring Boot monolith”, “React SPA”—not a vague “layer”.
15+
- ## Mechanism
16+
- Rendered as the primary boxes on a [[C4/Diagram/2 - Containers]]; each container hosts one or more [[C4/Abstraction/3 - Component]] groupings in the next zoom level.
17+
- ## Examples
18+
- A **single-page web app**, a **GraphQL API service**, a **message consumer**, a **relational database**, an **object store**.
19+
- ## Misconceptions
20+
- “**Docker image = container** (C4 sense)” — **Confusing word collision**; a C4 container is an **architectural** runtime unit, not necessarily one Docker container.
21+
- “**Every JAR / npm package is a container**” — **Usually false**; packaging and modules often map to [[C4/Abstraction/3 - Component]] or [[C4/Abstraction/4 - Code]] instead.

‎pages/C4___Abstraction___3 - Component.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
see-also:: [[C4/Diagram/3 - Components]], [[C4/Abstraction/2 - Container]], [[C4/Abstraction/4 - Code]]
4+
5+
- # **[Component](https://c4model.com/abstractions/component)** (C4 abstraction)
6+
- ## Overview
7+
- In C4, a **component** is a **grouping of related functionality** behind a **well-defined interface**—deliberately **not** “whatever your framework calls a component”.
8+
- Components are **not** separately deployable; the **container** is the deployable unit, and components share its **process space** (for typical interpretations).
9+
- ## Context
10+
- Third zoom level of [[C4]]: answers *how is **this container** structured internally*—services, modules, facades, bounded technical roles.
11+
- Stands **one level above** language-level [[C4/Abstraction/4 - Code]] (classes, modules, files).
12+
- ## Key principles
13+
- **Interface-backed** — Think in terms of responsibilities and contracts, not folder trees alone.
14+
- **Runtime partition** — Packaging (JARs, DLLs, folders) may or may not align; C4 cares about **logical structure inside a running container**.
15+
- ## Mechanism
16+
- Shown on [[C4/Diagram/3 - Components]]; often **reverse-engineered** from code for large systems (e.g. via [[Structurizr]] or similar tooling).
17+
- ## Examples
18+
- A **set of MVC controllers** plus a **service layer** and **repositories** might be refactored into named components (not every class is one).
19+
- ## Misconceptions
20+
- “**Every package / namespace / folder is a component**” — **Often false**; those are **organisational** units—components are **architectural** groupings.
21+
- “**Microservice = component**” — **Usually wrong**; a microservice is typically a **container** or even its **own software system**, depending on ownership and boundary.

‎pages/C4___Abstraction___4 - Code.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
see-also:: [[C4/Diagram/4 - Code]], [[C4/Abstraction/3 - Component]]
4+
5+
- # **[Code](https://c4model.com/abstractions/code)** (C4 abstraction)
6+
- ## Overview
7+
- **Code** elements are the programming-language building blocks that implement a [[C4/Abstraction/3 - Component]]: **classes**, **interfaces**, **enums**, **functions**, **objects**, and similar constructs.
8+
- The **finest** C4 static zoom; many teams **skip** drawing it and rely on the IDE or generated UML instead.
9+
- ## Context
10+
- Fourth level of [[C4]]: answers *how is this **component** actually built*—often **too detailed** for stakeholder decks but useful for developers onboarding to a module.
11+
- ## Key principles
12+
- **Honest detail** — Show the **architecturally relevant** types and relationships, not every POJO or util class.
13+
- **Optional by value** — If the diagram adds no new insight, omit it.
14+
- ## Mechanism
15+
- Expressed in [[C4/Diagram/4 - Code]] views; frequently **auto-generated** from source when used at all.
16+
- ## Examples
17+
- A UML-style **class diagram** for a service’s core types; a **module dependency** sketch in lieu of full UML.
18+
- ## Misconceptions
19+
- “C4 **requires** code diagrams” — **False**; context + container often suffice per [[C4/Diagram]].
20+
- “**Code diagram = full class diagram of everything**” — **Usually noise**; C4 expects **selective** structure, not inventory.

‎pages/C4___Diagram.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
see-also:: [[C4]], [[C4/Abstraction]]
4+
5+
- # **[Diagrams | C4 model](https://c4model.com/diagrams)**
6+
- ## Overview
7+
- **Core** static-structure views (the namesake “four Cs”): zoom from **system context** through **containers**, **components**, and optionally **code**.
8+
- **Supporting** views: **system landscape**, **dynamic**, and **deployment**—used when those stories matter.
9+
- ## Core diagram entities (numbered)
10+
- [[C4/Diagram/1 - System context]]
11+
- [[C4/Diagram/2 - Containers]]
12+
- [[C4/Diagram/3 - Components]]
13+
- [[C4/Diagram/4 - Code]]
14+
- ## Supporting diagram entities
15+
- [[C4/Diagram/System landscape]]
16+
- [[C4/Diagram/Dynamic]]
17+
- [[C4/Diagram/Deployment]]

‎pages/C4___Diagram___1 - System context.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
see-also:: [[C4/Abstraction/1 - Software System]], [[C4/Diagram/2 - Containers]]
4+
5+
- # **[System context diagram](https://c4model.com/diagrams/system-context)** (C4 diagram)
6+
- ## Overview
7+
- **Level 1** static-structure view: the **software system under design** as one box among **people** (actors) and **other software systems** it interacts with.
8+
- Deliberately **low detail**—answers *what does this system **do** for **whom*** and *what are its **external collaborators***.
9+
- ## Context
10+
- First of the four core diagrams indexed on [[C4/Diagram]]; together with [[C4/Diagram/2 - Containers]] it is **sufficient for most teams** per the C4 site.
11+
- Corresponds to modelling the [[C4/Abstraction/1 - Software System]] boundary in its environment—not what runs inside it.
12+
- ## Key principles
13+
- **Scope clarity** — “Inside” vs “outside” the system must be obvious.
14+
- **Audience fit** — Built for **non-developers** and **leadership** as much as engineers.
15+
- ## Mechanism
16+
- **Zoom in** from here to [[C4/Diagram/2 - Containers]] to open the system and show **containers**.
17+
- ## Examples
18+
- A payments platform shown with **customers**, **merchants**, **card networks**, and **internal admin users**.
19+
- ## Misconceptions
20+
- “**Context = deployment**” — **Wrong**; deployment concerns belong in [[C4/Diagram/Deployment]] (supporting view).
21+
- “**Must list every integration**” — **Pragmatically false**; show **material** external dependencies only.

‎pages/C4___Diagram___2 - Containers.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
see-also:: [[C4/Abstraction/2 - Container]], [[C4/Diagram/1 - System context]], [[C4/Diagram/3 - Components]]
4+
5+
- # **[Container diagram](https://c4model.com/diagrams/container)** (C4 diagram)
6+
- ## Overview
7+
- **Level 2** static-structure view: **inside** one [[C4/Abstraction/1 - Software System]], showing the **containers** at the [[C4/Abstraction/2 - Container]] level—web apps, APIs, workers, databases, file stores, etc.—and **how they communicate**.
8+
- Answers *what **ships** or **runs*** and *which **protocols** connect the pieces*.
9+
- ## Context
10+
- Central “**as-built runtime**” picture for many teams; bridges executives’ [[C4/Diagram/1 - System context]] with developers’ [[C4/Diagram/3 - Components]].
11+
- ## Key principles
12+
- **Technology honesty** — Name stacks where it aids comprehension (“PostgreSQL”, “Kotlin service”, …).
13+
- **Communication edges** — Prefer labelled relationships over a spaghetti of anonymous lines.
14+
- ## Mechanism
15+
- **Zoom in** on a single container to produce [[C4/Diagram/3 - Components]] for that boundary.
16+
- ## Examples
17+
- **Browser SPA** → **BFF API** → **domain services** → **OLTP database** + **object store** for attachments.
18+
- ## Misconceptions
19+
- “**One box per repo**” — **Heuristic at best**; some repos host **multiple** containers, or **one** container spans repos—model **runtimes**, not git topology.
20+
- “**Same as deployment diagram**” — **Different question**; [[C4/Diagram/Deployment]] maps software to **infrastructure**, not only logical containers.

‎pages/C4___Diagram___3 - Components.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
logseq-entity:: [[Logseq/Entity/concept]]
2+
tags:: [[Diataxis/Concept]]
3+
see-also:: [[C4/Abstraction/3 - Component]], [[C4/Diagram/2 - Containers]], [[C4/Diagram/4 - Code]]
4+
5+
- # **[Component diagram](https://c4model.com/diagrams/component)** (C4 diagram)
6+
- ## Overview
7+
- **Level 3** static-structure view: **inside** a single [[C4/Abstraction/2 - Container]], showing major **components** at the [[C4/Abstraction/3 - Component]] level—groupings of related behaviour behind interfaces—and their dependencies.
8+
- Answers *how is **this deployable** structured **logically*** without naming every class.
9+
- ## Context
10+
- Most useful when the container is **large enough** that a flat list of technologies (from the container diagram) no longer explains **seams** and **ownership** inside the process.
11+
- ## Key principles
12+
- **Cohesion** — Each component should represent a **story** you can explain in one breath.
13+
- **Acyclic clarity** — Highlight **allowed** dependencies; call out **forbidden** ones if the diagram is a governance artefact.
14+
- ## Mechanism
15+
- Optional **deeper** step: [[C4/Diagram/4 - Code]] for implementation detail—often skipped or generated.
16+
- ## Examples
17+
- Inside a monolithic web container: **controllers**, **application services**, **domain core**, **integration adapters**, **repositories**.
18+
- ## Misconceptions
19+
- “**Must mirror the folder tree**” — **No**; components are **architectural** slices, not directory listings.
20+
- “**Every class is a component**” — **Opposite of C4 intent**; components **aggregate** [[C4/Abstraction/4 - Code]].

0 commit comments

Comments
 (0)