МАТЕРИАЛЫ КУРСА
СИИ • НАВИГАЦИЯ
← НАЗАД К МАТЕРИАЛАМ

📐 C4 Model + PlantUML = Architecture as Code

Мастер-класс по созданию архитектурных диаграмм C4 с PlantUML — от Context до Component с живыми примерами

~15 МИН ЧТЕНИЯ
ОБНОВЛЕНО НЕДАВНО

📐 C4 Model + PlantUML: Architecture as Code

As Code
В Git, версионируется
Code Review
Ревью диаграмм
Auto-Gen
CI/CD генерация
Docs
Живая документация

🏗️ Четыре уровня C4 Model

Код как документация

Диаграммы создаются кодом, легко версионировать и поддерживать

Командная работа

Изменения видны в Git, можно делать code review диаграмм

Автоматизация

Интегрируется с CI/CD, автогенерация в документацию

Установка и настройка

1. Установка PlantUML

# Через Homebrew (macOS)
brew install plantuml

# Через apt (Ubuntu/Debian)
sudo apt install plantuml

# Или скачать JAR файл
wget https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar

2. C4-PlantUML библиотека

Для работы с C4 Model нужно подключить специальную библиотеку:

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
@enduml

3. Генерация диаграмм

# Генерация PNG
java -jar plantuml.jar -tpng diagram.puml

# Генерация SVG (рекомендуется)
java -jar plantuml.jar -tsvg diagram.puml

# Автообновление при изменениях
java -jar plantuml.jar -gui

🎮 Интерактивный код-плейграунд

Онлайн PlantUML редакторы

PlantUML Server
Официальный онлайн-редактор
PlantUML Editor
Современный интерфейс
Direct SVG
Прямая генерация SVG

🏢 Уровень 1: Context Diagram

Context диаграмма показывает систему как черный ящик в окружении пользователей и внешних систем.

AI Система для анализа документов

AI Document Analysis System

Пользователи:
• Business Analyst
• Data Scientist
• Manager
Внешние системы:
• OpenAI API
• Document Storage
• Email System

Уровень 2: Container Diagram

Container диаграмма показывает высокоуровневые технические компоненты системы и их взаимодействие.

Container архитектура AI системы
Frontend Container
React SPA - пользовательский интерфейс
API Gateway
FastAPI - маршрутизация запросов
AI Service
Python - обработка с LLM
Database
PostgreSQL + Vector DB
Background Jobs
Celery - асинхронная обработка
Monitoring
Langfuse + Grafana

Уровень 3: Component Diagram

Component диаграмма детализирует внутреннюю структуру отдельного контейнера.

Компоненты AI Service

Document Processor
Парсинг PDF, DOCX, TXT

LLM Client
Интеграция с OpenAI API

Prompt Manager
Управление промптами

Result Analyzer
Обработка ответов LLM

Cache Manager
Кэширование результатов

Monitoring Client
Отправка метрик в Langfuse

Практические советы

Лучшие практики

Именование:
  • • Используйте бизнес-термины, а не технические
  • • Краткие, но понятные названия
  • • Единый стиль naming convention
Структура:
  • • Один файл = одна диаграмма
  • • Логическая группировка компонентов
  • • Не более 9 элементов на диаграмме
Детализация:
  • • Context: только ключевые системы
  • • Container: технологические границы
  • • Component: логические модули

Частые ошибки

Слишком сложно:
  • • Показ всех возможных интеграций
  • • Технические детали в Context
  • • Более 10 элементов на диаграмме
Неактуальность:
  • • Диаграммы не обновляются с кодом
  • • Нет версионирования
  • • Отсутствие автоматизации
Неправильный уровень:
  • • Классы в Container диаграмме
  • • Контейнеры в Component диаграмме
  • • Смешивание уровней абстракции

Интеграция в проект

1. Структура файлов

docs/
├── architecture/
│   ├── context.puml           # Context диаграмма
│   ├── containers.puml        # Container диаграмма
│   ├── ai-service.puml        # Components AI Service
│   ├── api-gateway.puml       # Components API Gateway
│   └── README.md              # Описание архитектуры
├── generated/                 # Сгенерированные изображения
│   ├── context.svg
│   ├── containers.svg
│   └── ...
└── scripts/
    └── generate-diagrams.sh   # Скрипт генерации

2. Автоматизация генерации

# Makefile для генерации C4 диаграмм PLANTUML_JAR = plantuml.jar DIAGRAMS_DIR = docs/architecture OUTPUT_DIR = docs/generated FORMAT = svg .PHONY: diagrams clean install install: @echo "Скачиваем PlantUML..." wget -O $(PLANTUML_JAR) https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar diagrams: install @echo "Генерируем C4 диаграммы..." mkdir -p $(OUTPUT_DIR) java -jar $(PLANTUML_JAR) -t$(FORMAT) -o ../$(OUTPUT_DIR) $(DIAGRAMS_DIR)/*.puml @echo "Диаграммы сгенерированы в $(OUTPUT_DIR)/" clean: rm -rf $(OUTPUT_DIR)/*.$(FORMAT) watch: @echo "Мониторинг изменений в $(DIAGRAMS_DIR)..." java -jar $(PLANTUML_JAR) -gui $(DIAGRAMS_DIR) # Использование: # make diagrams - генерация всех диаграмм # make watch - автообновление при изменениях # make clean - очистка сгенерированных файлов

3. Интеграция в документацию

Для автоматической вставки диаграмм в Markdown документацию:

## Архитектура системы

### Context диаграмма
![Context](../generated/context.svg)

### Container диаграмма  
![Containers](../generated/containers.svg)

### AI Service Components
![AI Service](../generated/ai-service.svg)

✅ Чеклист готовности к продакшену

Production Readiness Checklist

📋 Диаграммы готовы:

Context диаграмма показывает систему в окружении
Container диаграмма детализирует технический стек
Component диаграммы показывают внутреннюю структуру

🔄 Автоматизация настроена:

PlantUML файлы в Git репозитории
CI/CD pipeline генерирует диаграммы
Диаграммы автоматически встраиваются в документацию
ВСЕ МАТЕРИАЛЫ