Разработка 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 день. Получите консультацию, чтобы обсудить вашу архитектуру. Гарантируем, что после внедрения диаграммы всегда будут отражать реальность.