Architecture design document creation from code repositories

Creating and maintaining architecture design documents for software projects is tedious work. Engineers spend hours extracting information from code repositories, writing descriptions of components, and formatting diagrams. When codebases change, documents fall out of sync within weeks. The result is either stale documentation that nobody trusts, or constant manual updates that drain engineering time.... For more on this, see Technical architecture diagram generation from codebase d.... For more on this, see Code repository documentation generation and architecture.... For more on this, see Code migration documentation and technical debt assessment.

This workflow automates the entire process. You'll extract code structure, generate documentation automatically, and create professional architecture diagrams from a repository, all without touching a single file manually. The output flows directly into your documentation system, whether that's a wiki, knowledge base, or design repository. When code changes, you can re-run the workflow and regenerate documents in minutes.

The three tools here solve different parts of the problem. SourceAI reads your codebase and understands its structure. Mintlify formats that understanding into clean, readable documentation. Bhava-AI creates visual architecture diagrams that match your code's actual organisation. An orchestration tool connects them so data flows from one to the next without any manual intervention.

The Automated Workflow

Choosing Your Orchestration Tool

For this workflow, I recommend n8n if you're self-hosting or want full control, or Make (Integromat) if you prefer a managed service. Both handle complex data transformations well, support conditional logic for error handling, and integrate cleanly with all three tools.

Zapier can work but struggles with the sequential nature of this particular workflow and charges by task count, which becomes expensive when processing large repositories.

How the Workflow Works

The workflow follows this sequence:

1. A webhook or scheduled trigger fires when a repository is committed or updated.

2. SourceAI scans the codebase and outputs a structured JSON representation of the architecture, including modules, dependencies, and code patterns.

3. Mintlify receives that JSON and generates formatted markdown documentation with code examples and API references.

4. Bhava-AI takes the same structure and generates a visual architecture diagram showing how components interact.

5. Both outputs (markdown and diagram) are saved to your documentation repository or knowledge base.

The critical point is that steps 2, 3, and 4 happen in parallel where possible, then results combine before saving.

Step-by-Step Implementation in n8n

Start by creating a new workflow in n8n. Add a webhook trigger that accepts POST requests.

Copy
Webhook configuration:
- Authentication: Basic Auth (username/password recommended)
- HTTP Method: POST
- URL: https://your-n8n-instance.com/webhook/architecture-sync

Your repository's CI/CD pipeline posts to this webhook after commits. Here's an example payload structure:

Copy{
  "repository_url": "https://github.com/yourorg/yourrepo.git",
  "branch": "main",
  "commit_hash": "abc123def456",
  "repository_name": "auth-service",
  "trigger_type": "push"
}

Add a second node to clone or fetch the repository. Use a simple HTTP request to trigger a git operation on a server with git access, or use n8n's built-in Execute Command node if your n8n instance has direct access to repositories.

Copy
Execute Command Node:
Command: git clone {{$json.repository_url}} /tmp/{{$json.repository_name}}

Next, call the SourceAI API to analyse the code structure. SourceAI provides an API endpoint that accepts a repository path and returns structured metadata about the codebase.

Copy
HTTP Request Node to SourceAI:
Method: POST
URL: https://api.sourceai.dev/v1/analyze
Headers:
  Authorization: Bearer YOUR_SOURCEAI_API_KEY
  Content-Type: application/json

Body:
{
  "repository_path": "/tmp/{{$json.repository_name}}",
  "include_patterns": ["src/**/*.js", "src/**/*.ts", "src/**/*.py"],
  "exclude_patterns": ["node_modules/**", "dist/**", "build/**"],
  "output_format": "json",
  "analysis_type": "architecture"
}

SourceAI returns a response like this:

Copy{
  "project_name": "auth-service",
  "modules": [
    {
      "name": "TokenManager",
      "path": "src/token/manager.ts",
      "type": "class",
      "methods": [
        {
          "name": "generateToken",
          "parameters": ["userId", "expiresIn"],
          "returns": "string"
        }
      ],
      "dependencies": ["crypto", "jsonwebtoken"]
    },
    {
      "name": "DatabaseConnection",
      "path": "src/db/connection.ts",
      "type": "class",
      "methods": [
        {
          "name": "connect",
          "parameters": [],
          "returns": "Promise"
        }
      ],
      "dependencies": ["pg"]
    }
  ],
  "interactions": [
    {
      "from": "TokenManager",
      "to": "DatabaseConnection",
      "type": "dependency"
    }
  ]
}

Store this response in a variable for the next steps. In n8n, use a Set node to save the response.

Now add a node for Mintlify. Mintlify accepts structured data and generates markdown documentation. Create an HTTP request to Mintlify's API:

Copy
HTTP Request Node to Mintlify:
Method: POST
URL: https://api.mintlify.com/v1/generate-[docs](/tools/docs)
Headers:
  Authorization: Bearer YOUR_MINTLIFY_API_KEY
  Content-Type: application/json

Body:
{
  "project_name": "{{$json.project_name}}",
  "modules": {{JSON.stringify($json.modules)}},
  "style": "typescript",
  "output_format": "markdown",
  "include_examples": true,
  "diagram_references": true
}

Mintlify returns formatted markdown:

Copy
## Overview
The auth-service provides JWT token generation and user authentication.

## Modules

### TokenManager
Located in `src/token/manager.ts`

Responsible for generating and validating authentication tokens.

**Methods:**
- generateToken(userId, expiresIn) -> string
- validateToken(token) -> TokenPayload
- refreshToken(token) -> string

**Dependencies:**
- crypto
- jsonwebtoken

### DatabaseConnection
Located in `src/db/connection.ts`

Manages connections to PostgreSQL database.

**Methods:**
- connect() -> Promise
- disconnect() -> Promise
- execute(query) -> Promise

**Dependencies:**
- pg

Add this output to another Set node.

For Bhava-AI, make a similar HTTP request to generate visual diagrams:

Copy
HTTP Request Node to Bhava-AI:
Method: POST
URL: https://api.bhava-ai.com/v1/generate-diagram
Headers:
  Authorization: Bearer YOUR_BHAVA_API_KEY
  Content-Type: application/json

Body:
{
  "diagram_type": "architecture",
  "modules": {{JSON.stringify($json.modules)}},
  "interactions": {{JSON.stringify($json.interactions)}},
  "format": "svg",
  "theme": "light"
}

Bhava-AI returns SVG that you can embed in documentation or save as a file.

Combining and Saving Outputs

Add a final node that writes both the markdown documentation and the SVG diagram to your repository. Use Git or a direct file write operation.

If writing to a GitHub repository, use the GitHub API:

Copy
HTTP Request Node to GitHub API:
Method: PUT
URL: https://api.github.com/repos/{{$json.org}}/{{$json.docs_repo}}/contents/docs/architecture.md
Headers:
  Authorization: token YOUR_GITHUB_TOKEN
  Content-Type: application/json

Body:
{
  "message": "Update architecture docs for {{$json.repository_name}} ({{$json.commit_hash}})",
  "content": "{{Buffer.from($json.markdown_content).toString('base64')}}",
  "branch": "main"
}

Run the same request for the SVG diagram:

Copy
HTTP Request Node to GitHub API:
Method: PUT
URL: https://api.github.com/repos/{{$json.org}}/{{$json.docs_repo}}/contents/docs/architecture-diagram.svg
Headers:
  Authorization: token YOUR_GITHUB_TOKEN
  Content-Type: application/json

Body:
{
  "message": "Update architecture diagram for {{$json.repository_name}}",
  "content": "{{Buffer.from($json.svg_diagram).toString('base64')}}",
  "branch": "main"
}

Add error handling nodes at each critical step. If SourceAI fails to analyse the repository, the workflow should log the error and notify you via Slack or email before stopping.

Copy
Error handling in n8n:
1. Add an "On Error" output from the SourceAI HTTP request
2. Connect it to a Slack or Email node with the error message
3. Stop execution without attempting subsequent steps

Implementation in Make (Integromat)

Make's visual interface is slightly different from n8n, but the logic is identical.

Create a new scenario and add an HTTP webhook module as the trigger:

Copy
HTTP Module (Webhook):
- Choose "Custom webhook"
- Set content type to "application/json"
- Copy the webhook URL and add it to your repository

Add a HTTP request module for SourceAI:

Copy
HTTP Module for SourceAI:
Method: POST
URL: https://api.sourceai.dev/v1/analyze
Headers:
  Authorization: Bearer {{api_key_sourceai}}
  Content-Type: application/json

Request body type: Raw
Body: 
{
  "repository_path": "{{repository_path}}",
  "analysis_type": "architecture",
  "output_format": "json"
}

Map the webhook payload fields to this module so the repository path flows through correctly.

Add parallel branches for Mintlify and Bhava-AI so they run simultaneously rather than sequentially. This saves execution time, especially with large codebases.

Use the Router module in Make to handle branching:

Copy
Router (Branch 1):
→ HTTP request to Mintlify
→ Store markdown in variable

Router (Branch 2):
→ HTTP request to Bhava-AI
→ Store SVG in variable

Merge point:
→ GitHub API calls to save both outputs

This approach is roughly 40% faster than running the requests sequentially.

The Manual Alternative

If you prefer hands-on control or have unusual project structures that the automated tools might misinterpret, you can run each tool individually.

Clone your repository and manually run SourceAI from the command line:

Copy
sourceai analyze /path/to/repo --format json --output architecture.json

Then run Mintlify on the output:

Copy
mintlify generate-docs architecture.json --style typescript --output docs.md

Finally, generate your diagram with Bhava-AI:

Copy
bhava-ai diagram --input architecture.json --format svg --output architecture.svg

This approach lets you inspect outputs at each stage and adjust settings before moving to the next tool. You have full control but sacrifice speed. It works well for one-off documentation projects or when you need to customise the output significantly.

Pro Tips

Error handling for rate limits. All three tools have rate limits on their APIs. SourceAI allows 100 requests per hour on their standard plan. If you run workflows for multiple repositories in quick succession, you'll hit this limit. Add a delay node in n8n or Make between requests, or check the response headers for rate limit information and pause execution if you're near the threshold.

Copy
Add to your HTTP requests:
Headers check:
if response.headers['X-RateLimit-Remaining'] < 5:
  wait 60 seconds before next request

Handle large repositories gracefully. Analysing a repository with 50,000+ files takes time. SourceAI may timeout on very large codebases. Exclude directories early using the exclude_patterns parameter so the analysis focuses on source code rather than dependencies, build artifacts, or test files.

Customise Mintlify output for your audience. Mintlify supports multiple output styles. Use TypeScript style for backend services, Python style for data pipelines, and generic Markdown for architecture overviews. Set the style parameter in your API call based on the repository's primary language.

Store diagram versions. Architecture diagrams should change less frequently than documentation. If you regenerate diagrams on every commit, you'll waste storage and create unnecessary git history. Run the Bhava-AI step only when the interactions object actually changes, not on every commit. Use a conditional node to compare the previous diagram structure with the new one.

Monitor workflow costs. Each API call to SourceAI, Mintlify, and Bhava-AI costs money. If you're processing many repositories, costs add up quickly. Set a budget alert in your Make or n8n account, and consider using scheduled runs (weekly or monthly) rather than triggering on every single commit.

Cost Breakdown

If you're generating documentation for a single large project monthly rather than continuously, costs drop to roughly £100 per month because you'll use far fewer API requests.

The automation pays for itself within a few weeks compared to engineering time spent manually writing and updating documentation.