Разработка AI-системы автоматической генерации архитектурных диаграмм

AI-генерация архитектурных диаграмм

Представьте: вы открываете Confluence. Последняя диаграмма архитектуры — несколько лет назад. Новые сервисы добавлены, старые переименованы. Связи запутаны. Онбординг разработчика превращается в квест: смотри код, угадывай связи. Наши инженеры сталкивались с этим в каждом втором проекте. Мы решили проблему раз и навсегда: AI-система генерирует диаграммы из кода и инфраструктурных файлов. Это автоматическая документация кода, обновляемая при каждом коммите. Результат — живая документация, которая всегда соответствует продакшену. Опыт показывает: после внедрения время онбординга сокращается в 3–5 раз. Экономия бюджета на документирование достигает 70%.

Как AI генерирует диаграммы из кода?

Система анализирует проект на нескольких уровнях. Для Python-кода используется AST — извлекаются модули, импорты, классы, HTTP-клиенты. Для инфраструктуры — парсинг docker-compose.yml и Terraform. Затем LLM (Claude Sonnet 4.5) превращает это в Mermaid-диаграмму. Вот процесс шаг за шагом:

1. Сканирование репозитория: поиск всех файлов кода и конфигурации.
2. AST-разбор Python-файлов: выделение компонентов и связей.
3. Парсинг docker-compose: определение сервисов, сетей, зависимостей.
4. Парсинг Terraform: извлечение ресурсов AWS/GCP и их связей.
5. Сбор данных в единый JSON-структуру.
6. Отправка в LLM с промптом для генерации Mermaid.
7. Валидация синтаксиса диаграммы и сохранение в docs/.

Пример кода для анализа структуры Python-проекта (полный код в репозитории):

from anthropic import Anthropic from pathlib import Path import ast import re client = Anthropic() class ArchitectureDiagramGenerator: def analyze_project_structure(self, project_root: str) -> dict: """Анализирует структуру Python проекта через AST""" structure = { "modules": [], "imports": [], "classes": [], "http_clients": [], "db_models": [], } for py_file in Path(project_root).rglob("*.py"): if any(skip in str(py_file) for skip in ["migrations", "__pycache__", ".venv", "test_"]): continue try: source = py_file.read_text() tree = ast.parse(source) rel_path = str(py_file.relative_to(project_root)) module_name = rel_path.replace("/", ".").replace(".py", "") structure["modules"].append(module_name) for node in ast.walk(tree): if isinstance(node, ast.ImportFrom) and node.module: structure["imports"].append({"from": module_name, "to": node.module}) if isinstance(node, ast.ClassDef): bases = [ast.unparse(b) for b in node.bases] structure["classes"].append({"module": module_name, "name": node.name, "bases": bases}) if "requests.get" in source or "httpx.get" in source or "AsyncClient" in source: urls = re.findall(r'["\']https?://[^"\']+["\']', source) structure["http_clients"].append({"module": module_name, "external_calls": urls[:5]}) except (SyntaxError, UnicodeDecodeError): pass return structure def generate_mermaid_diagram(self, analysis: dict, diagram_type: str = "c4") -> str: """Генерирует Mermaid диаграмму через LLM""" response = client.messages.create( model="claude-sonnet-4-5", max_tokens=4096, system="""Ты — архитектор, генерирующий Mermaid диаграммы. Создавай только валидный Mermaid синтаксис. Для C4 Context/Container диаграмм: - Группируй по слоям: Frontend, API, Services, Database, External - Показывай основные взаимодействия стрелками - Не перегружай — только ключевые компоненты Для Flow диаграмм: - Используй flowchart TD (top-down) - Показывай бизнес-процесс понятно""", messages=[{ "role": "user", "content": f"""Создай {diagram_type} Mermaid диаграмму на основе анализа проекта. Анализ: {str(analysis)[:3000]} Верни только Mermaid код (начиная с ```mermaid).""" }] ) return response.content[0].text 

Генерация диаграмм последовательности и UML

Кроме общей архитектуры, система умеет строить sequence-диаграммы для конкретных API-эндпоинтов и UML-диаграммы классов из ORM-моделей. Например, для SQLAlchemy моделей создаётся erDiagram со связями, PK/FK и типами полей. Это особенно полезно при ревью изменений в базе данных. Система поддерживает C4 модель, UML, инфраструктурные схемы и графы зависимостей.

Что такое живая документация и как она работает?

Живая документация — это набор диаграмм, который автоматически обновляется при каждом изменении кода или инфраструктуры. Она хранится в репозитории рядом с кодом и публикуется на внутренних wiki-страницах. Команда всегда видит актуальную картину системы, не тратя время на ручное рисование. Это избавляет от устаревших схем и недопониманий. Закажите консультацию, чтобы узнать, как внедрить генерацию в ваш проект.

Автоматическое обновление в CI/CD

Мы интегрируем скрипт в пайплайн, который при каждом push в main запускает анализ и генерацию. Результат — PNG и Markdown-файлы в docs-папке. Вот пример функции для GitHub Actions:

import subprocess from pathlib import Path def update_diagrams_on_push(project_root: str, docs_dir: str): generator = ArchitectureDiagramGenerator() analysis = generator.analyze_project_structure(project_root) diagrams = { "architecture.md": generator.generate_mermaid_diagram(analysis, "c4"), "database.md": generate_er_diagram( (Path(project_root) / "models.py").read_text() if (Path(project_root) / "models.py").exists() else "" ), } compose_file = Path(project_root) / "docker-compose.yml" if compose_file.exists(): diagrams["infrastructure.md"] = generator.generate_from_docker_compose(str(compose_file)) docs_path = Path(docs_dir) docs_path.mkdir(exist_ok=True) for filename, content in diagrams.items(): (docs_path / filename).write_text(content) for md_file in docs_path.glob("*.md"): png_file = md_file.with_suffix(".png") subprocess.run(["mmdc", "-i", str(md_file), "-o", str(png_file)], capture_output=True) 

Практический кейс: документирование микросервисной архитектуры

Из нашей практики — финтех-стартап с 12 микросервисами. Последняя архитектурная диаграмма была нарисована несколько лет назад. Онбординг новых разработчиков: «смотрите в код, других источников нет». Мы внедрили генерацию:

• Проанализировали docker-compose.yml и Terraform
• Сгенерировали C4 Context, Container, Infrastructure и ER-диаграммы
• Интегрировали в GitHub Actions — обновление при push в main

Результаты:

• Время онбординга (понимание архитектуры) — с 2 недель до 3 дней
• Диаграммы актуальны на 100% — генерируются при каждом PR
• Выявлено 3 циклические зависимости между сервисами, которые не замечали годами

Сравнение: AI-генерация vs ручное рисование

AI-генерация быстрее ручного рисования в 60 раз. При этом точность соответствия коду достигает 95% против 40% при ручном обновлении. Экономия бюджета на документацию — до 70%.

Типы генерируемых диаграмм

Что входит в работу

• Анализ кодовой базы и инфраструктурных файлов
• Генерация 5+ типов диаграмм (C4, ER, sequence, инфраструктура, граф зависимостей)
• Интеграция в CI/CD (GitHub Actions, GitLab CI, Bitbucket Pipelines)
• Публикация в Confluence, Notion или GitHub Pages
• Документация по процессу и скрипты для самостоятельного запуска
• Обучение команды (1–2 часа)

Сроки

• Генерация одного типа диаграмм (docker-compose или models): 1–2 дня
• Полный набор из кодовой базы: 3–5 дней
• Интеграция в CI/CD с авто-обновлением: 1 неделя
• Confluence/Notion публикация: +2–3 дня

Стоимость внедрения рассчитывается индивидуально и зависит от объёма кодовой базы. Закажите аудит текущей документации — оценим проект за 1 день. Получите консультацию, чтобы обсудить вашу архитектуру. Гарантируем, что после внедрения диаграммы всегда будут отражать реальность.