Technical architecture diagram generation from codebase documentation

Documentation sprawl is a real problem in software development. You write code, you generate documentation, but somewhere between your codebase and your architecture diagrams, the connection breaks. Teams end up maintaining diagrams manually in Figma or draw.io, updating them sporadically whenever the code changes. The result: diagrams that are three sprints out of date, inconsistent with reality, and utterly useless for onboarding or compliance reviews. For more on this, see Architecture design document creation from code repositories.

There's a better way. By combining bhava-ai to extract structure from your documentation, chat-with-pdf-by-copilotus to analyse your existing technical docs, and Mintlify to generate clean, structured diagrams, you can automate the entire pipeline. With an orchestration layer like n8n or Zapier, you can trigger this workflow whenever documentation updates, producing fresh architecture diagrams with zero manual intervention. For more on this, see Technical specification document generation from business....

This workflow is particularly valuable for teams shipping microservices, API-heavy applications, or complex distributed systems where architecture diagrams become stale within weeks. It's also useful for compliance-heavy industries where you need consistent, auditable documentation trails. Let's build it.

The Automated Workflow

We're going to wire three tools together to create a diagram-generation pipeline. The flow is straightforward: pull documentation from your repository, analyse it for architectural patterns, generate a structured representation, then output an architecture diagram....... For more on this, see Code repository documentation generation and architecture....

Understanding the Data Flow

The workflow operates in four stages:

1. Trigger: Documentation file changes in your repository
2. Extract: bhava-ai reads and extracts architectural metadata from your docs
3. Analyse: chat-with-pdf-by-copilotus comprehends relationships and dependencies
4. Generate: Mintlify produces a formatted diagram file

This is an intermediate workflow because you'll need to configure webhooks, handle JSON payloads, and potentially transform data between tools. If you've used Zapier or n8n before, you'll find this familiar; if not, expect to spend 30 minutes understanding how each step chains together.

Setting Up n8n (Recommended Approach)

We'll use n8n as the orchestration layer because it provides better flexibility than Zapier for API chaining, and it's simpler than Make for this particular use case. n8n also lets you host it yourself or use their cloud service.

Start by creating a new workflow in n8n. Your first node will be a webhook trigger.

Copy
POST /webhook/docs-updated
Content-Type: application/json

{
  "repository": "myproject",
  "doc_path": "/docs/architecture.md",
  "timestamp": "2024-01-15T10:30:00Z"
}

This webhook receives a payload whenever documentation changes. You can trigger it manually, or integrate it with a GitHub Actions workflow that fires whenever someone merges to main.

The GitHub Actions part (optional but recommended) looks like this:

Copyname: Trigger Architecture Diagram
on:
  push:
    paths:
      - 'docs/**'
    branches:
      - main

jobs:
  trigger-n8n:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger n8n workflow
        run: |
          curl -X POST https://your-n8n-instance.com/webhook/docs-updated \
            -H "Content-Type: application/json" \
            -d '{
              "repository": "'${{ github.repository }}'",
              "doc_path": "'${{ github.event.head_commit.modified[0] }}'",
              "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
            }'

Once the webhook receives the trigger, your n8n workflow moves to the next node: fetching the documentation file.

Node 2:

Fetch Documentation

Add an HTTP Request node to pull the actual documentation file from your repository.

Copy
GET https://raw.githubusercontent.com/your-org/your-repo/main/docs/architecture.md
Authorization: Bearer {{ env.GITHUB_TOKEN }}

This returns the raw markdown content. Store it in a variable called doc_content for the next step.

Node 3:

Extract Metadata with bhava-ai

bhava-ai is purpose-built for pulling structured data from unstructured documents. You'll need an API key from bhava-ai; sign up at their dashboard and generate credentials.

The bhava-ai endpoint for extraction:

Copy
POST https://api.bhava-ai.com/v1/extract
Authorization: Bearer {{ env.BHAVA_API_KEY }}
Content-Type: application/json

{
  "document": {{ $node["HTTP Request"].data.content }},
  "schema": {
    "components": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "type": { "type": "string", "enum": ["service", "database", "queue", "cache", "external"] },
          "language": { "type": "string" }
        }
      }
    },
    "connections": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "source": { "type": "string" },
          "target": { "type": "string" },
          "protocol": { "type": "string" }
        }
      }
    },
    "external_integrations": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

bhava-ai will parse your markdown documentation and return structured JSON with identified services, databases, message queues, and their relationships. This is the heavy lifting of the workflow; the AI understands context like "the API Gateway routes requests to the User Service via gRPC" and extracts that as a typed connection.

Store the output as extracted_architecture.

Node 4:

Analyse with Chat-with-PDF-by-Copilotus

This step feels redundant at first, but it serves a crucial purpose: validation and enrichment. Chat-with-PDF-by-copilotus can answer detailed questions about the documentation, filling in gaps that the schema-based extraction might miss.

Create a Chat node that references the original documentation:

Copy
POST https://api.chat-with-pdf.copilotus.io/v1/chat
Authorization: Bearer {{ env.COPILOTUS_API_KEY }}
Content-Type: application/json

{
  "document_id": "arch-doc-{{ $node.Webhook.data.repository }}",
  "document_content": {{ $node["HTTP Request"].data.content }},
  "question": "What are all the system dependencies, external APIs, and data stores mentioned in this architecture document? List them with their communication protocols."
}

The API returns a formatted answer that captures nuances the extraction step might miss. You now have both structured data and a semantic understanding of your architecture.

Node 5:

Transform and Merge Data

Add a Function node to combine the structured extraction with the semantic analysis:

Copyconst extracted = $node["bhava extraction"].data;
const analysis = $node["chat analysis"].data.answer;

const merged = {
  components: extracted.components,
  connections: extracted.connections,
  external_integrations: extracted.external_integrations,
  semantic_summary: analysis,
  generated_at: new Date().toISOString(),
  source_doc: $node.Webhook.data.doc_path
};

return { architecture_data: merged };

This consolidated object becomes your source of truth for diagram generation.

Node 6:

Generate Diagram with Mintlify

Mintlify is typically known as documentation-as-code, but its API can also generate architecture diagrams from structured data. You'll format your architecture data into Mintlify's expected schema:

Copy
POST https://api.mintlify.com/v1/diagrams/generate
Authorization: Bearer {{ env.MINTLIFY_API_KEY }}
Content-Type: application/json

{
  "title": "Architecture Diagram - {{ $node.Webhook.data.repository }}",
  "diagram_type": "architecture",
  "nodes": {{ $node["Transform"].data.architecture_data.components.map(c => ({
    "id": c.name.toLowerCase().replace(/\s+/g, "-"),
    "label": c.name,
    "type": c.type,
    "description": c.description
  })) }},
  "edges": {{ $node["Transform"].data.architecture_data.connections.map(conn => ({
    "source": conn.source.toLowerCase().replace(/\s+/g, "-"),
    "target": conn.target.toLowerCase().replace(/\s+/g, "-"),
    "label": conn.protocol
  })) }},
  "style": {
    "theme": "modern",
    "layout": "hierarchical"
  }
}

Mintlify returns a URL to your generated diagram, plus the diagram file itself.

Node 7:

Commit Back to Repository

Finally, save the generated diagram to your repository so it's version-controlled alongside your documentation:

Copy
POST https://api.github.com/repos/your-org/your-repo/contents/docs/architecture-diagram.svg
Authorization: Bearer {{ env.GITHUB_TOKEN }}
Content-Type: application/json

{
  "message": "Auto-generated architecture diagram from documentation [skip ci]",
  "content": {{ Buffer.from($node["Mintlify"].data.svg_content).toString("base64") }},
  "branch": "main",
  "committer": {
    "name": "Architecture Bot",
    "email": "bot@yourcompany.com"
  }
}

Add the [skip ci] flag to prevent an infinite loop of workflow triggers.

That's your complete workflow. When someone updates docs/architecture.md and pushes to main, the diagram regenerates automatically within two minutes. The diagram file lives in version control, so you can track how your architecture has changed over time.

The Manual Alternative

If you prefer not to automate this or need one-time diagram generation, you can run each step manually:

1. Export your documentation as a PDF from your wiki or repository.
2. Upload the PDF to chat-with-pdf-by-copilotus and ask it to identify all system components and their relationships.
3. Take the analysis output and manually create a structured JSON file matching bhava-ai's schema.
4. Use Mintlify's web interface to paste in your structured data and generate the diagram visually.
5. Download the SVG or PNG and commit it to your repository.

This takes about 20 minutes per diagram and requires human interpretation at each step. It's useful for one-off diagrams or when you want to hand-tune specific layout decisions. However, if you're updating diagrams more than once a month, the automated approach pays for itself immediately in time savings.

Pro Tips

Error handling in the extraction step. bhava-ai occasionally misses components if your documentation uses abbreviations or inconsistent naming. Add a validation node that checks whether the extracted components match the list provided by chat-with-pdf-by-copilotus. If the counts differ significantly (say, more than 20 percent), log a warning and notify Slack rather than silently generating an incomplete diagram.

Copyconst extractedCount = $node["bhava extraction"].data.components.length;
const analyzedCount = ($node["chat analysis"].data.answer.match(/\b(service|database|queue|api|cache)\b/gi) || []).length;

if (Math.abs(extractedCount - analyzedCount) / analyzedCount > 0.2) {
  return {
    warning: true,
    message: `Extracted ${extractedCount} components but analysis suggests ~${analyzedCount}. Review manually.`,
    should_notify_slack: true
  };
}

Rate limits on Mintlify. Their API allows 100 requests per month on the free plan and 1000 on paid plans. For teams generating diagrams more than twice a week, budget for the paid tier or implement caching logic that only regenerates diagrams if the architecture data has actually changed. Compare the current extraction with the previous one using a hash:

Copyconst crypto = require("crypto");
const current_hash = crypto.createHash("sha256")
  .update(JSON.stringify($node["Transform"].data.architecture_data))
  .digest("hex");

return { architecture_changed: current_hash !== previousHash };

Cost management with bhava-ai. bhava-ai charges per extraction API call, not per document size. A typical architecture document (2000 words) costs about £0.02 to extract. If you're documenting multiple services or running this for several repositories, costs add up. Set a budget alert in their dashboard and review monthly usage patterns to understand whether you need to optimise how often diagrams regenerate.

GitHub Actions context. If you're running the webhook trigger from GitHub Actions, make sure your GitHub token has contents: write permission. If you're working in a private repository, also ensure the n8n instance has network access to GitHub's API, which it should if you're hosting n8n in the cloud. For self-hosted n8n, you may need to whitelist GitHub's IP ranges.

Formatting edge cases. Mintlify sometimes struggles with very large diagrams (30+ nodes). If your architecture exceeds this, consider splitting the diagram into subsystem views. Modify the transformation node to detect node count and filter by component type:

Copyconst all_components = $node["Transform"].data.architecture_data.components;
if (all_components.length > 30) {
  return {
    split_required: true,
    services: all_components.filter(c => c.type === "service"),
    data_layer: all_components.filter(c => ["database", "cache", "queue"].includes(c.type)),
    external: all_components.filter(c => c.type === "external")
  };
}

This generates three focused diagrams instead of one overwhelming diagram.

Cost Breakdown

For most teams, the free tier combination covers typical usage patterns. Only scale to paid plans if you're generating diagrams multiple times daily or have strict rate-limit requirements.