Project Documentation Generator
Generate structured project documentation by analysing the codebase. Produces docs that reflect the actual code, not aspirational architecture.
When to Use
- New project needs initial documentation
- Docs are missing or stale
- Onboarding someone to the codebase
- Post-refactor doc refresh
Workflow
1. Detect Project Type
Scan the project root to determine what kind of project this is:
| Indicator | Project Type |
|---|---|
wrangler.jsonc / wrangler.toml | Cloudflare Worker |
vite.config.ts + src/App.tsx | React SPA |
astro.config.mjs | Astro site |
next.config.js | Next.js app |
package.json with hono | Hono API |
src/index.ts with Hono | API server |
drizzle.config.ts | Has database layer |
schema.ts or schema/ | Has database schema |
pyproject.toml / setup.py | Python project |
Cargo.toml | Rust project |
2. Ask What to Generate
Which docs should I generate? 1. ARCHITECTURE.md — system overview, stack, directory structure, key flows 2. API_ENDPOINTS.md — routes, methods, params, response shapes, auth 3. DATABASE_SCHEMA.md — tables, relationships, migrations, indexes 4. All of the above
Only offer docs that match the project. Don't offer API_ENDPOINTS.md for a static site. Don't offer DATABASE_SCHEMA.md if there's no database.
3. Scan the Codebase
For each requested doc, read the relevant source files:
ARCHITECTURE.md — scan:
package.json/pyproject.toml(stack, dependencies)- Entry points (
src/index.ts,src/main.tsx,src/App.tsx) - Config files (
wrangler.jsonc,vite.config.ts,tsconfig.json) - Directory structure (top 2 levels)
- Key modules and their exports
API_ENDPOINTS.md — scan:
- Route files (
src/routes/,src/api/, or inline in index) - Middleware files (auth, CORS, logging)
- Request/response types or Zod schemas
- Error handling patterns
DATABASE_SCHEMA.md — scan:
- Drizzle schema files (
src/db/schema.ts,src/schema/) - Migration files (
drizzle/,migrations/) - Raw SQL files if present
- Seed files if present
4. Generate Documentation
Write each doc to docs/ (create the directory if it doesn't exist). If the project already has docs there, offer to update rather than overwrite.
For small projects with no docs/ directory, write to the project root instead.
Document Templates
ARCHITECTURE.md
markdown# Architecture ## Overview [One paragraph: what this project does and how it's structured] ## Stack | Layer | Technology | Version | |-------|-----------|---------| | Runtime | [e.g. Cloudflare Workers] | — | | Framework | [e.g. Hono] | [version] | | Database | [e.g. D1 (SQLite)] | — | | ORM | [e.g. Drizzle] | [version] | | Frontend | [e.g. React 19] | [version] | | Styling | [e.g. Tailwind v4] | [version] | ## Directory Structure [Annotated tree — top 2 levels with purpose comments] ## Key Flows ### [Flow 1: e.g. "User Authentication"] [Step-by-step: request → middleware → handler → database → response] ### [Flow 2: e.g. "Data Processing Pipeline"] [Step-by-step through the system] ## Configuration [Key config files and what they control] ## Deployment [How to deploy, environment variables needed, build commands]
API_ENDPOINTS.md
markdown# API Endpoints ## Base URL [e.g. `https://api.example.com` or relative `/api`] ## Authentication [Method: Bearer token, session cookie, API key, none] [Where tokens come from, how to obtain] ## Endpoints ### [Group: e.g. Users] #### `GET /api/users` - **Auth**: Required - **Params**: `?page=1&limit=20` - **Response**: `{ users: User[], total: number }` #### `POST /api/users` - **Auth**: Required (admin) - **Body**: `{ name: string, email: string }` - **Response**: `{ user: User }` (201) - **Errors**: 400 (validation), 409 (duplicate email) [Repeat for each endpoint] ## Error Format [Standard error response shape] ## Rate Limits [If applicable]
DATABASE_SCHEMA.md
markdown# Database Schema ## Engine [e.g. Cloudflare D1 (SQLite), PostgreSQL, MySQL] ## Tables ### `users` | Column | Type | Constraints | Description | |--------|------|-------------|-------------| | id | TEXT | PK | UUID | | email | TEXT | UNIQUE, NOT NULL | User email | | name | TEXT | NOT NULL | Display name | | created_at | TEXT | NOT NULL, DEFAULT now | ISO timestamp | ### `posts` [Same format] ## Relationships [Foreign keys, join patterns, cascading rules] ## Indexes [Non-primary indexes and why they exist] ## Migrations - Generate: `npx drizzle-kit generate` - Apply local: `npx wrangler d1 migrations apply DB --local` - Apply remote: `npx wrangler d1 migrations apply DB --remote` ## Seed Data [Reference to seed script if one exists]
Quality Rules
- Document what exists, not what's planned — read the actual code, don't invent endpoints or tables
- Include versions — extract from package.json/lock files, not from memory
- Show real response shapes — copy from TypeScript types or Zod schemas in the code
- Keep it scannable — tables over paragraphs, code blocks over prose
- Don't duplicate CLAUDE.md — if architecture info is already in CLAUDE.md, either move it to ARCHITECTURE.md or reference it
- Flag gaps — if you find undocumented routes or tables without clear purpose, note them with
<!-- TODO: document purpose -->
Updating Existing Docs
If docs already exist:
- Read the existing doc
- Diff against the current codebase
- Show the user what's changed (new endpoints, removed tables, updated stack)
- Apply updates preserving any hand-written notes or sections
Never silently overwrite custom content the user has added to their docs.
