יצירת דיאגרמות ארכיטקטורה אוטומטית מבוססת AI

יצירת דיאגרמות ארכיטקטורה אוטומטיות מבוססות AI

תארו לעצמכם שפותחים את Confluence. דיאגרמת הארכיטקטורה האחרונה בת שנים. נוספו שירותים חדשים, ישנים שונו שמות. התלויות מסובכות. קליטת מפתח חדש הופכת למסע: לקרוא את הקוד, לנחש את החיבורים. המהנדסים שלנו נתקלו בזה בכל פרויקט שני. פתרנו את זה אחת ולתמיד: מערכת AI מייצרת דיאגרמות מקוד ומקבצי תשתית. זהו תיעוד קוד אוטומטי, שמתעדכן בכל commit. התוצאה — תיעוד חי שתמיד תואם לייצור. הניסיון מראה: לאחר ההטמעה, זמן הקליטה יורד פי 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 עם prompt ליצירת 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

יצירת דיאגרמות Sequence ו-UML

מעבר לארכיטקטורה הכללית, המערכת יכולה לבנות דיאגרמות sequence עבור נקודות קצה ספציפיות של API ודיאגרמות מחלקות UML ממודלי ORM. לדוגמה, עבור מודלי SQLAlchemy היא יוצרת erDiagram עם יחסים, PK/FK וסוגי שדות. זה שימושי במיוחד בעת סקירת שינויים במסד הנתונים. המערכת תומכת במודל C4, UML, דיאגרמות תשתית וגרפי תלויות.

מה זה תיעוד חי וכיצד הוא עובד?

תיעוד חי הוא קבוצת דיאגרמות שמתעדכנת אוטומטית עם כל שינוי בקוד או בתשתית. הוא מאוחסן במאגר לצד הקוד ומתפרסם בדפי wiki פנימיים. הצוות תמיד רואה תמונה עדכנית של המערכת ללא בזבוז זמן על ציור ידני. זה מבטל סכמות מיושנות ואי-הבנות. בקשו ייעוץ כדי ללמוד כיצד ליישם יצירה בפרויקט שלכם.

עדכונים אוטומטיים ב-CI/CD

אנו משלבים סקריפט ב-pipeline שלכם שמבצע ניתוח ויצירה בכל 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

תוצאות:

• זמן קליטה (הבנת הארכיטקטורה) — משבועיים ל-3 ימים
• דיאגרמות עדכניות ב-100% — נוצרות בכל PR
• גילינו 3 תלויות מעגליות בין שירותים שלא הבחינו בהן במשך שנים

השוואה: יצירת AI מול ציור ידני

יצירת AI מהירה פי 60 מציור ידני. הדיוק מול הקוד מגיע ל-95% לעומת 40% בעדכונים ידניים. החיסכון בתקציב התיעוד עד 70%.

סוגי דיאגרמות שנוצרות

מה כלול

• ניתוח קוד וקבצי תשתית
• יצירת 5+ סוגי דיאגרמות (C4, ER, sequence, infrastructure, dependency graph)
• שילוב CI/CD (GitHub Actions, GitLab CI, Bitbucket Pipelines)
• פרסום ל-Confluence, Notion או GitHub Pages
• תיעוד התהליך והסקריפטים לשימוש עצמי
• הדרכת צוות (1–2 שעות)

לוחות זמנים

• יצירה לסוג דיאגרמה אחד (docker-compose או מודלים): 1–2 ימים
• סט מלא מהקוד: 3–5 ימים
• שילוב CI/CD עם עדכון אוטומטי: שבוע
• פרסום ל-Confluence/Notion: +2–3 ימים

עלות ההטמעה מחושבת באופן אישי לפי גודל הקוד. הזמינו ביקורת על התיעוד הנוכחי שלכם — נעריך את הפרויקט תוך יום. קבלו ייעוץ כדי לדון בארכיטקטורה שלכם. אנו מבטיחים שאחרי ההטמעה, הדיאגרמות תמיד ישקפו את המציאות.