Назначение
C4 — способ рисовать архитектуру на разных уровнях «зума», как карту: от общего к частному. Решает проблему диаграмм-«монстров», где всё на одном листе и ничего не понятно. Четыре уровня дают каждому зрителю нужную детализацию: стейкхолдеру — Context, инженеру — Container/Component.
Четыре уровня (шаблон описания)
# 1. Context (вид с высоты)
Система целиком как один «ящик» + пользователи (акторы) + внешние системы вокруг.
Вопрос: кто пользуется и с чем система связана снаружи?
# 2. Container (что внутри)
Приложения/сервисы/БД внутри системы и как они общаются.
(контейнер = отдельно запускаемая/деплоится штука: SPA, API-сервис, БД, очередь)
Вопрос: из каких крупных кусков состоит и по каким протоколам они говорят?
# 3. Component (внутри контейнера)
Крупные части внутри одного контейнера и их связи.
Вопрос: как устроен конкретный сервис изнутри?
# 4. Code (детали)
Классы/модули компонента — рисуют редко, по необходимости (часто это просто код).
Пример 1 — Context (AI-Арсенал)
# Context: AI-Арсенал
Акторы:
- Пользователь (контент-мейкер/разработчик) — ищет инструменты, сохраняет избранное.
Система:
- [AI-Арсенал] — база знаний инструментов/ролей/промтов с персональным ядром.
Внешние системы:
- [Облако Laskoff] ← синхронизация персонального ядра (HTTPS).
- [Внешние ресурсы] ← кнопки «Открыть» ведут на GitHub/доки инструментов.
Связи: Пользователь → AI-Арсенал (web); AI-Арсенал → Облако (REST/WS, sync).
Пример 2 — Container (тот же продукт)
# Container: AI-Арсенал
Контейнеры внутри системы:
- [Web App (React/TS SPA)] — UI, локальный поиск, рендер карточек.
- [IndexedDB] — персональное ядро в браузере (favs/notes/collections).
- [Sync API (Fastify/Node)] — приём/выдача ядра, аутентификация.
- [PostgreSQL] — серверное хранение ядра пользователей.
- [Redis] — сессии/presence/адаптер realtime.
Связи:
- Web App → IndexedDB (чтение/запись локально).
- Web App → Sync API (HTTPS REST + WebSocket для realtime).
- Sync API → PostgreSQL (SQL), Sync API → Redis (кэш/pubsub).
Когда применять
- Объяснить архитектуру новичку, стейкхолдеру, в ADR/System Design Doc.
- Чаще всего достаточно Context + Container — это 90% пользы при 10% усилий.
- Component — когда нужно вскрыть конкретный сложный сервис. Code — почти никогда.
Чек-лист качества
- Один уровень = один масштаб (не смешивать на одной диаграмме).
- Подписаны связи: кто → кого и по какому протоколу/технологии.
- Контейнер — именно «отдельно запускаемое», а не папка с кодом.
- Указаны технологии в скобках (React, PostgreSQL…).
- Диаграмма читается без автора (легенда/подписи понятны).
Частые ошибки
- Всё на одном уровне (Context + классы вперемешку). → Разнеси по уровням зума.
- Связи без подписи. → Всегда «кто → кого, по чему» (HTTPS, SQL, очередь).
- Контейнер = модуль кода. → Контейнер деплоится/запускается отдельно; модуль — это Component/Code.
- Рисуют Code-уровень всегда. → Почти никогда не нужен; это и есть сам код.
- Диаграмма для себя. → Делается, чтобы понял другой; добавь легенду и технологии.