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

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

Архітектурні діаграми застарівають майже одразу після створення: розробники додають нові сервіси, змінюють взаємодії, а діаграми в Confluence ніхто не оновлює. AI-генерація діаграм з коду та інфраструктурних файлів вирішує проблему "живої документації" — діаграма генерується автоматично при кожній зміні.

Генерація з кодової бази

from anthropic import Anthropic
from pathlib import Path
import ast
import re
import subprocess

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,
                        })

                # HTTP клієнти (requests, httpx)
                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 діаграму"""

        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

    def generate_from_docker_compose(self, compose_file: str) -> str:
        """Генерує діаграму з docker-compose.yml"""
        import yaml

        with open(compose_file) as f:
            compose = yaml.safe_load(f)

        services = compose.get("services", {})
        networks = compose.get("networks", {})

        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=2048,
            messages=[{
                "role": "user",
                "content": f"""Створи Mermaid архітектурну діаграму з docker-compose.

Сервіси:
{str(services)[:2000]}

Мережі:
{str(networks)}

Покажи:
- Кожен сервіс як блок з назвою та image
- Залежності (depends_on) як стрілки
- Порти як позначки на блоках
- Спільні мережі як групи

Поверни тільки Mermaid код."""
            }]
        )

        return response.content[0].text

    def generate_from_terraform(self, tf_dir: str) -> str:
        """Генерує AWS/GCP архітектурну діаграму з Terraform"""

        # Читаємо всі .tf файли
        tf_content = ""
        for tf_file in Path(tf_dir).glob("*.tf"):
            tf_content += tf_file.read_text() + "\n\n"

        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4096,
            messages=[{
                "role": "user",
                "content": f"""Створи Mermaid діаграму інфраструктури з Terraform коду.

Terraform:
```hcl
{tf_content[:4000]}

Покажи:

• VPC/мережі як контейнери
• EC2/ECS/Lambda як прямокутники
• RDS/ElastiCache як циліндри (або бази даних)
• ALB/API Gateway як ромби
• Стрілки = трафік/взаємодії

Формат: Mermaid flowchart LR.""" }] )

    return response.content[0].text

### Генерація діаграм послідовності

```python
def generate_sequence_diagram(endpoint_source: str, service_name: str) -> str:
    """Генерує sequence diagram з коду обробника endpoint"""

    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=2048,
        messages=[{
            "role": "user",
            "content": f"""Створи Mermaid sequence diagram для цього API endpoint.

Код ({service_name}):
```python
{endpoint_source}

Покажи:

• Учасників: Client, API, кожен зовнішній сервіс/БД
• Все виклики в правильному порядку
• Async виклики (якщо є) з паралельними стрілками
• Умовні гілки через alt/opt

Поверни тільки Mermaid код.""" }] )

return response.content[0].text

def generate_er_diagram(models_source: str) -> str: """Генерує ER-діаграму з SQLAlchemy моделей"""

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=2048,
    messages=[{
        "role": "user",
        "content": f"""Створи Mermaid ER діаграму з SQLAlchemy моделей.

{models_source}

Покажи всі таблиці з:

• Полями та типами
• PK/FK маркерами
• Зв'язками (один-до-одного, один-до-багатьох, багато-до-багатьох)

Використовуй синтаксис: erDiagram""" }] )

return response.content[0].text

### Автоматичне оновлення в CI/CD

```python
import subprocess
from pathlib import Path

def update_diagrams_on_push(project_root: str, docs_dir: str):
    """Оновлює діаграми при кожному push"""

    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 ""
        ),
    }

    # docker-compose якщо є
    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)

    # Рендеримо PNG через mmdc (mermaid-cli)
    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 мікросервісів, остання архітектурна діаграма намальована 2 роки назад. Онбординг нових розробників: "дивіться в код, інших джерел немає".

Впровадження:

• Аналіз всіх docker-compose.yml та terraform файлів
• Генерація 4 діаграм: C4 Context, Container, Infrastructure, ER
• Інтеграція GitHub Actions: оновлення при push в main

Результати:

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

Типи генеруємих діаграм:

Терміни

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