C4-диаграммы в PlantUML: контекст, контейнеры, компоненты

Как рисовать архитектуру по модели C4 в PlantUML: подключение C4-PlantUML из стандартной библиотеки, люди, системы, контейнеры, связи и границы.

Модель C4 описывает архитектуру на четырёх уровнях: контекст системы, контейнеры (приложения и хранилища), компоненты, код. Для первых трёх уровней есть готовая библиотека C4-PlantUML — она входит в стандартную библиотеку PlantUML и подключается одной строкой.

Диаграмма контейнеров

@startuml
!include <C4/C4_Container>

Person(user, "Покупатель")
System_Boundary(shop, "Интернет-магазин") {
  Container(web, "Веб-приложение", "React", "Каталог и корзина")
  Container(api, "Order API", "Java, Spring Boot")
  ContainerDb(db, "База заказов", "PostgreSQL")
  ContainerQueue(bus, "События", "Kafka")
}
System_Ext(pay, "Платёжный шлюз")

Rel(user, web, "Покупки", "HTTPS")
Rel(web, api, "Вызовы API", "JSON/HTTPS")
Rel(api, db, "Чтение и запись", "SQL")
Rel(api, bus, "OrderPlaced")
Rel(api, pay, "Оплата", "REST")
SHOW_LEGEND()
@enduml

Вставьте в песочницу PlantUML — диаграмма нарисуется в стиле C4 с легендой.

Диаграмма контейнеров C4 интернет-магазина — Диаграмма контейнеров C4 с легендой

Уровни и подключения

!include <C4/C4_Context> — контекст: Person, System, System_Ext.
!include <C4/C4_Container> — контейнеры: Container, ContainerDb, ContainerQueue, границы System_Boundary.
!include <C4/C4_Component> — компоненты внутри контейнера: Component, Container_Boundary.
!include <C4/C4_Dynamic> и <C4/C4_Deployment> — динамические диаграммы и развёртывание.

Подключение по сетевому адресу (!include https://raw.githubusercontent.com/…), которое часто встречается в примерах, здесь запрещено — используйте форму с угловыми скобками из стандартной библиотеки.

Связи и раскладка

Rel(a, b, "что", "как") — связь с описанием и технологией; BiRel — двусторонняя.
Rel_D, Rel_R, Rel_L, Rel_U — подсказать направление, если раскладка неудачна.
LAYOUT_LEFT_RIGHT() — горизонтальная раскладка всей диаграммы.
SHOW_LEGEND() — легенда с обозначениями.

Советы

На одной диаграмме — один уровень детализации.
Указывайте технологию у контейнеров и протокол у связей — это то, что ищут при ревью архитектуры.
Храните диаграммы уровней в одной папке проекта с ADR и спецификациями.

Пример: диаграмма контекста

@startuml
!include <C4/C4_Context>
Person(analyst, "Аналитик")
System(helper, "Помощник SA", "Документация и диаграммы")
System_Ext(git, "GitLab", "Код и CI")
Rel(analyst, helper, "Пишет спецификации")
Rel(git, helper, "Читает схемы", "API")
@enduml

Вопросы и ответы

Почему не работает пример из интернета? Чаще всего он подключает библиотеку по адресу https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/…. Замените строку на !include <C4/C4_Container> (или нужный уровень) — остальной код менять не нужно.

Можно ли рисовать C4 в Structurizr DSL? Нет, поддерживается C4-PlantUML. Он описывает те же уровни и подходит для хранения в документации.