C4 и архитектурная документация на собеседовании SA
Зачем архитектурная документация на собесе SA
Архитектурная документация — отличает middle от senior SA. Middle делает диаграммы по запросу. Senior — выстраивает систему документации: что хранить, на каком уровне детализации, для какой аудитории.
На собесе системного аналитика C4 / ADR / документация спрашивают через кейсы: «нарисуй архитектуру системы X», «как организуешь docs в команде из 50 человек». Слабый ответ — «UML и Confluence». Сильный — про C4 уровни, ADR для решений, living documentation.
C4-модель
C4 (Context, Containers, Components, Code) — простая модель архитектурных диаграмм. Создана Simon Brown как «UML лайт». В 2026 — индустриальный стандарт для архитектурной документации.
4 уровня:
1. System Context — система и её внешние actors (users, third-party systems). Самый верхний уровень, для нетехнических stakeholders.
2. Container — high-level technology decisions. Web app, mobile app, backend API, database, message broker. Каждый «container» = deployable unit.
3. Component — внутри одного container: компоненты (модули, классы). Для разработчиков, для понимания структуры внутри сервиса.
4. Code — UML / class diagrams (опционально, обычно не нужны).
Когда какой уровень
- Context: на собес-задаче «спроектируй систему» — начинать с context. Презентация бизнесу — context.
- Container: main diagram. Используется чаще всего. На onboarding нового разработчика.
- Component: для сложных сервисов, где внутренняя структура не очевидна.
- Code: редко. Современные IDE генерируют по коду, ручная поддержка — overhead.
Tools
Structurizr — official tool Simon Brown. Code-as-documentation: DSL описывает архитектуру, диаграммы генерируются.
PlantUML + C4 macros — open-source, диаграммы как текст.
Mermaid — embed в Markdown, GitHub рендерит. Простой синтаксис.
Draw.io / Lucidchart — drag-and-drop, для команд без code-as-doc культуры.
Excalidraw — hand-drawn стиль, популярен для quick architecture sketches.
Подробнее — C4 диаграммы на собесе SA.
Architecture Decision Records (ADR)
Документ, фиксирующий важное архитектурное решение. Формат — короткий markdown в репо.
Структура:
- Title: «ADR-042: Использовать Kafka вместо RabbitMQ для event streaming»
- Status: Proposed / Accepted / Deprecated / Superseded
- Context: что произошло, какие были опции
- Decision: что решили
- Consequences: что получили, какие trade-offs
Зачем:
- Новый человек в команде видит «почему так» — не повторяет рассуждения
- Старое решение можно review через год: «контекст изменился, нужно ли revisit»
Хранение:
docs/adr/0001-use-kafka.md,0002-...- В корне репо или в
architecture/ - В коде, не в Confluence — версионирование, review через PR
Подробнее — ADR на собесе SA.
Living documentation
Документация, которая обновляется автоматически из кода / runtime.
Примеры:
- OpenAPI / Swagger — API contract из кода (Spring, FastAPI)
- TypeScript types — interfaces как документация
- dbt docs — data catalog генерируется из моделей
- Storybook — UI компоненты с примерами
Принцип: документация и код — один source of truth. Расходятся = bug.
Что хранить, что не хранить
Хранить:
- C4 Context + Container диаграммы (1-2 файла на сервис)
- ADR для важных решений
- README для каждого сервиса (что делает, как запустить, owner)
- Runbook для on-call (как разруливать инциденты)
- API contracts (OpenAPI, AsyncAPI для Kafka topics)
Не хранить (или генерировать):
- Code-level диаграммы (генерируются IDE)
- Detailed sequence diagrams для каждого endpoint (быстро устаревают)
- «How everything works» — слишком абстрактно, не читается
- Дублирующая информация (если в README — не дублировать в Confluence)
RFC процесс
Для больших архитектурных изменений — RFC (Request for Comments).
Flow:
- Author пишет RFC document
- Команда review (async, comments)
- Discussion в meeting
- Decision → ADR
Зачем:
- Обсуждение до implementation
- Surface concerns раньше
- Archive решений
Известные RFC: Rust RFCs, Kubernetes KEPs, Python PEPs.
Документация в разных аудиториях
- Junior developer: README + onboarding doc
- Senior developer: ADR + Container diagram
- Product manager: Context diagram + capability map
- Executive: one-pager strategy
- On-call engineer: runbook + monitoring dashboards
- Auditor / compliance: data flow, PII inventory
Не пытайся one-size-fits-all.
Типичные вопросы
«Нарисуй архитектуру системы заказов»
Начни с C4 Context: пользователь, web/mobile clients, Order System, downstream (Payment, Inventory, Shipping). Затем Container: API gateway, Order Service, Order DB, Kafka, Inventory Service, Payment Service. Component — по запросу для одного сервиса.
«Как организуешь docs в команде?»
В коде: README per service, ADR в docs/adr/. Centrally: Confluence / Notion для product-level docs. Living docs: OpenAPI, dbt docs auto-generated. RFC для big changes.
«ADR vs RFC?»
RFC — proposal, обсуждение. ADR — фиксация принятого решения. RFC → ADR.
«Как поддерживать docs актуальными?»
Living docs (auto-gen). Code review check: «if API changed — обновлены ли OpenAPI / docs». Quarterly doc cleanup. Doc owner per area.
Частые ошибки
- UML «всё подряд». Чрезмерно детальные диаграммы устаревают за неделю
- Без ADR. Через год «почему так?» — никто не помнит
- Documentation as afterthought. Деплой → потом задокументирую → через месяц нет docs
- Confluence как кладбище. Старые страницы не удаляются, поиск показывает outdated
- Игнор различия аудиторий. «Single source of truth» — но для разных людей нужна разная глубина
FAQ
C4 или UML?
C4 — для архитектуры (high-level). UML — class / sequence, для кода (но генерируется автоматически). На собесе SA — C4.
Как часто обновлять?
ADR — append-only (новое решение = новый ADR). C4 Container — раз в квартал или при major change. README — каждый PR, который меняет setup.
Diagrams as code vs draw.io?
Diagrams as code: версионирование, code review. Draw.io: быстрее для quick sketches. Зрелые команды — code; стартапы — обе.
Кто owner docs?
Per-service: tech lead. Global: principal engineer / staff. Без owner-а — documentation rot.
AsyncAPI стоит изучать?
Для Kafka-heavy архитектур — да. AsyncAPI = OpenAPI для event-driven systems.