C4 Architecture Document Template (C4 Model)

C4 model document with Mermaid C4 diagrams – context, containers, components, code, landscape, dynamic, deployment, element catalogues

Архітектура та системний дизайнПовнийC4 modeldiagramОновлено 20 жовт. 2026 р.

Відкрити в редакторіЗавантажити .md

Як використовувати: Teams that want diagrams developers actually maintain. Draw context and container levels first; add component diagrams only for one or two complex containers. The main pitfall is boxes without descriptions and lines labelled only "uses".

Перегляд

C4 Architecture Document: [System name]

Architecture document organised around the C4 model by Simon Brown (c4model.com): system context, containers, components and code, plus supplementary landscape, dynamic and deployment diagrams. Diagrams use Mermaid C4 syntax so they live next to the text. Replace every [bracketed] value and every row marked Example.

Document control

Field	Value
Document ID	[C4-SYSTEM-001]
Software system	[System name]
System release described	[vX.Y / current state as of YYYY-MM-DD]
Version	[0.1]
Status	[Draft / In review / Approved]
Author / owner	[@architect]
Classification	[Internal / Confidential / Public]
Last updated	YYYY-MM-DD

Approvals

Role	Name	Decision	Date
Lead architect	[@name]	[Approved / Approved with comments / Rejected]	YYYY-MM-DD
Engineering lead	[@name]	[Decision]	YYYY-MM-DD
Security architect	[@name]	[Decision]	YYYY-MM-DD
Operations lead	[@name]	[Decision]	YYYY-MM-DD

Revision history

Version	Date	Author	Change summary
0.1	YYYY-MM-DD	[@name]	Context and container diagrams
0.2	YYYY-MM-DD	[@name]	Example: Component diagram for the API application; deployment diagram
1.0	YYYY-MM-DD	[@name]	Example: Baseline approved at architecture review

Introduction
Notation and conventions
Level 1: System context
Level 2: Containers
Level 3: Components
Level 4: Code
Supplementary diagrams
Architecture decisions and quality attributes
Risks, open questions and glossary

1. Introduction

1.1 Purpose and audience

This document describes the software architecture of [System name] for [developers joining the team, architects reviewing changes, operations and security reviewers]. It uses the C4 model's hierarchy of abstractions, so each audience can stop at the level of detail they need.

1.2 System summary

[Two or three sentences: what the system does, for whom, and its business value. Example: "The online shop lets retail customers browse the catalogue, place orders and track deliveries. It handles around 8,000 orders per day and integrates with the warehouse and payment provider."]

1.3 Diagram inventory

Diagram	Level / type	Audience	Section
System context	Level 1	Everyone	3
Containers	Level 2	Technical staff	4
Components of [API application]	Level 3	Developers	5.1
Components of [Worker]	Level 3	Developers	5.2
System landscape	Supplementary	Architects, management	7.1
Dynamic: [Place order]	Supplementary	Developers, testers	7.2
Deployment: Production	Supplementary	Operations	7.3

2. Notation and conventions

Element	Meaning	Description required
Person	A human user or role	Role and goal
Software system	Something that delivers value to users; owned by one team	Purpose
External system	A software system outside the scope of this document	Purpose and owner
Container	A separately runnable or deployable unit (application, data store)	Technology and responsibility
Component	A grouping of related functionality behind an interface inside a container	Technology and responsibility
Relationship	Uni-directional dependency or data flow	Verb phrase and, at level 2 and below, protocol

Conventions used here: [relationship labels describe intent ("Places orders using"), not just "uses"; technology appears in square brackets; external systems are shown grey in the rendered diagrams].

2.1 Diagram review checklist

Run this checklist on every diagram before a review. A "no" is a defect to fix, not a style preference.

Check	Question
Title	Does the diagram have a title that names its type and scope?
Key	Is the meaning of every shape, colour, line style and acronym clear from the key or the conventions above?
Elements	Does every element have a name, a type and a one-sentence description?
Technology	At level 2 and below, does every container and component state its technology?
Relationships	Does every line have a direction and a label that says what happens, not only "uses"?
Protocols	At level 2 and below, does every relationship crossing a process boundary name its protocol?
Consistency	Do names match exactly across levels, so a container in section 4 is the boundary in section 5?
Size	Is the diagram small enough to read without zooming (about 15 elements or fewer)?

2.2 Keeping diagrams current

Practice	How it is applied here
Diagrams as code	Diagrams are Mermaid text in this document, reviewed in the same pull request as the change they describe
Owner per diagram	[The team owning the container owns its component diagram]
Review trigger	[Any new container, new external system, or changed protocol updates sections 3 and 4]
Model tooling	[Optional: a modelling tool generates views from one model; this document links to them]

3. Level 1: System context

3.1 Diagram

The system context diagram shows [System name] with its users and the external systems it relies on.

3.2 Element catalogue

Element	Type	Description	Owner
Example: Customer	Person	Retail customer on web or mobile browser	n/a
Example: Online shop	Software system (in scope)	Catalogue, basket, checkout, order tracking	Team Shop
Example: Payment provider	External system	Card authorisation and capture	[Vendor]
Example: Warehouse system	External system	Fulfilment and shipment status	Logistics IT
[Element]	[Type]	[Description]	[Owner]

4. Level 2: Containers

4.1 Diagram

The container diagram shows the deployable units inside the online shop.

4.2 Element catalogue

Container	Technology	Responsibility	Data owned	Team
Example: Web application	TypeScript, React	Customer UI, served as static files	None (browser storage for basket)	Team Shop
Example: API application	Java 21, Spring Boot	Orders, catalogue, payments orchestration	Shop database	Team Shop
Example: Fulfilment worker	Java 21	Hand-off to warehouse with retries	None	Team Logistics
Example: Shop database	PostgreSQL 16	System of record	Products, customers, orders	Team Shop
[Container]	[Technology]	[Responsibility]	[Data]	[Team]

4.3 Inter-container communication

From	To	Protocol	Sync / async	Authentication	Notes
Example: Web application	API application	HTTPS, JSON	Sync	OAuth 2.0 bearer token	Rate limited per user
Example: API application	Message broker	AMQP over TLS	Async	Service credentials	At-least-once delivery
[From]	[To]	[Protocol]	[Mode]	[AuthN]	[Notes]

4.4 Data ownership and security boundaries

Each data store has exactly one owning container. Other containers read its data only through the owner's API or events.

Data store	Owning container	Readers (via)	Personal data	Encryption at rest	Backup
Example: Shop database	API application	Fulfilment worker (order paid events)	Yes: names, addresses, email	Yes, provider-managed keys	Daily snapshot, 35 days
Example: Message broker	API application (publisher)	Fulfilment worker	Order ID and address	TLS in transit, disk encryption	Not backed up; replayable from outbox
[Store]	[Owner]	[Readers]	[Yes / No: fields]	[Yes / No]	[Policy]

5. Level 3: Components

5.1 Components of the API application

The API application is decomposed into components that each own one area of the business logic.

Component	Responsibility	Interface	Technology
Example: Order controller	Request validation, mapping to commands	`POST /orders`, `GET /orders/{id}`	Spring MVC
Example: Order service	Pricing, stock check, state transitions	`placeOrder(command)`	Plain Java
Example: Payment gateway	Idempotent payment calls, error mapping	`authorise(orderId, amount)`	HTTP client with retry
[Component]	[Responsibility]	[Interface]	[Technology]

5.2 Components of [second container]

[Repeat the diagram and table for a second container only if readers need it, for example the fulfilment worker's retry and dead-letter handling.]

Component	Responsibility	Interface	Technology
Example: Order event listener	Consumes order paid events	AMQP queue `orders.paid`	Spring AMQP
Example: Shipment client	Creates shipments, handles 429 and 5xx with backoff	`createShipment(order)`	HTTP client
[Component]	[Responsibility]	[Interface]	[Technology]

6. Level 4: Code

Code diagrams for [System name] are generated from the source on demand rather than maintained by hand. This section records the conventions that map components to code.

Component	Package / module	Key types	Notes
Example: Order service	`com.example.shop.orders`	`Order`, `OrderService`, `PricingPolicy`	Domain types have no framework annotations
Example: Payment gateway	`com.example.shop.payments`	`PaymentGateway`, `ProviderClient`	Only package allowed to call the provider SDK
[Component]	[Package]	[Types]	[Notes]

Rules enforced in the build: [for example "architecture tests fail the build when a controller calls a repository directly"].

7. Supplementary diagrams

7.1 System landscape

The landscape shows the online shop among the other systems of [Company].

System	Owner	Relevance to this document
Example: Product information system	Merchandising IT	Source of catalogue data
[System]	[Owner]	[Relevance]

7.2 Dynamic diagram: place order

The dynamic diagram shows the runtime order of interactions when a customer places an order.

Step	From	To	Description	Failure handling
1	Customer	Web application	Submits the basket	Client-side validation
2	Web application	API application	Creates the order with an idempotency key	Retry safe on timeout
3	API application	Payment provider	Authorises the amount	Declined returns 402, order stays unpaid
4	API application	Shop database	Stores order and outbox event in one transaction	Rollback, payment voided

7.3 Deployment diagram: production

The deployment diagram maps containers to production infrastructure.

Deployment node	Infrastructure	Instances	Scaling	Recovery
Example: Kubernetes cluster	Managed Kubernetes, 3 zones	3 API, 2 worker pods	HPA on CPU 70%	Pods rescheduled automatically
Example: Managed database	PostgreSQL 16	Primary and 1 replica	Vertical	Automatic failover, RPO 5 min
[Node]	[Infrastructure]	[Instances]	[Scaling]	[Recovery]

8. Architecture decisions and quality attributes

8.1 Key decisions

ID	Decision	Diagram affected	Status	Record
ADR-001	Example: Single-page application served from a CDN	Containers, deployment	Accepted	[link]
ADR-002	Example: Asynchronous hand-off to the warehouse via a broker	Containers, dynamic	Accepted	[link]
[ADR-nnn]	[Decision]	[Diagram]	[Status]	[link]

8.2 Quality attributes

Attribute	Target	Achieved by	Container
Example: Availability	99.9% monthly for checkout	3 API replicas across zones, managed database failover	API, database
Example: Performance	p95 checkout under 800 ms	Payment call is the only synchronous external call	API
[Attribute]	[Target]	[Mechanism]	[Container]

9. Risks, open questions and glossary

9.1 Risks and open questions

ID	Item	Type	Affected element	Owner	Due
RK-01	Example: Broker is a single cluster without cross-region replication	Risk	Message broker	@name	YYYY-MM-DD
OQ-01	Example: Should the worker call the warehouse in batches?	Question	Fulfilment worker	@name	YYYY-MM-DD
[ID]	[Item]	[Risk / Question]	[Element]	[@name]	YYYY-MM-DD

9.2 Glossary

Term	Meaning
Software system	Highest level of abstraction; delivers value and is owned by one team
Container	A runnable or deployable unit such as an application or a data store (not only a Docker container)
Component	A group of related functionality behind an interface inside one container
[Term]	[Meaning]

Standard and licence note

Based on the C4 model for visualising software architecture by Simon Brown (https://c4model.com): system context, container, component and code levels, plus system landscape, dynamic and deployment diagrams. This template is original text written for this collection and reproduces no text from the C4 website. Template licence: MIT.

Схожі шаблони

Архітектура та системний дизайн