Architecture

open-auto-doc is an automated documentation generation system that analyzes code repositories using Claude AI agents and generates beautiful documentation websites. The monorepo consists of 3 main packages: an AI analysis engine (analyzer) that uses the Claude Agent SDK to understand code structure, a template rendering engine (generator) that produces MDX content, and a CLI interface (cli) that orchestrates the workflow and handles GitHub integration. The system runs a 4-stage pipeline: static code parsing, architecture analysis via AI agents, parallel detail analysis (APIs, components, data models, features), and getting-started guide synthesis, producing structured analysis results that are rendered into a Fumadocs-based documentation site.

Data Flow

User Input → CLI (init command) → Analyzer Pipeline → Static Parsing (file tree, dependencies, imports) → Architecture Agent (AI analysis) → Parallel Detail Agents (APIs, components, models, features) → Getting Started Synthesis → Analysis Results → Generator (Handlebars templates) → MDX Content → Site Scaffold (Fumadocs) → Generated Docs Site → CLI Deploy (GitHub + Vercel) → Published Documentation Website. Incremental mode skips unchanged sections via Change Detection and Caching.

Key Patterns

• 4-stage analysis pipeline (static → arch → details → synthesis)
• Agent SDK integration via runAgent() wrapper with structured JSON schemas
• Parallel agent execution with graceful failure handling (Promise.allSettled)
• Incremental analysis with change detection and caching
• Zod v4 for schema validation in agent outputs
• ESM-only codebase with .js file extensions
• GitHub OAuth Device Flow for CLI authentication
• TypeScript strict mode with tsup bundling
• Process event listener tuning for parallel queries

Entry Points

• packages/cli/src/index.ts (CLI entry)
• packages/analyzer/src/index.ts (analyzer exports)
• packages/generator/src/index.ts (generator exports)
• npm run build (full monorepo build)
• npm run local (test CLI)
• node packages/cli/dist/index.js (deployed CLI)

Modules

analyzer

Core AI-powered code analysis engine. Orchestrates a 4-stage pipeline: static parsing (file tree, dependencies, imports), architecture analysis via Claude agents, parallel detail analysis (APIs, components, models), and getting-started guide synthesis.

Key Files:

• packages/analyzer/src/pipeline.ts
• packages/analyzer/src/agent-sdk.ts
• packages/analyzer/src/agents/*
• packages/analyzer/src/parsers/*
• packages/analyzer/src/cache.ts
• packages/analyzer/src/diff.ts

Responsibilities:

• Execute 4-stage analysis pipeline (parsing → architecture → details → synthesis)
• Manage Claude Agent SDK integration with structured output schemas
• Run architecture analysis to identify modules and generate Mermaid diagrams
• Execute parallel detail agents (APIs, components, data models, features)
• Implement incremental analysis with change detection and caching
• Support repository initialization with CLAUDE.md generation
• Parse file trees, dependencies, import graphs, and entry points
• Handle agent failures gracefully (non-fatal for detail agents)

generator

Handlebars-based MDX template rendering engine. Transforms analysis results into MDX documentation content and scaffolds documentation sites from Fumadocs template.

Key Files:

• packages/generator/src/scaffold.ts
• packages/generator/src/content-writer.ts
• packages/generator/src/meta-writer.ts
• packages/generator/templates/mdx/*

Responsibilities:

• Scaffold Fumadocs documentation site structure into user projects
• Render Handlebars templates for MDX content generation
• Transform analysis results (architecture, APIs, components) into markdown
• Copy and configure site-template with project-specific placeholders
• Write metadata files for documentation site configuration
• Generate index pages, navigation, and API documentation files

cli

Command-line interface published as @latent-space-labs/open-auto-doc. Orchestrates the analysis-to-deployment workflow with GitHub OAuth integration and interactive prompts.

Key Files:

• packages/cli/src/index.ts
• packages/cli/src/commands/*

Responsibilities:

• Provide user-facing CLI commands (init, generate, deploy, setup-ci, login, logout)
• Coordinate analysis, generation, and deployment workflows
• Handle GitHub OAuth Device Flow authentication
• Manage interactive prompts for user input using @clack/prompts
• Create GitHub repositories and push documentation sites
• Generate GitHub Actions workflows for auto-updating docs
• Support incremental regeneration and cache control

site-template

Fumadocs v16 + Next.js + Tailwind CSS template providing the documentation site infrastructure. Not part of workspace build but copied during scaffolding.

Key Files:

• packages/site-template/*

Responsibilities:

• Provide base documentation site template
• Include Fumadocs v16 configuration
• Supply Tailwind v4 CSS-first styling
• Contain placeholder templates for project name and configuration

Diagrams

Architecture Overview

High-level system architecture showing the three main packages and their interactions

Data Flow: From Repository to Documentation

Complete data flow showing how code is analyzed and transformed into documentation

Analyzer Pipeline: Multi-Stage Processing

Detailed 4-stage pipeline showing the core analysis workflow with parallel execution

API Request Flow - Documentation Search

Sequence diagram showing the flow of a search request through the documentation site