explain-codebase

What this skill does

# Explain Codebase Skill

When explaining a codebase, follow this structured process. The goal is to give someone everything they need to understand the project and start contributing confidently.

## 1. Discovery — Scan the Project

Before explaining anything, gather information:

### Project Identity
```bash
# What is this project?
cat README.md 2>/dev/null
cat package.json 2>/dev/null | grep -E '"name"|"description"|"version"'
cat pyproject.toml 2>/dev/null | head -20
cat Cargo.toml 2>/dev/null | head -20
cat go.mod 2>/dev/null | head -5
cat pom.xml 2>/dev/null | head -30
cat Gemfile 2>/dev/null | head -10
cat composer.json 2>/dev/null | grep -E '"name"|"description"'

# What does the directory structure look like?
find . -maxdepth 2 -type d ! -path '*/node_modules/*' ! -path '*/.git/*' ! -path '*/vendor/*' ! -path '*/__pycache__/*' ! -path '*/dist/*' ! -path '*/build/*' | sort
```

### Tech Stack Detection
```bash
# Languages — count lines by file type
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" -o -name "*.php" -o -name "*.swift" -o -name "*.kt" \) ! -path '*/node_modules/*' ! -path '*/vendor/*' | sed 's/.*\.//' | sort | uniq -c | sort -rn

# Framework detection
cat package.json 2>/dev/null | grep -E "react|next|vue|nuxt|angular|express|fastify|nest|svelte|remix|astro"
cat requirements.txt pyproject.toml 2>/dev/null | grep -E "django|flask|fastapi|celery|sqlalchemy"
cat Gemfile 2>/dev/null | grep -E "rails|sinatra|sidekiq"
cat go.mod 2>/dev/null | grep -E "gin|echo|fiber|chi"
cat pom.xml build.gradle 2>/dev/null | grep -E "spring|quarkus|micronaut"

# Database
cat docker-compose.yml 2>/dev/null | grep -E "postgres|mysql|mongo|redis|elasticsearch"
grep -rn "DATABASE_URL\|MONGO_URI\|REDIS_URL" .env.example .env.sample 2>/dev/null

# Infrastructure
ls Dockerfile docker-compose.yml k8s/ terraform/ .github/workflows/ .circleci/ 2>/dev/null
```

### Codebase Size
```bash
# File count and lines of code (excluding deps and build)
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" -o -name "*.php" \) ! -path '*/node_modules/*' ! -path '*/vendor/*' ! -path '*/dist/*' ! -path '*/build/*' | wc -l

# Lines of code
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" \) ! -path '*/node_modules/*' ! -path '*/dist/*' -exec cat {} + | wc -l

# Test file count
find . -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" -o -name "*_test.*" \) ! -path '*/node_modules/*' | wc -l
```

## 2. The 30-Second Overview

Start with a concise summary anyone can understand:
```
[Project Name] is a [type of application] that [what it does] for [who uses it].

Built with [primary tech stack], it [key capability 1], [key capability 2], 
and [key capability 3].

The codebase is [size: small/medium/large] with approximately [X] files 
and [X]k lines of code.
```

Example:
```
Acme Dashboard is a web application that provides real-time analytics 
and reporting for e-commerce merchants.

Built with Next.js, PostgreSQL, and Redis, it processes order data, 
generates sales reports, and sends automated alerts when metrics 
fall outside configured thresholds.

The codebase is medium-sized with approximately 320 source files 
and 45k lines of TypeScript.
```

## 3. Architecture Overview

### System Diagram

Always provide an ASCII diagram showing the major components:
```
┌─────────────────────────────────────────────────────────┐
│                        CLIENT                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │  Pages    │  │Components│  │  Hooks   │              │
│  │ (Routes)  │──│  (UI)    │──│ (State)  │              │
│  └────┬─────┘  └──────────┘  └────┬─────┘              │
│       │                           │                      │
│       └───────────┬───────────────┘                      │
│                   │ API Calls                            │
└───────────────────┼──────────────────────────────────────┘
                    │
┌───────────────────┼──────────────────────────────────────┐
│                   │        SERVER                         │
│  ┌────────────────▼───────────────┐                      │
│  │        API Layer               │                      │
│  │   (Routes / Controllers)       │                      │
│  └────────────────┬───────────────┘                      │
│                   │                                      │
│  ┌────────────────▼───────────────┐                      │
│  │       Service Layer            │                      │
│  │    (Business Logic)            │                      │
│  └───┬────────────┬───────────┬──┘                      │
│      │            │           │                           │
│  ┌───▼───┐  ┌────▼────┐  ┌──▼──────┐                   │
│  │  DB   │  │  Cache  │  │ External│                    │
│  │(Postgres)│ │(Redis) │  │  APIs   │                   │
│  └───────┘  └─────────┘  └─────────┘                    │
└──────────────────────────────────────────────────────────┘
```

### Directory Map

Explain what each top-level directory contains and WHY it's organized that way:
```
project/
├── src/
│   ├── api/          → HTTP route handlers. Validates input, calls services, returns responses.
│   │                    Does NOT contain business logic.
│   ├── services/     → Core business logic. Orchestrates operations across repositories
│   │                    and external services. This is where the "rules" live.
│   ├── db/           → Database access layer. Queries, models, migrations.
│   │                    Only layer that imports the ORM.
│   ├── models/       → TypeScript interfaces and types shared across layers.
│   │                    No runtime code — only type definitions.
│   ├── middleware/    → Express/Fastify middleware: auth, logging, rate limiting, error handling.
│   ├── utils/        → Pure utility functions. No side effects, no external dependencies.
│   ├── config/       → Configuration loading and validation. Reads from env vars.
│   ├── jobs/         → Background job definitions (queue workers, cron jobs).
│   └── lib/          → Third-party service wrappers (Stripe, SendGrid, S3).
│                        Isolates external dependencies behind clean interfaces.
├── tests/
│   ├── unit/         → Fast tests for individual functions and classes.
│   ├── integration/  → Tests that hit the database or external services.
│   └── e2e/          → End-to-end tests simulating real user flows.
├── scripts/          → Developer tooling: seed data, migrations, deploy scripts.
├── docs/             → Architecture decisions, API docs, onboarding guides.
├── infra/            → Infrastructure as code: Terraform, Kubernetes, Docker.
└── .github/          → CI/CD workflows, PR templates, issue templates.
```

## 4. Key Concepts & Domain Model

Explain the core business domain:

### Domain Entities
Identify and explain the main entities/models:
- What are they?
- How do they relate to each other?
- Where are they defined in code?
```
┌──────────┐     ┌──────────┐     ┌──────────┐
│   User   │────▶│  Order   │────▶│  Item    │
│          │ 1:N │          │ 1:N │          │
└──────────┘     └────┬─────┘     └──────────┘
                      │ 1:1
                 ┌────▼─────┐
                 │ Payment  │
                 └──────────┘
```

### Key Business Rules
List the non-obvious rules that drive behavior:
- "Orders over $100 get free shipping"
- "Users can only cancel within 24 hours"
- "Inventory is reserved at checkout, released after 30 minutes if unpaid"

### Glossary
Define project-specific terms:
| Term | Meaning | Where in Code |
|------|---------|---------------|
| Merchant | A business using our platform | `src/models/merchant.ts` |
| Fulfillm