C4 Model

Что такое C4 Model

C4 Model -- иерархический подход к визуализации архитектуры программных систем, созданный Саймоном Брауном. Название C4 происходит от четырёх уровней: Context, Containers, Components, Code.

Аналогия с Google Maps

C4 работает как карта с zoom:

Level 1: System Context  =  Карта мира (Россия на глобусе)
Level 2: Container        =  Карта страны (регионы и города)
Level 3: Component        =  Карта города (улицы и районы)
Level 4: Code             =  Схема здания (комнаты и коридоры)

Каждый уровень отвечает на свой вопрос:
L1: Что это за система и кто её использует?
L2: Из каких технических блоков она состоит?
L3: Из каких модулей состоит каждый блок?
L4: Как устроен каждый модуль внутри?

Level 1: System Context Diagram

Самый высокий уровень. Показывает систему как чёрный ящик, её пользователей и внешние системы.

Аудитория

Все: разработчики, менеджеры, бизнес, стейкхолдеры.

Пример: E-commerce платформа

┌─────────────┐         ┌─────────────────────────┐
│  Customer   │         │     Admin User          │
│  [Person]   │         │     [Person]             │
└──────┬──────┘         └────────────┬────────────┘
       │                             │
       │ Просматривает товары,       │ Управляет каталогом,
       │ делает заказы               │ обрабатывает заказы
       │                             │
       ▼                             ▼
┌──────────────────────────────────────────────────┐
│                                                  │
│           E-COMMERCE PLATFORM                    │
│           [Software System]                      │
│                                                  │
│   Позволяет покупателям выбирать товары          │
│   и оформлять заказы онлайн                      │
│                                                  │
└────────────────────┬─────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        │            │            │
        ▼            ▼            ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│ Payment  │  │  Email   │  │ Delivery │
│ Gateway  │  │ Service  │  │ Service  │
│[External]│  │[External]│  │[External]│
└──────────┘  └──────────┘  └──────────┘

Правила Level 1

Правило	Описание
Система -- один прямоугольник	Не показываем внутреннее устройство
Пользователи -- отдельные блоки	Кто использует систему
Внешние системы	С чем интегрируемся
Стрелки с описанием	Что передаётся и зачем
Без технических деталей	Никаких "REST", "PostgreSQL", "Kafka"

Level 2: Container Diagram

Zoom in внутрь системы. Показывает контейнеры: приложения, базы данных, файловые системы, очереди.

Что такое Container в C4

Container -- это НЕ Docker-контейнер!

Container в C4 = отдельно деплоящийся/запускаемый модуль:
- Web Application (SPA)
- API Application (backend)
- Database (PostgreSQL)
- Message Queue (RabbitMQ)
- Mobile App (iOS/Android)
- File Storage (S3)

Пример: E-commerce Platform (Level 2)

┌──────────┐                              ┌──────────┐
│ Customer │                              │  Admin   │
│ [Person] │                              │ [Person] │
└────┬─────┘                              └────┬─────┘
     │                                         │
     │ HTTPS                                   │ HTTPS
     ▼                                         ▼
┌──────────────────────────────────────────────────────┐
│                 E-COMMERCE PLATFORM                   │
│                                                      │
│  ┌──────────────┐          ┌──────────────────┐     │
│  │  Web App     │          │  Admin Panel     │     │
│  │  [Container: │  HTTPS/  │  [Container:     │     │
│  │   Vue.js SPA]│  JSON    │   Vue.js SPA]    │     │
│  └──────┬───────┘          └────────┬─────────┘     │
│         │                           │                │
│         └──────────┬────────────────┘                │
│                    ▼                                 │
│         ┌──────────────────┐                         │
│         │   API Gateway    │                         │
│         │   [Container:    │                         │
│         │    Nginx]        │                         │
│         └────────┬─────────┘                         │
│                  │                                   │
│      ┌───────────┼───────────┐                      │
│      ▼           ▼           ▼                      │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐                │
│ │ Order   │ │ Catalog │ │  User   │                │
│ │ Service │ │ Service │ │ Service │                │
│ │[Go]     │ │[Go]     │ │[Go]     │                │
│ └────┬────┘ └────┬────┘ └────┬────┘                │
│      │           │           │                      │
│      ▼           ▼           ▼                      │
│ ┌──────────────────────────────────┐                │
│ │        PostgreSQL                │                │
│ │        [Container: Database]     │                │
│ └──────────────────────────────────┘                │
│                                                      │
│ ┌──────────┐  ┌──────────┐                          │
│ │  Redis   │  │ RabbitMQ │                          │
│ │ [Cache]  │  │ [Queue]  │                          │
│ └──────────┘  └──────────┘                          │
└──────────────────────────────────────────────────────┘

Правила Level 2

Правило	Описание
Каждый container -- отдельный процесс	Может быть задеплоен отдельно
Указываем технологию	Vue.js, Go, PostgreSQL
Стрелки с протоколом	HTTPS, gRPC, AMQP, SQL
Границы системы видны	Рамка вокруг контейнеров

Level 3: Component Diagram

Zoom in внутрь одного контейнера. Показывает основные компоненты: контроллеры, сервисы, репозитории.

Пример: Order Service (Level 3)

┌──────────────────────────────────────────────────┐
│              ORDER SERVICE [Container: Go]        │
│                                                  │
│  ┌─────────────────┐    ┌──────────────────┐    │
│  │  Order          │    │  Order           │    │
│  │  Controller     │───▶│  Service         │    │
│  │  [Component:    │    │  [Component:     │    │
│  │   HTTP Handler] │    │   Business Logic]│    │
│  └─────────────────┘    └────────┬─────────┘    │
│                                  │              │
│                    ┌─────────────┼──────────┐   │
│                    ▼             ▼          ▼   │
│  ┌──────────────┐ ┌──────────┐ ┌─────────────┐ │
│  │  Order       │ │ Payment  │ │ Notification│ │
│  │  Repository  │ │ Client   │ │ Publisher   │ │
│  │  [Component: │ │[Component│ │ [Component: │ │
│  │   DB Access] │ │ HTTP]    │ │  AMQP]      │ │
│  └──────┬───────┘ └────┬─────┘ └──────┬──────┘ │
│         │              │              │         │
└─────────┼──────────────┼──────────────┼─────────┘
          │              │              │
          ▼              ▼              ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │PostgreSQL│  │ Payment  │  │ RabbitMQ │
    │          │  │ Gateway  │  │          │
    └──────────┘  └──────────┘  └──────────┘

Правила Level 3

Правило	Описание
Только один контейнер	Не смешивать компоненты разных контейнеров
Компоненты -- логические блоки	Пакеты, модули, классы
Внешние зависимости за рамкой	БД, другие сервисы
Не для каждого контейнера	Только для ключевых

Level 4: Code Diagram

Zoom in внутрь компонента. Обычно UML Class или Package diagram.

Когда нужен Level 4

НУЖЕН:                              НЕ НУЖЕН:
- Сложная бизнес-логика             - CRUD-операции
- Критический компонент             - Простые сервисы
- Onboarding новых разработчиков    - Прототипы
- Код с неочевидной структурой      - Большинство случаев

Пример: Order Service (Level 4)

┌──────────────────────────────────────┐
│          <<interface>>               │
│          OrderRepository             │
│  ─────────────────────────           │
│  + FindByID(id UUID) Order           │
│  + Save(order Order) error           │
│  + FindByUser(userID UUID) []Order   │
└───────────────┬──────────────────────┘
                │ implements
                ▼
┌──────────────────────────────────────┐
│       PostgresOrderRepository        │
│  ─────────────────────────           │
│  - db *sql.DB                        │
│  ─────────────────────────           │
│  + FindByID(id UUID) Order           │
│  + Save(order Order) error           │
└──────────────────────────────────────┘

┌──────────────────────────────────────┐
│             Order                    │
│  ─────────────────────────           │
│  - id UUID                           │
│  - userID UUID                       │
│  - items []OrderItem                 │
│  - status OrderStatus                │
│  - total Money                       │
│  ─────────────────────────           │
│  + AddItem(item OrderItem)           │
│  + CalculateTotal() Money            │
│  + Submit() error                    │
│  + Cancel() error                    │
└──────────────────────────────────────┘

Diagrams as Code с Structurizr

Structurizr DSL -- инструмент для описания C4-моделей в текстовом формате.

Пример Structurizr DSL

workspace {
    model {
        customer = person "Customer" "A buyer"
        admin = person "Admin" "Manages catalog"

        ecommerce = softwareSystem "E-Commerce" {
            webapp = container "Web App" "Vue.js SPA" "JavaScript"
            api = container "API" "Backend API" "Go"
            db = container "Database" "Stores data" "PostgreSQL"

            webapp -> api "Makes API calls" "HTTPS/JSON"
            api -> db "Reads/writes" "SQL"
        }

        customer -> webapp "Browses and orders"
        admin -> webapp "Manages catalog"
    }

    views {
        systemContext ecommerce "Context" {
            include *
            autolayout lr
        }
        container ecommerce "Containers" {
            include *
            autolayout lr
        }
    }
}

Альтернативы

Инструмент	Описание
Structurizr	Официальный инструмент C4 (DSL + рендер)
PlantUML + C4	C4 через PlantUML-макросы
Mermaid C4	C4 в Markdown через Mermaid
D2	Универсальный Diagrams as Code
IcePanel	Визуальный C4 с коллаборацией

Дополнительные диаграммы C4

System Landscape Diagram

Показывает ВСЕ системы организации (уровень выше L1):

┌──────────┐   ┌──────────┐   ┌──────────┐
│  CRM     │   │E-Commerce│   │Analytics │
│  System  │──▶│ Platform │──▶│ Platform │
└──────────┘   └──────────┘   └──────────┘
       │              │              │
       └──────────────┼──────────────┘
                      ▼
               ┌──────────┐
               │  Identity│
               │  Provider│
               └──────────┘

Deployment Diagram

Показывает КАК и ГДЕ развёрнута система:

┌─────────────────────────────┐
│     AWS Region: eu-west-1   │
│                             │
│  ┌───────────────────────┐  │
│  │  ECS Cluster          │  │
│  │  ┌─────┐ ┌─────┐     │  │
│  │  │ API │ │ API │     │  │
│  │  │ (x2)│ │ (x2)│     │  │
│  │  └─────┘ └─────┘     │  │
│  └───────────────────────┘  │
│                             │
│  ┌───────────────────────┐  │
│  │  RDS PostgreSQL       │  │
│  │  (Multi-AZ)           │  │
│  └───────────────────────┘  │
└─────────────────────────────┘

Итоги

Уровень	Аудитория	Детализация
L1: System Context	Все	Система + окружение
L2: Container	Технические	Приложения + БД + очереди
L3: Component	Разработчики	Модули внутри контейнера
L4: Code	Разработчики	Классы и интерфейсы

Главное правило: Рисуй Level 1 и 2 для каждого проекта. Level 3 -- для ключевых контейнеров. Level 4 -- почти никогда (код меняется слишком часто).