# 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*.

<!--
Guidance: How to use this template
- Draw level 1 (context) and level 2 (containers) for every system. Draw
  level 3 (components) only for the one or two containers where the team
  needs it; most systems never need level 4 diagrams.
- Every diagram has a title, a key and an element catalogue table. A box
  without a description and a line without a label are the two most common
  C4 mistakes.
- Keep diagrams to about 10 to 15 elements. Split rather than shrink.
- Mermaid C4 support is still evolving; if a diagram does not render, check
  quoting and keep to the element types shown here.
-->

## Document control

<!-- Guidance: Identify the document and the system release the diagrams describe. Diagrams drift; version them. -->

| 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

<!-- Guidance: Name the diagrams that changed in each entry. -->

| 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 |

## Contents

1. [Introduction](#1-introduction)
2. [Notation and conventions](#2-notation-and-conventions)
3. [Level 1: System context](#3-level-1-system-context)
4. [Level 2: Containers](#4-level-2-containers)
5. [Level 3: Components](#5-level-3-components)
6. [Level 4: Code](#6-level-4-code)
7. [Supplementary diagrams](#7-supplementary-diagrams)
8. [Architecture decisions and quality attributes](#8-architecture-decisions-and-quality-attributes)
9. [Risks, open questions and glossary](#9-risks-open-questions-and-glossary)

## 1. Introduction

<!-- Guidance: Say what the system does, who the document is for, and which diagrams it contains. -->

### 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

<!-- Guidance: C4 is notation-independent, so state yours. Readers should never have to guess what a shape, colour or line means. -->

| 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

<!-- Guidance: The big picture: the system as one box, the people who use it and the systems it depends on. No technology, no protocols beyond what non-technical readers understand. -->

### 3.1 Diagram

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

```mermaid
C4Context
  title System context for the online shop
  Person(customer, "Customer", "Buys products online")
  Person(staff, "Support agent", "Handles customer queries")
  System(shop, "Online shop", "Lets customers browse, order and track deliveries")
  System_Ext(pay, "Payment provider", "Authorises and captures card payments")
  System_Ext(wms, "Warehouse system", "Picks, packs and ships orders")
  System_Ext(mail, "Email service", "Delivers transactional email")
  Rel(customer, shop, "Browses and places orders")
  Rel(staff, shop, "Looks up orders and issues refunds")
  Rel(shop, pay, "Requests payments")
  Rel(shop, wms, "Sends orders for fulfilment")
  Rel(shop, mail, "Sends confirmations")
```

### 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

<!-- Guidance: Zoom into the system boundary: applications and data stores, their technology and how they communicate. This is the most useful diagram for most teams; keep it current. -->

### 4.1 Diagram

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

```mermaid
C4Container
  title Containers of the online shop
  Person(customer, "Customer", "Buys products online")
  System_Ext(pay, "Payment provider", "Card payments")
  System_Ext(wms, "Warehouse system", "Fulfilment")
  System_Boundary(shop, "Online shop") {
    Container(spa, "Web application", "TypeScript, React", "Catalogue, basket and checkout in the browser")
    Container(api, "API application", "Java, Spring Boot", "Business logic and JSON API")
    Container(worker, "Fulfilment worker", "Java", "Sends paid orders to the warehouse")
    ContainerDb(db, "Shop database", "PostgreSQL", "Products, customers, orders")
    ContainerDb(queue, "Message broker", "RabbitMQ", "Order events")
  }
  Rel(customer, spa, "Uses", "HTTPS")
  Rel(spa, api, "Calls", "JSON over HTTPS")
  Rel(api, db, "Reads and writes", "JDBC")
  Rel(api, pay, "Requests payments", "HTTPS")
  Rel(api, queue, "Publishes order paid", "AMQP")
  Rel(worker, queue, "Consumes order paid", "AMQP")
  Rel(worker, wms, "Creates shipments", "HTTPS")
```

### 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

<!-- Guidance: Decompose only the containers where structure is non-obvious or risky. Components are logical groupings behind an interface, not every class. -->

### 5.1 Components of the API application

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

```mermaid
C4Component
  title Components of the API application
  Container(spa, "Web application", "React", "Customer UI")
  ContainerDb(db, "Shop database", "PostgreSQL", "System of record")
  System_Ext(pay, "Payment provider", "Card payments")
  Container_Boundary(api, "API application") {
    Component(orderCtl, "Order controller", "Spring MVC", "REST endpoints for orders")
    Component(orderSvc, "Order service", "Spring bean", "Validates and prices orders")
    Component(payGw, "Payment gateway", "Spring bean", "Wraps the provider API")
    Component(repo, "Order repository", "Spring Data JPA", "Persists orders")
  }
  Rel(spa, orderCtl, "Calls", "JSON over HTTPS")
  Rel(orderCtl, orderSvc, "Uses")
  Rel(orderSvc, payGw, "Requests payment")
  Rel(orderSvc, repo, "Saves orders")
  Rel(repo, db, "Reads and writes", "JDBC")
  Rel(payGw, pay, "Calls", "HTTPS")
```

| 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

<!-- Guidance: Code-level diagrams are optional and best generated from the code. Document only the conventions and the few structures that are hard to see in the IDE. -->

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

<!-- Guidance: Use these when the core four levels are not enough: the landscape for many systems, dynamic for an important flow, deployment for infrastructure. -->

### 7.1 System landscape

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

```mermaid
C4Context
  title System landscape of Acme Retail
  Person(customer, "Customer", "Buys products")
  Person(buyer, "Category buyer", "Manages the assortment")
  Enterprise_Boundary(acme, "Acme Retail") {
    System(shop, "Online shop", "Customer ordering")
    System(pim, "Product information system", "Product data and prices")
    System(wms, "Warehouse system", "Fulfilment")
    System(erp, "ERP", "Finance and invoicing")
  }
  Rel(customer, shop, "Orders products")
  Rel(buyer, pim, "Maintains products")
  Rel(pim, shop, "Publishes catalogue")
  Rel(shop, wms, "Sends orders")
  Rel(shop, erp, "Posts sales")
```

| 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.

```mermaid
C4Dynamic
  title Place order
  Person(customer, "Customer", "Buys products")
  Container(spa, "Web application", "React", "Customer UI")
  Container(api, "API application", "Spring Boot", "Business logic")
  ContainerDb(db, "Shop database", "PostgreSQL", "Orders")
  System_Ext(pay, "Payment provider", "Card payments")
  Rel(customer, spa, "Submits checkout")
  Rel(spa, api, "POST /orders")
  Rel(api, pay, "Authorise payment")
  Rel(api, db, "Store paid 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.

```mermaid
C4Deployment
  title Production deployment
  Deployment_Node(cdn, "CDN", "Edge network") {
    Container(spa, "Web application", "Static files", "Customer UI")
  }
  Deployment_Node(cloud, "Cloud region EU", "Public cloud") {
    Deployment_Node(k8s, "Kubernetes cluster", "Managed Kubernetes") {
      Container(api, "API application", "Container x3", "Business logic")
      Container(worker, "Fulfilment worker", "Container x2", "Warehouse hand-off")
    }
    Deployment_Node(dbnode, "Managed database", "PostgreSQL 16, primary and replica") {
      ContainerDb(db, "Shop database", "PostgreSQL", "Orders")
    }
  }
  Rel(spa, api, "Calls", "HTTPS")
  Rel(api, db, "Reads and writes", "TLS")
```

| 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

<!-- Guidance: C4 shows structure, not reasoning. Link the decisions behind the diagrams and the quality targets they serve. -->

### 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

<!-- Guidance: Keep risks and unanswered questions visible next to the diagrams they affect. -->

### 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.