# C4-модель описания архитектуры

← [Раздел](README.md) · [Главная](../README.md)

## Цель

Освоить **C4 model** — четыре уровня диаграмм для описания облачной системы: от контекста до кода, без перегруза деталями на ранних этапах.

## Предварительно

- [NFR и SLA](nfr-i-sla.md)
- Базовое знакомство с [компонентами](../02-komponenty/README.md)

## Время

**4–6 часов** (чтение + 2 диаграммы в draw.io)

---

## Зачем C4

Одна «гигантская схема» с классами и IP пугает менеджера и устаревает за неделю. **C4** (Simon Brown) задаёт **зум**:

| Уровень | Аудитория | Детализация |
|---------|-----------|-------------|
| **1. System Context** | Все | Система и внешние акторы |
| **2. Containers** | Разработчики, архитекторы | Приложения, БД, очереди |
| **3. Components** | Команда сервиса | Модули внутри container |
| **4. Code** | Разработчики | Классы (редко вручную) |

На курсе фокус на **Context + Container** — этого хватает для 80% обсуждений.

---

## Уровень 1: System Context

**Один прямоугольник** — ваша система. Вокруг — люди и внешние системы.

```mermaid
flowchart TB
  User[Пользователь семьи]
  Admin[Админ поддержки]
  subgraph system [Умный список покупок]
    App[Система списков]
  end
  Email[Email SaaS]
  User -->|использует| App
  Admin -->|поддержка| App
  App -->|отправка писем| Email
```

| Элемент | Описание |
|---------|----------|
| Пользователь | Мобильное/веб приложение |
| Система | Всё, что вы разрабатываете и деплоите |
| Email SaaS | Внешний провайдер, не ваш код |

**Не рисуем:** PostgreSQL, Kubernetes — это уровень 2.

---

## Уровень 2: Containers

**Container** в C4 ≠ Docker. Это **развёртываемая единица**: приложение, БД, SPA.

```mermaid
flowchart TB
  User[Пользователь]
  subgraph platform [Платформа Умный список]
    SPA[Web SPA]
    Mobile[Mobile App]
    API[Backend API]
    DB[(PostgreSQL)]
    Redis[(Redis)]
    Q[Message Queue]
    Worker[Email Worker]
  end
  Email[Email SaaS]
  User --> SPA
  User --> Mobile
  SPA -->|HTTPS JSON| API
  Mobile -->|HTTPS JSON| API
  API --> DB
  API --> Redis
  API --> Q
  Q --> Worker
  Worker --> Email
```

Подписи на стрелках: **протокол и назначение** (`HTTPS/JSON`, `SQL`, `AMQP`).

---

## Уровень 3: Components (внутри API)

Для монолитного API container раскрывается на модули:

```mermaid
flowchart TB
  subgraph API [Backend API container]
    AuthC[Auth Controller]
    ListsC[Lists Controller]
    ListSvc[List Service]
    UserSvc[User Service]
    Repo[Repositories]
  end
  DB[(PostgreSQL)]
  AuthC --> UserSvc
  ListsC --> ListSvc
  ListSvc --> Repo
  UserSvc --> Repo
  Repo --> DB
```

Микросервисы: каждый **сервис** — отдельный container на уровне 2; component diagram — внутри одного сервиса.

---

## Уровень 4: Code

Обычно **генерируется** из IDE или не рисуется вручную. ADR и тесты важнее UML на 200 классов.

---

## Нотация и стиль

| Правило | Зачем |
|---------|-------|
| Один диаграмма — один уровень | Не смешивать Context и БД |
| Имена понятные бизнесу | «Список покупок API», не `svc-7f3a` |
| Легенда протоколов | HTTPS, gRPC, JDBC |
| Дата и версия в углу | «2026-06-16, v0.3» |

Инструменты: [diagrams.net](https://app.diagrams.net), Structurizr, Mermaid (для простых схем в git).

---

## Связь C4 с требованиями

| FR/NFR | Где видно на C4 |
|--------|-----------------|
| FR-4 приглашения | Container Worker + Email SaaS |
| NFR-P1 latency | Redis container |
| NFR-A1 availability | Несколько API за LB (добавить на L2) |

---

## Типичные ошибки

| Ошибка | Исправление |
|--------|-------------|
| 50 микросервисов на Context | Один блок «Платформа» |
| IP и порты на Context | Только на deployment diagram (другой вид) |
| Нет внешних систем | Забыли платежи, SSO |
| Container = Docker only | БД тоже container в C4 |

---

## Deployment diagram (дополнение)

Отдельно от C4: **где** крутятся containers — AWS region, K8s namespace, nodes. Полезно для Ops, не для первой встречи с заказчиком.

---

## Практика

1. Нарисуйте Context для учебного кейса (3 актора максимум).  
2. Раскройте Container: минимум API, DB, клиент, очередь, worker.  
3. Добавьте на Container диаграмму один компонент внутри API.

---

## Самопроверка

1. Чем C4 Container отличается от Docker-контейнера?  
2. Что показывает уровень Context?  
3. Почему не рисуют PostgreSQL на Context?

---

## Дальше

→ [ADR — архитектурные решения](adr-resheniya.md)