AI-Powered Automatic Architecture Diagram Generation

AI-Powered Automatic Architecture Diagram Generation

Imagine opening your Confluence. The last architecture diagram is years old. New services have been added, old ones renamed. Dependencies are tangled. Onboarding a developer becomes a quest: read the code, guess the connections. Our engineers encountered this in every second project. We solved it once and for all: an AI system generates diagrams from code and infrastructure files. This is automatic code documentation, updated at every commit. The result — living documentation that always matches production. Experience shows: after deployment, onboarding time drops 3–5 times. Documentation budget savings reach 70%.

How AI Generates Diagrams from Code

The system analyzes the project on multiple levels. For Python code, it uses AST — extracting modules, imports, classes, HTTP clients. For infrastructure — parsing docker-compose.yml and Terraform. Then an LLM (Claude Sonnet 4.5) turns this into a Mermaid diagram. Here's the process step by step:

1. Scan repository: find all code and configuration files.
2. AST parse Python files: extract components and dependencies.
3. Parse docker-compose: identify services, networks, dependencies.
4. Parse Terraform: extract AWS/GCP resources and their relationships.
5. Aggregate data into a single JSON structure.
6. Send to LLM with a prompt for Mermaid generation.
7. Validate diagram syntax and save in docs/.

Example code for analyzing a Python project's structure (full code in repository):

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:
        """Analyze Python project structure via 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:
        """Generate Mermaid diagram via LLM"""
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4096,
            system="""You are an architect generating Mermaid diagrams.
Create only valid Mermaid syntax.
For C4 Context/Container diagrams:
- Group by layers: Frontend, API, Services, Database, External
- Show main interactions with arrows
- Don't overload — only key components
For Flow diagrams:
- Use flowchart TD (top-down)
- Show business process clearly""",
            messages=[{
                "role": "user",
                "content": f"""Create a {diagram_type} Mermaid diagram based on the project analysis.
Analysis:
{str(analysis)[:3000]}
Return only Mermaid code (starting with ```mermaid)."""
            }]
        )
        return response.content[0].text

Sequence and UML Diagram Generation

Beyond overall architecture, the system can build sequence diagrams for specific API endpoints and UML class diagrams from ORM models. For example, for SQLAlchemy models it creates an erDiagram with relationships, PK/FK, and field types. This is especially useful when reviewing database changes. The system supports C4 model, UML, infrastructure diagrams, and dependency graphs.

What Is Living Documentation and How Does It Work?

Living documentation is a set of diagrams that automatically updates with every change to code or infrastructure. It's stored in the repository alongside the code and published on internal wiki pages. The team always sees an up-to-date picture of the system without spending time on manual drawing. This eliminates outdated schematics and misunderstandings. Request a consultation to learn how to implement generation in your project.

Automatic Updates in CI/CD

We integrate a script into your pipeline that runs analysis and generation on every push to main. The result is PNG and Markdown files in the docs folder. Here's an example function for 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)

Practical Case: Documenting a Microservice Architecture

From our practice: a fintech startup with 12 microservices. The last architectural diagram was drawn years ago. Onboarding new developers: "look at the code, no other sources." We implemented generation:

• Analyzed docker-compose.yml and Terraform
• Generated C4 Context, Container, Infrastructure, and ER diagrams
• Integrated into GitHub Actions — update on push to main

Results:

• Onboarding time (understanding architecture) — from 2 weeks to 3 days
• Diagrams 100% current — generated at every PR
• Discovered 3 circular dependencies between services that went unnoticed for years

Comparison: AI Generation vs Manual Drawing

AI generation is 60x faster than manual drawing. Accuracy against code reaches 95% vs 40% for manual updates. Documentation budget savings up to 70%.

Types of Generated Diagrams

What's Included

• Analysis of codebase and infrastructure files
• Generation of 5+ diagram types (C4, ER, sequence, infrastructure, dependency graph)
• CI/CD integration (GitHub Actions, GitLab CI, Bitbucket Pipelines)
• Publishing to Confluence, Notion, or GitHub Pages
• Documentation of the process and scripts for self-service
• Team training (1–2 hours)

Timelines

• Generation for one diagram type (docker-compose or models): 1–2 days
• Full set from codebase: 3–5 days
• CI/CD integration with auto-update: 1 week
• Confluence/Notion publishing: +2–3 days

Implementation cost is calculated individually based on codebase size. Order an audit of your current documentation — we'll assess the project in 1 day. Get a consultation to discuss your architecture. We guarantee that after implementation, diagrams will always reflect reality.

LLM Development: Fine-Tuning, RAG, Agents, and Production Deployment

Using GPT‑4 or Claude 3.5 Sonnet through a public API is not a solution — it's just a tool. When the requirement is to "make it like ChatGPT, but on our data," there is a real engineering challenge behind it: from prompt engineering to training a 70B model on your own infrastructure. End-to-end LLM solution development is a complex stack, and we have been doing it for over 5 years. During this time, we have completed over 20 projects in generative AI: from RAG systems for legal departments to custom support agents. Where exactly your task falls depends on data, latency requirements, budget, and how critical confidentiality is.

A typical situation: the client has already tried ChatGPT, but results are unstable — sometimes accurate, sometimes hallucinating. Or they need integration into a corporate portal while complying with security policies. Let's break down each layer of the stack in detail — from RAG to production deployment.

Why Do RAG Systems Break and How to Fix It?

RAG (Retrieval-Augmented Generation) looks simple: find relevant documents, put them in context, get an answer. In practice, it fails in several places.

Chunking without overlap. Classic mistake: chunk_size=512, overlap=0. If the answer lies across two chunks, retrieval won't find either with sufficient confidence. Solution: overlap 15–25% of chunk_size, or better yet, sentence-aware splitting with spaCy or NLTK instead of naive character splitting.

Poor embedder. text-embedding-ada-002 is good for general use, but on legal or medical texts, specialized models like E5-large-v2, BGE-M3, or fine-tuned sentence-transformers on domain data outperform it. Recall@5 differences can be 15–25%.

No re-ranking. Vector search optimizes for speed, not relevance. A cross-encoder re-ranker (ms-marco-MiniLM-L-6-v2, bge-reranker-large) after initial retrieval improves top-3 accuracy with acceptable latency (+50–150ms). This is often more impactful than improving the embedding model.

Hybrid search. Dense vectors alone work poorly on exact queries: names, SKUs, codes. BM25 (sparse) finds exact matches but misses semantics. Hybrid via RRF (Reciprocal Rank Fusion) is the optimal compromise. Qdrant, Weaviate, and pgvector 0.7+ support hybrid search natively.

When to Fine-Tune Instead of Prompt Engineering?

Prompt engineering solves ~70% of LLM adaptation tasks for a domain. The remaining 30% require fine-tuning. Three indicators: the model ignores a specific output format even with detailed prompting; the task requires deep knowledge of specialized vocabulary (medicine, law); you need to significantly reduce token costs by replacing a large model with a smaller specialized one.

LoRA and QLoRA are the standard for SFT. LoRA adds trainable low-rank matrices to attention layers. A typical configuration for Llama-3 8B: r=64, lora_alpha=128, target_modules=["q_proj","v_proj","k_proj","o_proj"] yields ~0.8% trainable parameters, training on one A100 40GB. QLoRA adds 4-bit quantization (NF4) and allows fine-tuning 70B models on two A100 40GB, though speed drops by half compared to bf16.

DPO instead of RLHF. Direct Preference Optimization requires only (chosen, rejected) pairs, not scalar reward signals. DPOTrainer from the trl library (Hugging Face) implements it in a few dozen lines.

Common mistake. A dataset of 500 examples, 5 epochs, validation loss 0.8 — seems fine. But on test, the model degrades on general instructions. Cause: catastrophic forgetting. Solution: add 10–20% general instruction-following examples (Alpaca, FLAN) to the training set to preserve original capabilities.

How to Choose a Base Model: 8B or 70B?

For most tasks, fine-tuning an 8B model is sufficient. 70B is needed when deep reasoning is required or the 8B baseline does not reach the required quality even after fine-tuning. Inference cost for Llama-3 8B via vLLM on A100 is efficient; the exact cost depends on volume.

What Does PagedAttention Bring to Production?

vLLM is the first choice for serving open-source models. PagedAttention is the key technical innovation: KV-cache is managed like virtual memory in an OS, without fragmentation. This yields 2–4x higher throughput compared to naive HuggingFace Transformers inference. The vLLM documentation confirms that continuous batching and PagedAttention are the standard for high-load LLM services.

Typical numbers on A100 80GB for Llama-3 8B (bf16): 400–600 req/s, P50 latency 200–400ms, P99 latency 600–900ms at concurrency 64. For 70B on two A100 with tensor parallelism: 80–120 req/s, P99 latency 1.5–2.5s. AWQ or GPTQ quantization reduces memory consumption by 2x with quality loss within 1–3%.

Multi-Agent Systems

Agents are LLMs with access to tools: search, code execution, API calls, database interaction. Common patterns:

• ReAct (Reason + Act): the model reasons → chooses a tool → observes the result → reasons again. LangChain and LlamaIndex implement it out of the box.
• Multi-agent orchestration: multiple specialized agents with a coordinator on top. Example: coordinator → researcher (search + summarization) → coder (code generation and execution) → critic (verification). Tools: AutoGen (Microsoft), CrewAI, custom implementation on LangGraph.

In production, agent systems are non-deterministic. Essential: guardrails, step limits, logging of each step, human-in-the-loop for critical actions.

How We Work: Stages, Timeline, Deliverables

What Is Included

We deliver:

• Technical documentation (model card, configs, deployment instructions)
• Access to infrastructure (code repository, trained weights)
• 1 month of post-deployment support (consultations, bug fixes)
• Customer team training (2–3 sessions on system operation)

Timeline: basic RAG prototype — 1–2 weeks. Fine-tuning with customer data — 3–6 weeks (including data preparation). Production system with monitoring and retraining — 2–4 months. Cost is calculated individually based on data volume, model complexity, and infrastructure requirements.

We guarantee the quality of the final model with performance benchmarks and ongoing monitoring. Our engineers have hands‑on experience with dozens of production LLM systems.

Want to evaluate your project? Leave a request — we will prepare a preliminary summary within 1–2 business days. Or get a consultation on choosing the approach: RAG, fine-tuning, or hybrid — we will tell you what works best for you. Contact us to discuss your LLM development needs. Schedule a free consultation today.