Analyze a codebase and generate comprehensive onboarding documentation tailored to your audience. Produces architecture overviews, key file maps, local setup guides, common task runbooks, debugging guides, and contribution guidelines. Outputs to Markdown, Notion, or Confluence.
Analyze a codebase and generate comprehensive onboarding documentation tailored to your audience. Produces architecture overviews, key file maps, local setup guides, common task runbooks, debugging guides, and contribution guidelines. Outputs to Markdown, Notion, or Confluence.
Analyze a codebase and generate comprehensive onboarding documentation tailored to your audience. Produces architecture overviews, key file maps, local setup guides, common task runbooks, debugging guides, and contribution guidelines. Outputs to Markdown, Notion, or Confluence.
Core Capabilities
Architecture overview — tech stack, system boundaries, data flow diagrams
Key file map — what's important and why, with annotations
Local setup guide — step-by-step from clone to running tests
Common developer tasks — how to add a route, run migrations, create a component
Debugging guide — common errors, log locations, useful queries
# [Project Name]> One-sentence description of what this does and who uses it.
[](https://github.com/org/repo/actions/workflows/ci.yml)
[](https://codecov.io/gh/org/repo)
## What is this?
[2-3 sentences: problem it solves, who uses it, current state]
**Live:** https://myapp.com
**Staging:** https://staging.myapp.com
**Docs:** https://docs.myapp.com
---
## Quick Start### Prerequisites
| Tool | Version | Install |
|------|---------|---------|
| Node.js | 20+ | `nvm install 20` |
| pnpm | 8+ | `npm i -g pnpm` |
| Docker | 24+ | [docker.com](https://docker.com) |
| PostgreSQL | 16+ | via Docker (see below) |
### Setup (5 minutes)```bash
# 1. Clone
git clone https://github.com/org/repo
cd repo
# 2. Install dependencies
pnpm install
# 3. Start infrastructure
docker compose up -d # Starts Postgres, Redis
# 4. Environment
cp .env.example .env
# Edit .env — ask a teammate for real values or see Vault
# 5. Database setup
pnpm db:migrate # Run migrations
pnpm db:seed # Optional: load test data
# 6. Start dev server
pnpm dev # → http://localhost:3000
# 7. Verify
pnpm test # Should be all green
-- Find slow queries (requires pg_stat_statements)SELECT query, mean_exec_time, calls, total_exec_time
FROM pg_stat_statements
ORDERBY mean_exec_time DESC
LIMIT 20;
-- Check active connectionsSELECTcount(*), state FROM pg_stat_activity GROUPBY state;
-- Find bloated tablesSELECT relname, n_dead_tup, n_live_tup,
round(n_dead_tup::numeric/nullif(n_live_tup,0)*100, 2) AS dead_pct
FROM pg_stat_user_tables
ORDERBY n_dead_tup DESC;
Debug Authentication
# Decode a JWT (no secret needed for header/payload)echo"YOUR_JWT" | cut -d. -f2 | base64 -d | jq .
# Check session in DB
psql $DATABASE_URL -c "SELECT * FROM sessions WHERE user_id = 'usr_...' ORDER BY expires_at DESC LIMIT 5;"
Log Locations
Environment
Logs
Local dev
Terminal running pnpm dev
Vercel production
Vercel dashboard → Logs
Workers (Railway)
Railway dashboard → Deployments → Logs
Database
docker logs postgres (local)
Background jobs
pnpm worker:dev terminal
Contribution Guidelines
Branch Strategy
main → production (protected, requires PR + CI)
└── feature/PROJ-123-short-desc
└── fix/PROJ-456-bug-description
└── chore/update-dependencies
PR Requirements
Branch name includes ticket ID (e.g., feature/PROJ-123-...)
PR description explains the why
All CI checks pass
Test coverage doesn't decrease
Self-reviewed (read your own diff before requesting review)
Screenshots/video for UI changes
Commit Convention
feat(scope): short description → new feature
fix(scope): short description → bug fix
chore: update dependencies → maintenance
docs: update API reference → documentation
Code Style
# Lint + format
pnpm lint
pnpm format
# Type check
pnpm typecheck
# All checks (run before pushing)
pnpm validate
Audience-Specific Notes
For Junior Developers
Start with src/lib/auth.ts to understand authentication
Read existing tests in tests/api/ — they document expected behavior
Ask before touching anything in src/db/schema.ts — schema changes affect everyone
Use pnpm db:seed to get realistic local data
For Senior Engineers / Tech Leads
Architecture decisions are documented in docs/adr/ (Architecture Decision Records)
Performance benchmarks: pnpm bench — baseline is in tests/benchmarks/baseline.json
Security model: RLS policies in src/db/rls.sql, enforced at DB level
Scaling notes: docs/scaling.md
For Contractors
Scope is limited to src/features/[your-feature]/ unless discussed
Never push directly to main
All external API calls go through src/lib/ wrappers (for mocking in tests)
Time estimates: log in Linear ticket comments daily
