Documentation Auto-Generator

Overview

An agent that reads your codebase and generates comprehensive documentation — API references, architecture overviews, setup guides, component docs, and developer onboarding guides. It understands code structure, extracts types and interfaces, and produces markdown documentation that stays accurate and up-to-date.

Quick Start

Copy
# Generate API documentation from your routes
claude "Generate API documentation for all endpoints in src/routes/"

# Generate a project README
claude "Create a comprehensive README for this project"

# Generate architecture documentation
claude "Document the system architecture with diagrams"

# Generate component documentation
claude "Create docs for all React components in src/components/"

Documentation Types

1. API Reference

Generates endpoint documentation from your route files:

Copy
## POST /api/users

Create a new user account.

**Authentication:** Required (Bearer token)
**Authorization:** Admin only

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | Valid email address |
| `name` | string | Yes | Full name (2-100 chars) |
| `role` | enum | No | One of: `admin`, `editor`, `viewer`. Default: `viewer` |
| `teamId` | string | No | Team to assign the user to |

### Example Request

```json
POST /api/users
Authorization: Bearer eyJhbG...
Content-Type: application/json

{
  "email": "[email protected]",
  "name": "Jane Smith",
  "role": "editor",
  "teamId": "team-123"
}

Response

201 Created

Copy
{
  "data": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "Jane Smith",
    "role": "editor",
    "teamId": "team-123",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Error Responses

Status	Description
400	Validation failed (invalid email, missing required fields)
401	Missing or invalid authentication token
403	Insufficient permissions (admin required)
409	Email already registered

### 2. Architecture Overview

Generates system-level documentation:

```markdown
## System Architecture

### Overview

The application follows a layered architecture with clear separation
of concerns:

┌─────────────────────────────────────────┐ │ Client Layer │ │ React SPA / Mobile App / API Client │ ├─────────────────────────────────────────┤ │ API Gateway │ │ Rate Limiting · Auth · Load Balance │ ├────────┬──────────┬─────────┬──────────┤ │ Auth │ Users │ Orders │ Payments │ │Service │ Service │ Service │ Service │ ├────────┴──────────┴─────────┴──────────┤ │ Message Queue (Redis) │ ├────────┬──────────┬─────────┬──────────┤ │ User │ Order │ Payment │ Event │ │ DB │ DB │ DB │ Store │ └────────┴──────────┴─────────┴──────────┘

### Directory Structure

src/ ├── routes/ # HTTP endpoint definitions ├── controllers/ # Request handling & response formatting ├── services/ # Business logic (framework-agnostic) ├── models/ # Database schemas & data access ├── middleware/ # Auth, validation, error handling ├── utils/ # Shared utilities & helpers ├── types/ # TypeScript interfaces & types ├── config/ # Environment & app configuration ├── jobs/ # Background job processors └── tests/ # Test suites

### Data Flow

1. Request hits route → middleware chain (auth, rate limit, validate)
2. Controller parses request → calls service with clean data
3. Service executes business logic → calls model for data access
4. Model queries database → returns typed results
5. Controller formats response → sends to client

### Key Design Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Architecture | Layered monolith | Simple to start, easy to extract services later |
| Database | PostgreSQL | ACID compliance, JSON support, mature ecosystem |
| Auth | JWT + refresh tokens | Stateless, scalable, standard |
| API style | REST | Team familiarity, tooling support |
| Queue | Redis + BullMQ | Simple setup, reliable for current scale |

3. Setup Guide

Generates onboarding documentation:

Copy
## Developer Setup Guide

### Prerequisites

| Tool | Version | Installation |
|------|---------|-------------|
| Node.js | >= 20 | `nvm install 20` |
| PostgreSQL | >= 15 | `brew install postgresql@15` |
| Redis | >= 7 | `brew install redis` |
| Docker | >= 24 | [Download](https://docker.com) |

### Quick Start

1. **Clone the repository**

   ```bash
   git clone https://github.com/org/project.git
   cd project

2. Install dependencies

   Copy
   npm install

3. Set up environment variables

   Copy
   cp .env.example .env
   # Edit .env with your local settings

4. Start the database

   Copy
   # Option A: Docker
   docker compose up -d postgres redis
   
   # Option B: Local services
   brew services start postgresql@15
   brew services start redis

5. Run database migrations

   Copy
   npm run db:migrate
   npm run db:seed   # Optional: seed with test data

6. Start the development server

   Copy
   npm run dev
   # API available at http://localhost:3001
   # Frontend at http://localhost:3000

Environment Variables

Variable	Required	Default	Description
DATABASE_URL	Yes	—	PostgreSQL connection string
REDIS_URL	Yes	redis://localhost:6379	Redis connection string
JWT_SECRET	Yes	—	Secret for signing JWT tokens
PORT	No	3001	API server port
NODE_ENV	No	development	Environment mode
STRIPE_SECRET_KEY	No	—	Stripe API key (for payments)
SMTP_HOST	No	—	Email server host

Common Tasks

Copy
# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Format code
npm run format

# Build for production
npm run build

# Run database migrations
npm run db:migrate

# Create a new migration
npm run db:migration:create -- --name add-orders-table

# Reset database (development only)
npm run db:reset

Troubleshooting

Issue	Solution
Port 3001 already in use	lsof -i :3001 to find process, then kill -9 <PID>
Database connection refused	Check PostgreSQL is running: pg_isready
Migration failed	Run npm run db:status to check migration state
Node version mismatch	Run nvm use to switch to project's Node version

### 4. Component Documentation

Generates docs for React components:

```markdown
## Component: DataTable

A feature-rich data table with sorting, pagination, filtering,
row selection, and CSV export.

### Import

```tsx
import { DataTable } from '@/components/DataTable';

Props

Prop	Type	Default	Description
data	T[]	required	Array of data objects
columns	Column<T>[]	required	Column definitions
pageSize	number	20	Rows per page
sortable	boolean	true	Enable column sorting
selectable	boolean	false	Enable row selection
onSelectionChange	(rows: T[]) => void	—	Callback on selection change
onRowClick	(row: T) => void	—	Callback on row click
loading	boolean	false	Show loading skeleton
emptyMessage	string	'No data'	Message when data is empty
exportable	boolean	false	Show CSV export button

Usage

Copy
const columns = [
  { key: 'name', label: 'Name', sortable: true },
  { key: 'email', label: 'Email', sortable: true },
  { key: 'role', label: 'Role', render: (val) => <Badge>{val}</Badge> },
  { key: 'createdAt', label: 'Joined', render: (val) => formatDate(val) },
];

<DataTable
  data={users}
  columns={columns}
  pageSize={25}
  selectable
  onSelectionChange={setSelectedUsers}
  exportable
/>

### 5. Changelog

Generates release notes from git history:

```markdown
## v2.1.0 (2024-01-15)

### New Features
- **User invitations** — Invite users to teams via email with role assignment
- **CSV export** — Export table data to CSV from the DataTable component
- **Dark mode** — System-aware dark mode with manual toggle

### Improvements
- Improved search performance with debounced API calls
- Added loading skeletons to all data-heavy pages
- Reduced bundle size by 23% through code splitting

### Bug Fixes
- Fixed session expiry not redirecting to login page
- Fixed pagination resetting when filters change
- Fixed mobile menu not closing after navigation

### Breaking Changes
- `UserService.create()` now requires a `teamId` parameter
- Removed deprecated `GET /api/users/search` endpoint (use `GET /api/users?search=` instead)

Auto-Detection

The generator automatically detects and adapts to:

Framework	Detection	Documentation Style
Express.js	app.get(), router.post() patterns	REST API reference
Next.js API	pages/api/ or app/api/ directories	API routes + pages
GraphQL	.graphql files, resolvers	Schema + query docs
React	.tsx components	Component props + usage
Prisma	schema.prisma	Data model reference
OpenAPI	openapi.yaml	Swagger-compatible docs

Output Formats

Format	Command	Use Case
Markdown	Default	GitHub wikis, repos
MDX	--format mdx	Docusaurus, Nextra
HTML	--format html	Static site hosting
OpenAPI	--format openapi	Swagger UI, Postman
JSDoc	Inline in code	IDE tooltips

Configuration

Copy
// .claude/docs-config.json
{
  "output": "docs/",
  "format": "markdown",
  "sections": ["api", "architecture", "setup", "components"],
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["src/**/*.test.ts", "src/**/*.stories.tsx"],
  "apiBaseUrl": "https://api.example.com",
  "projectName": "My App",
  "badges": ["build", "coverage", "license"]
}

Keeping Docs Updated

Pre-commit Hook

Regenerate docs automatically when source files change:

Copy
// .claude/hooks.json
{
  "hooks": {
    "pre-commit": {
      "command": "claude docs --changed-only",
      "description": "Update docs for changed files"
    }
  }
}

CI Pipeline

Copy
# .github/workflows/docs.yml
on:
  push:
    branches: [main]
    paths: ['src/**']

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx claude docs --all
      - uses: peaceiris/actions-gh-pages@v3
        with:
          publish_dir: docs/

Best Practices

1. Document the why, not the what — Code shows what; docs explain why decisions were made
2. Keep examples runnable — Every code example should work if copy-pasted
3. Use consistent terminology — Define terms once and use them everywhere
4. Include error examples — Show what happens when things go wrong
5. Version your docs — Tag docs with the API version they describe
6. Link between docs — Cross-reference related sections
7. Start with a quick start — First section should get someone running in under 5 minutes
8. Document edge cases — Cover the non-obvious behavior
9. Add diagrams — Architecture flows, data models, sequence diagrams
10. Review docs like code — Include docs in PR reviews