Code repository documentation generation and architecture diagramming

Introduction

Maintaining accurate, up-to-date documentation for a code repository is a perpetual friction point. Your codebase evolves faster than your docs can follow. Meanwhile, architecture diagrams decay into obsolescence within weeks of deployment changes. Teams end up with either outdated diagrams in Confluence or no diagrams at all, forcing new developers to reverse-engineer the system mentally.

This workflow solves that problem by combining three specialised AI tools into a fully automated pipeline. When code changes land in your repository, bhava-ai analyses the codebase structure, mintlify transforms that analysis into polished documentation, and windsurf generates accurate architecture diagrams. No manual handoff. No waiting for someone to remember to update the docs. The output lands ready to publish.

The workflow is genuinely complex to set up, which is why we've classified it as advanced. But once it runs, you're essentially outsourcing your documentation maintenance to AI, freeing your team to focus on writing code rather than documenting it.

The Automated Workflow

We'll build this using n8n as the orchestration backbone, though the same logic maps onto Zapier or Make. The workflow operates on a schedule or webhook trigger when commits land in your repository.

How the pieces fit together:

bhava-ai reads your repository and generates a structural analysis (function signatures, dependencies, module relationships). That output feeds into mintlify, which uses it to generate professional API documentation. Simultaneously, windsurf takes the same structural data and produces architecture diagrams in SVG or PNG format. Both outputs get committed back to your repository or published to your documentation site.

Setting up the webhook trigger in n8n:

Create a new workflow and start with a webhook node configured to receive POST requests from your Git provider. GitHub's webhook events are straightforward:

Copy
POST /webhook/your-unique-id
Content-Type: application/json

{
  "action": "opened",
  "pull_request": {
    "html_url": "https://github.com/yourorg/yourrepo/pull/123",
    "head": {
      "sha": "abc123def456",
      "ref": "feature/new-api"
    }
  },
  "repository": {
    "clone_url": "https://github.com/yourorg/yourrepo.git"
  }
}

Configure the webhook to trigger only on push events to your main branch or on pull request merges. This prevents the workflow running on every single commit.

Step 1: Repository cloning and initial analysis with bhava-ai:

Add an HTTP request node that calls bhava-ai's repository analysis endpoint. You'll need a bhava-ai API key; obtain one from their dashboard.

Copy
POST https://api.bhava-ai.com/v1/repositories/analyse
Authorization: Bearer YOUR_BHAVA_API_KEY
Content-Type: application/json

{
  "repository_url": "https://github.com/yourorg/yourrepo.git",
  "branch": "main",
  "include_patterns": ["src/**/*.ts", "src/**/*.js", "src/**/*.py"],
  "exclude_patterns": ["node_modules", "dist", "build"],
  "analysis_depth": "full",
  "output_format": "json"
}

bhava-ai returns a detailed JSON structure containing:

Copy{
  "modules": [
    {
      "name": "auth",
      "path": "src/auth",
      "functions": [
        {
          "name": "verifyToken",
          "signature": "verifyToken(token: string): Promise<User>",
          "description": "Validates JWT token against current signing key"
        }
      ],
      "dependencies": ["crypto", "jsonwebtoken"],
      "exports": ["verifyToken", "generateToken"]
    }
  ],
  "architecture": {
    "layers": ["api", "service", "data"],
    "connections": [
      {"from": "api", "to": "service"},
      {"from": "service", "to": "data"}
    ]
  },
  "statistics": {
    "total_functions": 47,
    "total_modules": 12,
    "complexity_score": 6.2
  }
}

Store this response in an n8n variable for the next steps. Use an expression node:

Copy
{{ $json.body }}

Step 2: Documentation generation with mintlify:

Create a new HTTP node calling mintlify's generation endpoint. You're passing the bhava-ai analysis output as context.

Copy
POST https://api.mintlify.com/v1/docs/generate
Authorization: Bearer YOUR_MINTLIFY_API_KEY
Content-Type: application/json

{
  "project_id": "your-project-id",
  "title": "API Reference",
  "description": "Auto-generated from repository analysis",
  "analysis_data": {{ $json.step1_bhava_response }},
  "style": {
    "theme": "dark",
    "colour_scheme": "blue"
  },
  "output_format": "markdown",
  "include_examples": true,
  "group_by": "module"
}

Mintlify processes this and returns a complete documentation structure, typically as MDX (Markdown with JSX) or plain Markdown depending on your target platform:

Copy## verifyToken

Validates JWT token against current signing key.

**Parameters:**
- `token` (string): The JWT token to validate

**Returns:**
Promise<User>: User object if token is valid

**Example:**
\`\`\`typescript
const user = await verifyToken(authHeader.split(' ')[1]);
console.log(user.email);
\`\`\`

**Errors:**
- TokenExpiredError: Token has expired
- InvalidSignatureError: Token signature is invalid

Store this output in another variable:

Copy
{{ $json.documentation_output }}

Step 3: Architecture diagram generation with windsurf:

Windsurf consumes the same bhava-ai analysis data but focuses on visual relationships. Call windsurf's diagram generation endpoint:

Copy
POST https://api.windsurf.dev/v1/diagrams/generate
Authorization: Bearer YOUR_WINDSURF_API_KEY
Content-Type: application/json

{
  "diagram_type": "architecture",
  "analysis_data": {{ $json.step1_bhava_response }},
  "output_format": "svg",
  "include_data_flow": true,
  "include_dependencies": true,
  "layout": "hierarchical",
  "colour_scheme": "professional"
}

Windsurf returns an SVG diagram of your architecture, with modules as boxes and dependency arrows between them. The response includes the raw SVG as a base64-encoded string:

Copy{
  "diagram_svg": "PHN2ZyB3aWR0aD0iODAwIiBo...",
  "diagram_url": "https://generated-diagrams.windsurf.dev/abc123.svg",
  "metrics": {
    "module_count": 12,
    "connection_count": 23,
    "depth": 4
  }
}

Step 4: Commit outputs back to repository:

Add a Git commit node in n8n. This requires configuring Git credentials within n8n, or using the GitHub API directly. Using the GitHub API is more reliable:

Copy
POST https://api.github.com/repos/yourorg/yourrepo/contents/docs/architecture.svg
Authorization: Bearer YOUR_GITHUB_TOKEN
Content-Type: application/json

{
  "message": "Auto-generated: architecture diagram from bhava-ai analysis",
  "content": "{{ $json.step3_windsurf_svg }}",
  "branch": "main"
}

Do the same for the markdown documentation:

Copy
POST https://api.github.com/repos/yourorg/yourrepo/contents/docs/api-reference.md
Authorization: Bearer YOUR_GITHUB_TOKEN
Content-Type: application/json

{
  "message": "Auto-generated: API reference from code analysis",
  "content": "{{ $json.step2_mintlify_output }}",
  "branch": "main"
}

Step 5: Slack notification (optional but recommended):

Add a Slack node to notify your team that documentation has been regenerated. This creates visibility and catches any unexpected outputs:

Copy
POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL
Content-Type: application/json

{
  "text": "Documentation regenerated",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Documentation Auto-Update Complete*\n\n• Architecture diagram: `docs/architecture.svg`\n• API reference: `docs/api-reference.md`\n• Modules analysed: 12\n• Functions documented: 47"
      }
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": {"type": "plain_text", "text": "View on GitHub"},
          "url": "https://github.com/yourorg/yourrepo"
        }
      ]
    }
  ]
}

Complete n8n workflow structure:

Copy
1. Webhook Trigger (GitHub push/PR merge)
   ↓
2. HTTP: bhava-ai repository analysis
   ↓
3. HTTP: mintlify documentation generation
   ├─ Input: bhava-ai output
   └─ Output: markdown documentation
   ↓
4. HTTP: windsurf diagram generation
   ├─ Input: bhava-ai output
   └─ Output: SVG diagram
   ↓
5. HTTP: GitHub API commit (documentation)
   ↓
6. HTTP: GitHub API commit (diagram)
   ↓
7. Slack notification
   ↓
8. End

The Manual Alternative

If you prefer more control over the documentation output, run these steps manually in sequence:

For documentation:

1. Clone your repository locally.
2. Visit bhava-ai's web interface and upload your repository.
3. Download the structured analysis as JSON.
4. Upload that JSON to mintlify's dashboard.
5. Review the generated markdown, edit as needed.
6. Commit manually to your repository.

For diagrams:

1. Use the same bhava-ai analysis from step 3 above.
2. Upload to windsurf's diagram tool.
3. Customise the diagram layout, colours, and groupings in their visual editor.
4. Export and save the SVG.
5. Commit manually.

This approach gives you a review step before documentation goes live, which is valuable if your architecture contains sensitive details or non-standard patterns that AI analysis might misrepresent. The trade-off is time; you're back to manual documentation maintenance, though still faster than writing it from scratch.

Pro Tips

1. Set API rate limit buffers:

All three services impose rate limits. bhava-ai allows 10 analyses per minute on the free tier; mintlify permits 100 generations daily; windsurf has a 30-diagram-per-hour cap. If your repository is large, split it into modules and analyse each separately. Add delays between API calls in n8n using Wait nodes:

Copy
Add Wait node between requests
Set to: 2 seconds

This prevents hitting rate limits if the workflow processes multiple repositories.

2. Version your diagram outputs:

Archive old diagrams so you can track how architecture evolves. Before committing new diagrams, rename the existing one:

Copy
GitHub API: GET /repos/yourorg/yourrepo/contents/docs/architecture.svg
Then: POST to /docs/architecture-2024-01-15.svg
Then: POST new diagram to /docs/architecture.svg

This gives you a history of architecture changes without cluttering your main branch.

3. Use conditional logic for large repositories:

If your repository exceeds 500 functions, bhava-ai may take several minutes to complete analysis. Use n8n's conditional nodes to check response status and wait if needed:

Copy
HTTP Request node
↓
If status = "processing" (add Wait: 30 seconds, then poll)
↓
If status = "complete" (proceed to next step)
↓
If status = "error" (send error notification, retry)

4. Exclude generated code and third-party modules:

Configure bhava-ai's exclude patterns aggressively. Generated code (GraphQL schemas, protobuf bindings) clutters documentation. Third-party dependencies muddy your architecture diagram. Use:

Copy"exclude_patterns": [
  "node_modules/**",
  "dist/**",
  "build/**",
  "*.generated.ts",
  "*.pb.ts",
  ".next/**",
  "__generated__/**"
]

5. Monitor for documentation staleness:

Even automated documentation can drift if developers bypass the workflow (pushing directly to main outside CI/CD). Add a scheduled n8n check that runs weekly, comparing your last analysis timestamp to the last commit date. If they're more than 7 days apart, trigger a manual regeneration and alert the team:

Copy
1. GET last commit timestamp from GitHub
2. GET last documentation generation timestamp from n8n
3. If difference > 7 days:
   a. Trigger workflow manually
   b. Send Slack alert: "Docs are stale; regenerating"

Cost Breakdown

The self-hosted approach saves the n8n subscription but requires infrastructure; for most teams, the cloud cost is negligible against the time saved maintaining documentation manually.

Next steps: Start with a test repository. Set the workflow to run daily rather than on every push, giving you time to review outputs and adjust API parameters. Once you're confident in the quality, switch to triggering on every main-branch commit and integrate into your deployment pipeline.