Code repository documentation generation and architecture diagramming

Documentation is one of those tasks that developers perpetually defer. Your code repository grows, architectural patterns emerge, and suddenly you're staring at a README that hasn't been updated since 2019. The problem compounds when you need both written documentation and visual architecture diagrams. Maintaining these in sync requires constant manual effort, and by the time you finish writing one, the other is already out of date....... For more on this, see Technical architecture diagram generation from codebase d.... For more on this, see Technical specification document generation from business.... For more on this, see Architecture design document creation from code repositories.

The traditional workflow looks something like this: a developer reads the codebase, writes documentation manually (if they do at all), creates diagrams in a drawing tool, then watches both slowly drift from reality as the code evolves. Each step involves human time, context-switching, and the inevitable inconsistencies between what the docs say and what the code actually does.

What if instead you could run a single workflow that analyses your repository, generates accurate documentation automatically, and produces corresponding architecture diagrams, all without touching your code or manually coordinating between tools? This is possible now with the right combination of AI tools and orchestration.

The Automated Workflow

The workflow combines three specialist tools: bhava-ai for code analysis and understanding, mintlify for documentation generation and hosting, and windsurf for creating architecture diagrams from code structure. The orchestration layer ties everything together so that a single trigger produces fully generated documentation and diagrams.

Architecture Overview

The flow works like this:

1. Code repository trigger (GitHub webhook or scheduled check)

2. bhava-ai analyses the codebase structure and extracts context

3. Output feeds into mintlify, which generates formatted documentation

4. Simultaneously, architecture data flows to windsurf for diagram creation

5. Both outputs are committed back or published automatically

6. Notification confirms completion

Setting Up With n8n

n8n is the ideal choice here because it handles both sequential and parallel workflows, has excellent GitHub integration, and allows conditional routing based on code analysis results. Here's how to build it:

Step 1: GitHub Repository Trigger

Create a webhook that fires on repository updates or use a schedule:

Copy
POST https://your-n8n-instance.com/webhook/code-analysis

{
  "event": "push",
  "repository": "your-org/your-repo",
  "branch": "main"
}

In n8n, add a GitHub trigger node configured with:

Copy
Repository: your-org/your-repo
Events: Push, Pull Request
Branches: main

Alternatively, use a scheduled trigger if you prefer daily or weekly analysis runs:

Copy
Trigger type: Interval
Interval: Every day at 02:00 UTC

Step 2: Fetch Repository Contents

Before bhava-ai can analyse your code, you need to provide it with the repository structure and key files. Use the GitHub API to fetch this:

Copy
GET https://api.github.com/repos/{owner}/{repo}/contents

Authorization: Bearer {github_token}

In n8n, use the HTTP Request node:

Copy{
  "method": "GET",
  "url": "https://api.github.com/repos/your-org/your-repo/contents",
  "headers": {
    "Authorization": "Bearer {{ $secrets.github_token }}",
    "Accept": "application/vnd.github.v3.raw"
  }
}

This returns the file structure. You'll need to make additional requests to fetch the contents of important files like src/main.ts, package.json, architecture documentation files, and any existing README.

Step 3: Invoke bhava-ai for Code Analysis

bhava-ai excels at understanding code relationships and extracting architectural information. Set up an HTTP request to bhava-ai's analysis endpoint:

Copy
POST https://api.bhava-ai.com/v1/analyse-codebase

{
  "repository_url": "https://github.com/your-org/your-repo",
  "analysis_type": "full",
  "include_architecture": true,
  "include_dependencies": true,
  "output_format": "json"
}

In n8n, configure it like this:

Copy{
  "method": "POST",
  "url": "https://api.bhava-ai.com/v1/analyse-codebase",
  "headers": {
    "Authorization": "Bearer {{ $secrets.bhava_api_key }}",
    "Content-Type": "application/json"
  },
  "body": {
    "repository_url": "https://github.com/{{ $node['GitHub Trigger'].json.repository }}",
    "analysis_type": "full",
    "include_architecture": true,
    "include_dependencies": true,
    "commit_hash": "{{ $node['GitHub Trigger'].json.after }}"
  }
}

bhava-ai will return a detailed JSON object containing module relationships, dependency graphs, key functions and classes, and architectural patterns detected. This becomes the source of truth for both documentation and diagrams.

Step 4: Generate Documentation with mintlify

Mintlify's API accepts structured data and produces beautifully formatted documentation. Prepare the data from bhava-ai output:

Copy{
  "project_name": "your-project",
  "description": "{{ $node['bhava-ai Analysis'].json.project_summary }}",
  "modules": [
    {
      "name": "{{ module.name }}",
      "description": "{{ module.purpose }}",
      "files": ["{{ file.path }}"],
      "exports": ["{{ export.name }}"],
      "dependencies": ["{{ dep.name }}"]
    }
  ],
  "api_endpoints": [
    {
      "method": "GET",
      "path": "{{ endpoint.path }}",
      "description": "{{ endpoint.description }}",
      "parameters": ["{{ param.name }}"],
      "returns": "{{ endpoint.return_type }}"
    }
  ]
}

Call mintlify's documentation generation endpoint:

Copy
POST https://api.mintlify.com/v1/generate-docs

{
  "project_id": "your-project-id",
  "content": {...},
  "output_format": "markdown",
  "include_toc": true,
  "include_code_samples": true
}

In n8n:

Copy{
  "method": "POST",
  "url": "https://api.mintlify.com/v1/generate-docs",
  "headers": {
    "Authorization": "Bearer {{ $secrets.mintlify_api_key }}",
    "Content-Type": "application/json"
  },
  "body": {
    "project_id": "your-project-id",
    "content": {
      "project_name": "{{ $node['GitHub Trigger'].json.repository }}",
      "description": "{{ $node['bhava-ai Analysis'].json.summary }}",
      "modules": "{{ $node['bhava-ai Analysis'].json.modules }}",
      "api_endpoints": "{{ $node['bhava-ai Analysis'].json.endpoints }}"
    },
    "output_format": "markdown",
    "include_toc": true
  }
}

Step 5: Generate Architecture Diagrams with windsurf

In parallel with documentation generation, send the same bhava-ai analysis output to windsurf for diagram creation:

Copy
POST https://api.windsurf.ai/v1/generate-diagram

{
  "diagram_type": "architecture",
  "architecture_data": {...},
  "style": "c4_model",
  "output_format": "svg"
}

windsurf accepts architectural metadata and produces publication-ready diagrams. Configure it in n8n:

Copy{
  "method": "POST",
  "url": "https://api.windsurf.ai/v1/generate-diagram",
  "headers": {
    "Authorization": "Bearer {{ $secrets.windsurf_api_key }}",
    "Content-Type": "application/json"
  },
  "body": {
    "diagram_type": "architecture",
    "project_name": "{{ $node['GitHub Trigger'].json.repository }}",
    "architecture_data": {
      "components": "{{ $node['bhava-ai Analysis'].json.components }}",
      "relationships": "{{ $node['bhava-ai Analysis'].json.relationships }}",
      "external_systems": "{{ $node['bhava-ai Analysis'].json.external_dependencies }}"
    },
    "style": "c4_model",
    "output_format": "svg"
  }
}

You might generate multiple diagrams: a system context diagram, container diagram, and component diagrams at different levels of detail.

Step 6: Commit Results Back to Repository

Create a new branch, commit both the generated documentation and diagrams, then open a pull request:

Copy
POST https://api.github.com/repos/{owner}/{repo}/contents/{path}

{
  "message": "docs: auto-generated documentation and architecture diagrams",
  "content": "{base64_encoded_content}",
  "branch": "auto/docs-update-{timestamp}"
}

In n8n, use the GitHub node to create commits:

Copy{
  "resource": "file",
  "operation": "create",
  "repository": "your-org/your-repo",
  "filePath": "docs/architecture.md",
  "fileContent": "{{ $node['mintlify Documentation'].json.content }}",
  "commitMessage": "docs: auto-generated architecture documentation",
  "branch": "auto/docs-{{ Date.now() }}"
}

Repeat this for the SVG diagram files.

Step 7: Create Pull Request

Automatically open a PR for review:

Copy
POST https://api.github.com/repos/{owner}/{repo}/pulls

{
  "title": "chore: auto-generated documentation and diagrams",
  "body": "Updated by documentation pipeline. Review changes and merge if correct.",
  "head": "auto/docs-update-{timestamp}",
  "base": "main"
}

Step 8: Notification

Finally, send a notification (Slack, email, or GitHub comment) confirming the workflow completed:

Copy{
  "method": "POST",
  "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "body": {
    "text": "Documentation generation complete",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "Repository: {{ $node['GitHub Trigger'].json.repository }}\nPR: {{ $node['Create PR'].json.html_url }}\nDiagrams: {{ $node['windsurf Diagram'].json.diagram_url }}"
        }
      }
    ]
  }
}

The Manual Alternative

If you want more control over which files get analysed or need to exclude certain parts of your codebase, you can trigger each step manually through the respective tool dashboards. bhava-ai, mintlify, and windsurf all offer web interfaces where you can upload code, configure analysis parameters, and review outputs before committing them.

This approach is useful for one-off documentation of legacy systems or when you're first setting up the pipeline and want to verify that the outputs look correct before automating. You might also prefer manual triggering if you only document code periodically (quarterly releases, for example) rather than on every commit.

Simply run each tool individually, download the outputs, and commit them to your repository manually. This takes roughly 45 minutes to an hour compared to the instant, automated approach.

Pro Tips

Rate limiting and API quotas

bhava-ai, mintlify, and windsurf all have rate limits. If you're running this workflow daily, you'll consume API credits quickly. Configure n8n to batch requests: instead of analysing on every commit, run the full pipeline once per day or once per week. Add a rate-limit check in n8n using the "Limit" node to pause execution if you're approaching quota limits.

Copy{
  "node": "Limit",
  "maxRequests": 10,
  "timePeriod": "day",
  "action": "queue"
}

Error handling for incomplete analyses

Sometimes bhava-ai won't analyse your entire codebase correctly if it's very large or uses uncommon frameworks. Set up conditional logic in n8n to detect low confidence scores and flag those analyses for manual review:

Copy{
  "if": "{{ $node['bhava-ai Analysis'].json.confidence < 0.85 }}",
  "then": "notify-on-slack",
  "else": "proceed-to-mintlify"
}

Excluding sensitive files

Add a .docignore file to your repository root to exclude certain paths from analysis:

Copy
node_modules/
.env
config/secrets/
private/
vendor/
*.log

Configure bhava-ai to respect this file by passing it as a parameter in the API request.

Diagram customization by audience

Generate multiple diagrams for different stakeholders. Non-technical stakeholders benefit from high-level system diagrams, while engineers need detailed component views. Use windsurf's "audience" parameter to automatically adjust diagram detail:

Copy{
  "style": "c4_model",
  "audience": "executive",
  "abstraction_level": "high"
}

Then create a second request with "audience": "engineer" and "abstraction_level": "detailed".

Versioning and tracking changes

Store generated documentation alongside version tags. After generating docs, create a lightweight Git tag:

Copy
POST https://api.github.com/repos/{owner}/{repo}/git/tags

{
  "tag": "docs-v{{ $node['GitHub Trigger'].json.commit_sha.slice(0, 7) }}",
  "message": "Documentation for commit {{ $node['GitHub Trigger'].json.commit_sha }}"
}

This lets you track which documentation corresponds to which code state, useful for debugging or reviewing historical changes.

Cost Breakdown

If you run the workflow once per week instead of daily, costs drop to roughly £280 monthly. If you run it monthly, expect £200 to £250.

Self-hosting n8n reduces the monthly cost to just cloud infrastructure (roughly £40–60/month on a small VPS), bringing the total to around £280–300 monthly. However, self-hosting adds operational complexity.