project-docs

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:

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

# Architecture

API_ENDPOINTS.md

DATABASE_SCHEMA.md

Quality Rules

1. Document what exists, not what's planned — read the actual code, don't invent endpoints or tables
2. Include versions — extract from package.json/lock files, not from memory
3. Show real response shapes — copy from TypeScript types or Zod schemas in the code
4. Keep it scannable — tables over paragraphs, code blocks over prose
5. Don't duplicate CLAUDE.md — if architecture info is already in CLAUDE.md, either move it to ARCHITECTURE.md or reference it
6. 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:

1. Read the existing doc
2. Diff against the current codebase
3. Show the user what's changed (new endpoints, removed tables, updated stack)
4. Apply updates preserving any hand-written notes or sections

Never silently overwrite custom content the user has added to their docs.