diagram-as-code
Visualize workflows, architecture and business processes as Mermaid/C4/PlantUML with validation. Use for any diagram.
Diagram as Code
Workflows, architecture and business processes as validated code, not pixels.
Quick Start
flowchart TD
A[User request] --> B{Needs diagram?}
B -->|yes| C[Pick type: flowchart/sequence/C4]
B -->|no| D[Skip]
C --> E[Write Mermaid]
E --> F[Validate + render]# render locally or paste into Mermaid Live
npx @mermaid-js/mermaid-cli -i docs/arch.mmd -o docs/arch.svg
# optional: wire the render into your own validator,
# e.g.: python scripts/validate_mermaid.py docs/arch.mmdWhen to Use
- System architecture and service maps
- Business processes and approval flows
- Sequence diagrams for APIs and auth
- State machines, ER diagrams, C4 models
- Docs that must stay in sync with code
Best Practices
Picking the Type
- Flowchart: decisions and processes, max 12 nodes per view
- Sequence: interactions over time, name every actor
- Class/ER: data models, no methods except key behavior
- State: explicit initial/final, every transition labeled
- C4: Context for stakeholders, Container for teams, Component for devs
Readability
- One idea per diagram, split large flows into subgraphs
- Left-to-right for processes, top-to-bottom for hierarchies
- Short node labels (3-5 words), details in notes
- Stable ids in latin, human labels separate
Correctness
- Every branch has a condition label
- No orphan nodes, no crossing arrows without need
- Actors and services match the real codebase names
- Version the diagram next to the code it describes
Rendering
- Prefer Mermaid for Markdown-native docs
- C4-PlantUML for enterprise architecture
- SVG output for docs site, dark + light tested
- Keep source `.mmd` in git, render on CI
Dependencies
npm i -g @mermaid-js/mermaid-cli
# optional: java + plantuml for C4
java -versionExamples
sequenceDiagram
participant U as User
participant A as Agent
participant T as Tools
U->>A: Build checkout form
A->>A: Read design-spec-md
A->>T: search styles + tokens
T-->>A: design system
A->>U: Code + checkliststateDiagram-v2
[*] --> Draft
Draft --> Review: submit
Review --> Approved: accept
Review --> Draft: request changes
Approved --> [*]@startsalt
salt
{
{T
+ Order | Status | Total
+ #1234 | paid | $89
+ #1235 | pending | $12
}
}
@endsalterDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
USER {
string id PK
string email
}
ORDER {
string id PK
string status
}## Decision cheat-sheet
- Process with branches -> flowchart TD/LR
- Two+ actors over time -> sequenceDiagram
- Data tables and keys -> erDiagram
- Lifecycle with transitions -> stateDiagram-v2
- Enterprise landscape -> C4 Context/ContainerStep-by-Step
1. State the single question the diagram answers.
2. Pick the minimal type (flowchart, sequence, ER, state, C4).
3. Draft nodes with stable ids and short labels.
4. Label every edge and condition.
5. Validate syntax with the CLI script.
6. Render SVG and check dark/light readability.
7. Split if more than 12 nodes or 3 swimlanes.
8. Commit `.mmd` source next to docs, link from README.
Validation
1. Mermaid/PlantUML parses with zero errors
2. One question answered, no second story hidden inside
3. All branches labeled, no orphan nodes
4. Names match code and docs terminology
5. Renders cleanly in GitHub, docs site, and print
Troubleshooting
- Render fails: check unescaped brackets, quotes, and `#` in labels.
- Spaghetti arrows: switch direction TD/LR or split into subgraphs.
- Too dense: extract a subgraph per actor or per phase.
- GitHub shows code not diagram: fence must be `mermaid` language tag exactly.
- C4 too abstract: drop one level (Context -> Container -> Component).
Диаграммы как код (Diagram as Code)
Воркфлоу, архитектура и бизнес-процессы как проверяемый код, а не пиксели.
Быстрый старт
flowchart TD
A[Запрос] --> B{Нужна диаграмма?}
B -->|да| C[Тип: flowchart/sequence/C4]
B -->|нет| D[Пропустить]
C --> E[Пишем Mermaid]
E --> F[Валидация + рендер]# рендер локально или вставьте в Mermaid Live
npx @mermaid-js/mermaid-cli -i docs/arch.mmd -o docs/arch.svg
python scripts/validate_mermaid.py docs/arch.mmdКогда использовать
- Архитектура систем и карта сервисов
- Бизнес-процессы и согласования
- Sequence-диаграммы для API и авторизации
- Машины состояний, ER-диаграммы, C4-модели
- Доки, которые обязаны жить вместе с кодом
Лучшие практики
Выбор типа
- Flowchart: решения и процессы, макс 12 узлов на вид
- Sequence: взаимодействия во времени, каждый актор поименован
- Class/ER: модели данных, без лишних методов
- State: явные initial/final, каждый переход подписан
- C4: Context для стейкхолдеров, Container для команд, Component для девов
Читаемость
- Одна идея на диаграмму, большое режьте на подграфы
- Процессы слева направо, иерархии сверху вниз
- Короткие подписи (3-5 слов), детали в заметках
- Стабильные id латиницей, человеческие подписи отдельно
Корректность
- У каждой ветки подписано условие
- Без висячих узлов и лишних пересечений стрелок
- Акторы и сервисы совпадают с именами в коде
- Диаграмма версионируется рядом с кодом
Рендеринг
- Mermaid для Markdown-доков
- C4-PlantUML для enterprise-архитектуры
- SVG для сайта доков, проверяйте dark + light
- Исходник `.mmd` в git, рендер на CI
Зависимости
npm i -g @mermaid-js/mermaid-cli
# опционально: java + plantuml для C4
java -versionПримеры
sequenceDiagram
participant U as Пользователь
participant A as Агент
participant T as Инструменты
U->>A: Собери форму оплаты
A->>A: Читаю design-spec-md
A->>T: поиск стилей + токенов
T-->>A: дизайн-система
A->>U: Код + чек-листstateDiagram-v2
[*] --> Draft
Draft --> Review: submit
Review --> Approved: accept
Review --> Draft: правки
Approved --> [*]@startsalt
salt
{
{T
+ Заказ | Статус | Сумма
+ #1234 | оплачен | $89
+ #1235 | ждет | $12
}
}
@endsalterDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
USER {
string id PK
string email
}
ORDER {
string id PK
string status
}## Шпаргалка выбора
- Процесс с ветками -> flowchart TD/LR
- Два+ актора во времени -> sequenceDiagram
- Таблицы и ключи -> erDiagram
- Жизненный цикл -> stateDiagram-v2
- Enterprise-ландшафт -> C4 Context/ContainerПошаговое руководство
1. Сформулируйте один вопрос, на который отвечает диаграмма.
2. Выберите минимальный тип (flowchart, sequence, ER, state, C4).
3. Набросайте узлы со стабильными id и короткими подписями.
4. Подпишите каждое ребро и условие.
5. Проверьте синтаксис CLI-скриптом.
6. Отрендерьте SVG и проверьте читаемость в dark/light.
7. Разбейте, если больше 12 узлов или 3 дорожек.
8. Закоммитьте `.mmd` рядом с доками, ссылку в README.
Валидация
1. Mermaid/PlantUML парсится без ошибок
2. Отвечен один вопрос, второй истории внутри нет
3. Все ветки подписаны, висячих узлов нет
4. Имена совпадают с кодом и терминологией
5. Чистый рендер в GitHub, на сайте и в печати
Устранение неполадок
- Рендер падает: проверьте скобки, кавычки и `#` в подписях.
- Спагетти-стрелки: смените направление TD/LR или режьте на подграфы.
- Слишком плотно: вынесите подграф на актора или фазу.
- GitHub показывает код: у забора должен быть языковой тег `mermaid`.
- C4 слишком абстрактна: спуститесь на уровень (Context -> Container -> Component).