🏗️ ArchDoc Generator

AI-powered architecture documentation generator for any codebase using LangChain and multi-agent workflows.

ArchDoc Generator is an intelligent tool that analyzes your codebase and generates comprehensive, accurate architectural documentation automatically. It supports any programming language and uses AI-powered agents to understand your project structure, dependencies, patterns, security, and data flows.

📋 Table of Contents

• Features
• Quick Start
• CLI Usage
• Programmatic Usage
• Configuration
• What Gets Generated
• Available Agents
• Architecture Highlights
• Supported Languages
• Contributing
• License

✨ Features

• 🤖 8 Specialized AI Agents: File Structure, Dependencies, Patterns, Flows, Schemas, Architecture, Security, and Repository KPI (NEW!).
• 📊 Repository Health Dashboard: LLM-powered KPI analysis with actionable insights on code quality, testing, architecture health, and technical debt.
• ⚡ Generation Performance Metrics: Track agent execution times, token usage, costs, and confidence scores in metadata.
• 🌍 17 Languages Out-of-the-Box: TypeScript, Python, Java, Go, C#, C/C++, Kotlin, PHP, Ruby, Rust, Scala, Swift, CSS, HTML, JSON, XML, Flex/ActionScript.
• 🧠 AI-Powered: Uses LangChain with Claude 4.5, GPT-5, Gemini 2.5, or Grok 3.
• � Comprehensive Analysis: Structure, dependencies, patterns, flows, schemas, security, and executive-level KPIs.
• 📝 Markdown Output: Clean, version-controllable documentation with smart navigation.
• 🔄 Iterative Refinement: Self-improving analysis with quality checks and gap detection.
• 🎨 Customizable: Prompt-based agent selection and configuration.
• � LangSmith Tracing: Full observability of AI workflows with detailed token tracking.
• 🔒 Security Analysis: Vulnerability detection, authentication review, and crypto analysis.
• ➕ Extensible: Add support for any language via configuration—no code changes required.

🚀 Quick Start

Installation

# Using npm
npm install -g @techdebtgpt/archdoc-generator

# Using yarn
yarn global add @techdebtgpt/archdoc-generator

# Using pnpm
pnpm add -g @techdebtgpt/archdoc-generator

Interactive Setup (Recommended)

Run the interactive configuration wizard:

archdoc config --init

This will:

1. Prompt you to choose an LLM provider (Anthropic/OpenAI/Google).
2. Ask for your API key.
3. Create .archdoc.config.json with your configuration.
4. Validate your setup.

Basic Usage

Available Commands

Documentation Generation

# Analyze current directory
archdoc analyze

# Analyze specific project
archdoc analyze /path/to/your/project

# Custom output location
archdoc analyze --output ./docs

# Enhanced analysis with user focus (runs all agents with extra attention to specified topics)
archdoc analyze --prompt "security vulnerabilities and authentication patterns"
archdoc analyze --prompt "database schema design and API architecture"

# Analysis depth modes
archdoc analyze --depth quick    # Fast, less detailed (2 iterations, 70% threshold)
archdoc analyze --depth normal   # Balanced (5 iterations, 80% threshold) - default
archdoc analyze --depth deep     # Thorough, most detailed (10 iterations, 90% threshold)

# Disable iterative refinement for faster results
archdoc analyze --no-refinement

# Verbose output for debugging
archdoc analyze --verbose

C4 Architecture Model Generation

# Generate C4 model for current directory
archdoc analyze --c4

# Generate C4 model for specific project
archdoc analyze /path/to/project --c4

# Custom output location for C4 model
archdoc analyze --c4 --output ./architecture-docs

# C4 model with verbose output
archdoc analyze --c4 --verbose

Configuration Management

# Interactive configuration wizard (recommended for first-time setup)
archdoc config --init

# List current configuration
archdoc config --list

# Get specific configuration value
archdoc config --get llmProvider
archdoc config --get anthropicApiKey

# Set configuration value
archdoc config --set llmProvider=anthropic
archdoc config --set anthropicApiKey=your-api-key

# Reset configuration to defaults
archdoc config --reset

Export and Format Options

# Single-file output (default: multi-file)
archdoc analyze --single-file

# Export as JSON
archdoc analyze --single-file --format json

# Export as HTML
archdoc analyze --single-file --format html

# Export as Markdown (default)
archdoc analyze --single-file --format markdown

# Export existing documentation to different formats
archdoc export .arch-docs --format html --output ./docs.html
archdoc export .arch-docs --format json --output ./docs.json
archdoc export .arch-docs --format confluence --output ./confluence.md

# Export with custom template
archdoc export .arch-docs --format html --template ./my-template.html --output ./custom-docs.html

Advanced Usage

# Incremental updates (preserves existing docs, adds new analysis)
archdoc analyze --prompt "new feature area to document"
# (Automatically detects existing docs and runs in incremental mode)

# Full regeneration even if docs exist
archdoc analyze --clean

# Specify LLM provider and model
archdoc analyze --provider anthropic --model claude-sonnet-4-5-20250929
archdoc analyze --provider openai --model gpt-4o
archdoc analyze --provider google --model gemini-2.0-flash-exp

# Budget control (halt if cost exceeds limit)
archdoc analyze --max-cost 10.0  # Stop if cost exceeds $10

# Custom refinement settings
archdoc analyze --refinement-iterations 10 --refinement-threshold 90 --refinement-improvement 15

CLI Usage

archdoc analyze [path] [options]

Options:

C4 Model Generation

Generate structured C4 architecture diagrams with PlantUML output:

# Generate C4 model
archdoc analyze --c4

# Generate for specific project
archdoc analyze /path/to/project --c4 --output ./architecture

# Output includes:
# - c4-model.json (structured data)
# - context.puml (system context diagram)
# - containers.puml (container diagram)
# - components.puml (component diagram)

🔧 Programmatic Usage

Use the library in your Node.js applications:

Standard Documentation

import {
  DocumentationOrchestrator,
  AgentRegistry,
  FileSystemScanner,
} from '@techdebtgpt/archdoc-generator';

// Setup registry with agents
const registry = new AgentRegistry();
const scanner = new FileSystemScanner();
const orchestrator = new DocumentationOrchestrator(registry, scanner);

// Generate documentation
const docs = await orchestrator.generateDocumentation('/path/to/project', {
  maxTokens: 100000,
  parallel: true,
  iterativeRefinement: {
    enabled: true,
    maxIterations: 5,
    clarityThreshold: 80,
  },
});

console.log('Generated:', docs.summary);

C4 Architecture Model

import {
  C4ModelOrchestrator,
  AgentRegistry,
  FileSystemScanner,
} from '@techdebtgpt/archdoc-generator';

// Setup registry with agents
const registry = new AgentRegistry();
const scanner = new FileSystemScanner();
const orchestrator = new C4ModelOrchestrator(registry, scanner);

// Generate C4 model
const result = await orchestrator.generateC4Model('/path/to/project');

console.log('C4 Context:', result.c4Model.context);
console.log('Containers:', result.c4Model.containers);
console.log('Components:', result.c4Model.components);

// PlantUML diagrams available in result.plantUMLModel

See the API Reference for complete programmatic documentation.

⚙️ Configuration

Environment Variables

See the Configuration Guide for detailed options.

🎨 What Gets Generated

Standard Documentation

The tool generates a multi-file documentation structure:

.arch-docs/
├── index.md              # Table of contents with smart navigation
├── architecture.md       # High-level system design
├── file-structure.md     # Project organization
├── dependencies.md       # External & internal deps
├── patterns.md           # Design patterns detected
├── code-quality.md       # Quality metrics (if data exists)
├── flows.md              # Data & control flows
├── schemas.md            # Data models
├── security.md           # Security vulnerability analysis
├── recommendations.md    # Improvement suggestions
├── kpi.md                # Repository health KPI dashboard (NEW!)
├── metadata.md           # Generation metadata + performance metrics
└── changelog.md          # Documentation update history

What's New:

• kpi.md: LLM-generated repository health dashboard with actionable insights on code quality, testing coverage, architecture health, dependency management, and technical debt.
• Generation Performance Metrics: Added to metadata.md showing agent confidence scores, execution times, token efficiency, and cost breakdown.

C4 Architecture Model

When using --c4, generates structured architecture diagrams:

.arch-docs-c4/
├── c4-model.json         # Complete C4 model (JSON)
├── context.puml          # System Context (Level 1)
├── containers.puml       # Container Diagram (Level 2)
└── components.puml       # Component Diagram (Level 3)

C4 Model Levels:

• Context: Shows the system boundary, actors (users), and external systems
• Containers: Shows deployable units (APIs, web apps, databases, microservices)
• Components: Shows internal modules and their relationships within containers

🤖 Available Agents

Each agent specializes in a specific analysis task using LLM-powered intelligence:

KPI Analyzer Features:

• 📊 Overall repository health score (0-100%)
• 🎯 Component scores: Code quality, testing, architecture, dependencies, complexity
• 📈 Detailed metrics with ASCII visualizations
• 💡 8+ actionable insights with prioritized action items
• 🚀 Executive-friendly language with quantifiable targets

🏗️ Architecture Highlights

Multi-Agent System

The orchestrator coordinates agents to perform analysis.

┌─────────────────────────────┐
│  Documentation Orchestrator │
└─────────────┬─────────────┘
              │
    ┌─────────┴─────────┐
    │  Agent Registry   │
    └─────────┬─────────┘
              │
┌───▼────┐  ┌───▼───┐  ┌───▼───┐
│ Agent 1│  │ Agent 2│  │ Agent N│
└────────┘  └───────┘  └───────┘

Self-Refining Analysis

Each agent autonomously improves its analysis through iterative refinement. It evaluates its own output, identifies gaps, searches for relevant code, and refines until quality thresholds are met.

Learn how the self-refinement workflow works →

LangChain LCEL Integration

All agents use LangChain Expression Language (LCEL) for composable AI workflows with unified LangSmith tracing.

📊 Language Support

ArchDoc Generator supports 17 programming and markup languages out-of-the-box with zero configuration:

Programming Languages

Web & Data Languages

Multi-Language Projects

The scanner automatically detects all supported languages in your project:

# Just run the command - no configuration needed!
archdoc analyze ./my-project

# Example output:
# ✅ Found 487 imports across 17 file types
# - TypeScript: 234 imports
# - Python: 123 imports
# - Rust: 89 imports
# - CSS: 41 imports

Custom Language Support

Need support for a language not listed? No code changes required!

Add custom language configurations via .archdoc.config.json:

{
  "languages": {
    "custom": {
      "myLanguage": {
        "displayName": "My Language",
        "filePatterns": {
          "extensions": [".mylang"]
        },
        "importPatterns": {
          "myImport": "^import\\s+([^;]+);"
        }
      }
    }
  }
}

See Custom Language Configuration Guide for complete documentation on:

• Adding new languages
• Extending built-in language configurations
• Custom import pattern syntax
• Language-specific frameworks and keywords

🤝 Contributing

We welcome contributions! See the Contributing Guide for details on:

• Development setup
• Creating custom agents
• Testing guidelines
• Code style and standards
• Pull request process

Community Guidelines

• Code of Conduct - Our pledge to foster an open and welcoming environment
• Security Policy - How to report security vulnerabilities responsibly
• Issue Templates - Bug reports, feature requests, and more
• Pull Request Template - Guidelines for submitting changes

� Resources

• 🌐 Website: techdebtgpt.com
• 📦 GitHub: github.com/techdebtgpt/architecture-doc-generator
• 📚 Documentation: Full Documentation
• 💬 Discussions: GitHub Discussions
• 🐛 Issues: Report Issues

�📄 License

Apache License 2.0 - see the LICENSE file for details.

Made with ❤️ by TechDebtGPT