Перейти к содержанию

Visualization tooling decision — 2026-05-19🔗

Superseded

Superseded by the Living Architecture Map pilot (2026-06-22) — see architecture/overview.md. This document (Structurizr + Mermaid + pydeps exploration) is retained for history; do not follow it for current tooling.

Status: DEFERRED (research done, implementation в Phase 3-4 после стабилизации структуры src/). Trigger to revisit: после Phase 3 миграции — когда reports/narodnaya/ стабилизируется, иначе drift гарантирован.

1. Контекст / зачем нужно🔗

Discovery 2026-05-19 показала что у проекта нет визуальной архитектурной документации. Code-level импорты ясны, но как pipeline narodnaya течёт от SocialScan до CSV-отчёта — нет графического обзора. При росте scope (53 кандидата, Wave D) это станет блокером onboarding для будущих сессий Claude Code.

Текущее состояние: три текстовых файла decisions-log + concept-doc + roadmap. Это хорошо для ADR-style решений, но недостаточно для быстрого spatial reasoning по системе. Отдельная проблема: legacy TG/VK pipeline и новый SocialScan-flow существуют параллельно — без диаграмм граница между ними неочевидна из кода.

Почему сейчас не реализуем: структура src/polit_media_radar/ ещё не стабильна. SocialScan adapter живёт в pilot/, reports/narodnaya/ под вопросом, pipelines vs reports namespace не финализирован. Диаграммы написанные сейчас устареют за одну волну рефакторинга. Закон Goodhart в применении к документации: diagram, optimised for today's structure, becomes misleading noise post-Phase 3.

2. Selected stack (3 layers)🔗

Layer Tool Файлы Кто обновляет
L1: High-level (C1 + C2) Structurizr DSL + docker run structurizr/lite docs/architecture/workspace.dsl + exported PNG в docs/architecture/c4/ Claude при изменении компонентов/границ
L2: Sequences, state, ER, flows Mermaid inline в markdown docs/architecture/flows/*.md Claude в том же PR что меняет код
L3: Python module deps pydeps + Graphviz docs/architecture/deps/module-deps.svg On-demand после крупного refactor

Три слоя — потому что разные аудитории и разные частоты обновления. L1 меняется редко (граница системы стабильна). L2 меняется при каждом значимом code change. L3 нужен только после крупных структурных сдвигов.

3. Rationale по инструментам🔗

Layer 1: Structurizr DSL🔗

Единственный зрелый tool где Context (C1) + Container (C2) — одна связная модель с навигацией между views. DSL text-based, git-versionable, diff-friendly. Self-hosted Lite через Docker — бесплатно, без vendor lock-in. Simon Brown (автор C4 model) явно называет AI-friendliness критерием дизайна DSL.

Trade-offs: Docker overhead при локальном рендере — но Docker уже в стеке проекта. Нет GitHub native rendering — митигация: PNG экспортируется и коммитится рядом с DSL (docs/architecture/c4/*.png). Человек видит PNG, Claude читает DSL-источник.

Layer 2: Mermaid🔗

88k+ GitHub stars, native rendering в GitHub/GitLab/Obsidian, LLM accuracy ~90% по benchmark исследования (vs ~60% D2). Mermaid v11 добавил architecture-beta — C4-подобные service diagrams с группировкой. Sequence, state, ER, flowchart — один синтаксис, zero runtime зависимостей.

Trade-off: layout engine Dagre непредсказуем при >15-20 nodes на диаграмму. Митигация: жёсткий лимит — одна диаграмма = одна концепция, не пытаться показать всё сразу.

Layer 3: pydeps🔗

Единственный активно поддерживаемый Python-tool для auto-gen import graphs (v3.0.6, 2025). Показывает циклы, cluster-mode группирует по пакетам. Graphviz dependency — но это системный пакет, не Python dependency.

Trade-off: SVG бинарный blob в git. Митигация: обновлять только вручную при крупных рефакторах, не в CI.

4. Что НЕ берём и почему🔗

Tool Причина отказа
D2 (Terrastruct) Нет native GitHub rendering. LLM accuracy ~60% vs 90% Mermaid — killer criterion для AI-first workflow.
PlantUML + C4-PlantUML Java runtime overhead. GPL 3.0 (licensing friction). LLM accuracy заметно хуже Mermaid по тем же benchmarks.
IcePanel Платный SaaS, vendor lock-in, данные не в git. Противоречит принципу text-as-source-of-truth.
Backstage / Compass Enterprise infrastructure, overkill для solo dev + одного Claude-агента.
C3/C4 levels (Components/Code) Simon Brown сам предупреждает: эти уровни устаревают за недели в agile-контексте. Только C1+C2 justified для solo.
pyreverse Не обновляется как отдельный инструмент, живёт внутри pylint с непредсказуемым CLI.
arc42 как полная methodology 12 секций arc42 — overhead для solo. Можно заимствовать секции (особенно 8 «Querschnittliche Konzepte») без полного следования.
Diagrams by mingrammer Python-генерация диаграмм кода. Хорошо для cloud infra, но output — статичные PNG без DSL-source. Drift проблема хуже чем у Mermaid.

5. ADR tooling — отдельный вопрос🔗

Параллельно изучить codenamev/ai-software-architect (Claude Code plugin, декабрь 2025). Предоставляет slash commands: /setup-architect, /create-adr, /architecture-review. Потенциально полезен для стандартизации ADR format при росте до 5+ активных решений в Phase 3-4.

Статус: не изучали вплотную, отложено до Phase 3. Рассмотреть когда будем создавать первые формальные ADR (сейчас decisions живут в decisions-log-*.md в свободном формате).

6. Implementation plan (когда возвращаемся)🔗

Trigger: Phase 3 финал — reports/narodnaya/ стабилен, SocialScan adapter перенесён в src/, namespace finalised.

Шаг 1 — L1 Structurizr. Написать docs/architecture/workspace.dsl с C1 (system context: radar, SocialScan, Telegram, VK, штаб ЕР как user) + C2 (containers: app, scheduler, postgres, alerter, SocialScan API, candidate seed). Export PNG через: 

docker run -it --rm -p 8080:8080 -v $(pwd)/docs/architecture:/usr/local/structurizr structurizr/lite
Скачать PNG → docs/architecture/c4/system-context.png + c4/containers.png. Коммитить DSL + PNG вместе.

Шаг 2 — L2 Mermaid flows. Написать первые 4-5 диаграмм в docs/architecture/flows/: - narodnaya-cycle-flow.md — от SocialScan extract до CSV-рендера (flowchart, ~10 nodes) - ingestion-sequence.md — legacy TG/VK pipeline с cursor logic (sequence diagram) - schema-er.md — radar.* tables с FK (ER diagram, ~8 entities) - deploy-topology.md — VPS + Docker containers (architecture-beta) - ss-pipeline-state.md — state diagram cycle: fetch → classify → review → render

Шаг 3 — L3 pydeps. 

pydeps src/polit_media_radar --max-module-depth=3 --cluster -o docs/architecture/deps/module-deps.svg
Commit SVG. Дата генерации — в имени файла или frontmatter комментарии.

Шаг 4 — ai-software-architect. Установить plugin, запустить /setup-architect, оценить fit с текущим decisions-log форматом. Adopt или skip — решить на месте.

Не делаем pre-Phase 3 — структура не стабильна, любая диаграмма сейчас будет misleading через месяц.

7. Принцип: избегать documentation drift🔗

IcePanel State of Software Architecture Report 2025: «keeping documentation current» — challenge #1 industry-wide. Для solo + AI-agent контекста это особенно острая проблема: Claude Code обновляет код быстро, документацию — только если явно указано.

Митигации: - Минимум диаграмм — 5-7 ключевых, не 50 полных. Лучше 5 актуальных чем 20 устаревших. - Только нужный уровень абстракции — C1+C2, не C3/C4. - Правило Update-as-you-go: PR меняющий архитектурную границу (новый source, новый container, новый external dependency) обязан обновлять workspace.dsl и соответствующий Mermaid flow в том же PR. - Definition of Done для архитектурных PR включает: «diagram updated or N/A with reason».

Это не автоматизируется полностью — это культурное правило для Claude-агента в каждой сессии.

8. References🔗