Codebase Onboarding

When to Use

• Onboarding a new team member or contractor
• After a major refactor that made existing docs stale
• Before open-sourcing a project
• Creating a team wiki page for a service
• Self-documenting before a long vacation

Codebase Analysis Commands

Run these before generating docs to gather facts:

# Project overview
cat package.json | jq '{name, version, scripts, dependencies: (.dependencies | keys), devDependencies: (.devDependencies | keys)}'

# Directory structure (top 2 levels)
find . -maxdepth 2 -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.next/*' | sort | head -60

# Largest files (often core modules)
find src/ -name "*.ts" -not -path "*/test*" -exec wc -l {} + | sort -rn | head -20

# All routes (Next.js App Router)
find app/ -name "route.ts" -o -name "page.tsx" | sort

# All routes (Express)
grep -rn "router\.\(get\|post\|put\|patch\|delete\)" src/routes/ --include="*.ts"

# Recent major changes
git log --oneline --since="90 days ago" | grep -E "feat|refactor|breaking"

# Top contributors
git shortlog -sn --no-merges | head -10

# Test coverage summary
pnpm test:ci --coverage 2>&1 | tail -20

Generated Documentation Template

README.md — Full Template

# [Project Name]

> One-sentence description of what this does and who uses it.

[![CI](https://github.com/org/repo/actions/workflows/ci.yml/badge.svg)](https://github.com/org/repo/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/org/repo/branch/main/graph/badge.svg)](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

Verify it works

• http://localhost:3000 loads the app
• http://localhost:3000/api/health returns {"status":"ok"}
• pnpm test passes

Architecture

System Overview

Browser / Mobile
    │
    ▼
[Next.js App] ←──── [Auth: NextAuth]
    │
    ├──→ [PostgreSQL] (primary data store)
    ├──→ [Redis] (sessions, job queue)
    └──→ [S3] (file uploads)
         
Background:
[BullMQ workers] ←── Redis queue
    └──→ [External APIs: Stripe, SendGrid]

Tech Stack

Key Files

Common Developer Tasks

Add a new API endpoint

# 1. Create route handler
touch app/api/my-resource/route.ts

// app/api/my-resource/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { auth } from '@/lib/auth'
import { db } from '@/db/client'

export async function GET(req: NextRequest) {
  const session = await auth()
  if (!session) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
  
  const data = await db.query.myResource.findMany({
    where: (r, { eq }) => eq(r.userId, session.user.id),
  })
  
  return NextResponse.json({ data })
}

# 2. Add tests
touch tests/api/my-resource.test.ts

# 3. Add to OpenAPI spec (if applicable)
pnpm generate:openapi

Run a database migration

# Create migration
pnpm db:generate     # Generates SQL from schema changes

# Review the generated SQL
cat drizzle/migrations/0001_my_change.sql

# Apply
pnpm db:migrate

# Roll back (manual — inspect generated SQL and revert)
psql $DATABASE_URL -f scripts/rollback_0001.sql

Add a new email template

# 1. Create template
touch emails/my-email.tsx

# 2. Preview in browser
pnpm email:preview

# 3. Send in code
import { sendEmail } from '@/lib/email'
await sendEmail({
  to: user.email,
  subject: 'Subject line',
  template: 'my-email',
  props: { name: "username"
})

Add a background job

// 1. Define job in workers/jobs/my-job.ts
import { Queue, Worker } from 'bullmq'
import { redis } from '@/lib/redis'

export const myJobQueue = new Queue('my-job', { connection: redis })

export const myJobWorker = new Worker('my-job', async (job) => {
  const { userId, data } = job.data
  // do work
}, { connection: redis })

// 2. Enqueue
await myJobQueue.add('process', { userId, data }, {
  attempts: 3,
  backoff: { type: 'exponential', delay: 1000 },
})

Debugging Guide

Common Errors

Error: DATABASE_URL is not set

# Check your .env file exists and has the var
cat .env | grep DATABASE_URL

# Start Postgres if not running
docker compose up -d postgres

PrismaClientKnownRequestError: P2002 Unique constraint failed

User already exists with that email. Check: is this a duplicate registration?
Run: SELECT * FROM users WHERE email = '[email protected]';

Error: JWT expired

# Dev: extend token TTL in .env
JWT_EXPIRES_IN=30d

# Check clock skew between server and client
date && docker exec postgres date

500 on /api/* in local dev

# 1. Check terminal for stack trace
# 2. Check database connectivity
psql $DATABASE_URL -c "SELECT 1"
# 3. Check Redis
redis-cli ping
# 4. Check logs
pnpm dev 2>&1 | grep -E "error|Error|ERROR"

Useful SQL Queries

-- Find slow queries (requires pg_stat_statements)
SELECT query, mean_exec_time, calls, total_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 20;

-- Check active connections
SELECT count(*), state FROM pg_stat_activity GROUP BY state;

-- Find bloated tables
SELECT 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
ORDER BY 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

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