explain-codebase

name	explain-codebase
version	1.0.0
author	Polycat
tags	["codebase","architecture","onboarding","documentation","analysis"]
license	MIT
platform	universal
description	Drop into any repo and generate a structured architecture overview. Maps the codebase, identifies entry points, frameworks, and dependencies — then produces a "start here" guide for new contributors.

🗺️ Explain Codebase

Compatible with Claude Code, Codex CLI, Cursor, Windsurf, and any SKILL.md-compatible agent.

Drop into any unfamiliar repository and generate a complete architectural overview in minutes. Maps directory structure, identifies entry points and frameworks, explains dependencies, and produces a contributor-ready "start here" guide.

---

Triggers

Activate this skill when:

• User drops into an unfamiliar repo and asks what it does
• "explain this codebase", "give me an overview", "what does this project do"
• "architecture overview", "how is this structured", "where do I start"
• "onboarding guide", "explain the code", "map this repo"
• Starting work on a new project or PR
• Before a refactor that needs full system understanding

---

How It Works

Run these exploration commands first, then synthesize into a structured overview.

Phase 1: Recon (run these commands)

# 1. Top-level structure
ls -la

# 2. Directory tree (exclude noise)
find . -type d \
  ! -path './.git/*' \
  ! -path './node_modules/*' \
  ! -path './.venv/*' \
  ! -path './venv/*' \
  ! -path './__pycache__/*' \
  ! -path './dist/*' \
  ! -path './build/*' \
  ! -path './.next/*' \
  | sort | head -80

# 3. Key config files (reveal framework & toolchain)
ls -la *.json *.toml *.yaml *.yml *.lock *.cfg *.ini 2>/dev/null | head -30

# 4. Dependency file contents
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat Cargo.toml 2>/dev/null || cat go.mod 2>/dev/null || cat pom.xml 2>/dev/null

# 5. Entrypoints — where does execution start?
grep -r "if __name__.*__main__" --include="*.py" -l 2>/dev/null | head -10
ls -la main.* index.* app.* server.* cmd.* 2>/dev/null

# 6. README and docs
cat README.md 2>/dev/null || cat README.rst 2>/dev/null | head -100

# 7. Docker / deployment clues
cat Dockerfile 2>/dev/null | head -40
cat docker-compose.yml 2>/dev/null | head -40

# 8. CI/CD
ls .github/workflows/ 2>/dev/null
ls .gitlab-ci.yml .circleci/ .travis.yml 2>/dev/null

# 9. Test structure
find . -name "test_*.py" -o -name "*.test.ts" -o -name "*.spec.js" 2>/dev/null | head -20

# 10. Size overview — what's actually big?
find . -type f \
  ! -path './.git/*' \
  ! -path './node_modules/*' \
  ! -path './.venv/*' \
  | xargs wc -l 2>/dev/null | sort -rn | head -20

Phase 2: Deep Dive (read these files)

After recon, read the most important files:

1. Main entrypoint(s) identified above
2. Core library / src directory (skim for class/function names)
3. Config files (understand environment expectations)
4. Any core/, lib/, common/, or shared/ directory
5. Database models or schema files
6. API route definitions

Phase 3: Synthesize

Produce the structured overview below.

---

Output Format

# 📦 Codebase Overview: [Project Name]

> Generated by explain-codebase skill | [date]

## What This Project Does

[2–3 sentence plain-English description. What problem does it solve? Who uses it?]

---

## Tech Stack

| Layer | Technology | Notes |
|-------|-----------|-------|
| Language | Python 3.11 | |
| Framework | FastAPI | REST API |
| Database | PostgreSQL | via SQLAlchemy ORM |
| Cache | Redis | session + rate limiting |
| Frontend | React 18 | Vite, TypeScript |
| Testing | pytest | + httpx for API tests |
| CI/CD | GitHub Actions | deploy on push to main |
| Container | Docker + Compose | dev + prod configs |

---

## Repository Structure

project/ ├── src/ # Main application code │ ├── api/ # HTTP route handlers │ │ ├── auth.py # Login, JWT, session │ │ └── users.py # User CRUD endpoints │ ├── core/ # Business logic (no I/O) │ │ ├── models.py # SQLAlchemy ORM models │ │ └── services.py # Service layer │ ├── db/ # Database setup │ │ └── migrations/ # Alembic migrations │ └── main.py # ← ENTRYPOINT: FastAPI app ├── tests/ # Test suite │ ├── unit/ # Pure logic tests │ └── integration/ # API + DB tests ├── frontend/ # React SPA │ ├── src/ │ │ ├── components/ # Reusable UI │ │ ├── pages/ # Route-level pages │ │ └── main.tsx # ← ENTRYPOINT: React root │ └── package.json ├── Dockerfile # Production container ├── docker-compose.yml # Dev environment ├── pyproject.toml # Python deps + tool config └── .env.example # Required environment vars

---

## Entry Points

| What | File | How to Run |
|------|------|------------|
| API server | `src/main.py` | `uvicorn src.main:app --reload` |
| Frontend dev | `frontend/src/main.tsx` | `cd frontend && npm run dev` |
| DB migrations | `src/db/migrations/` | `alembic upgrade head` |
| Tests | `tests/` | `pytest tests/` |
| Production | `Dockerfile` | `docker-compose up` |

---

## Key Dependencies

| Package | Role | Why it matters |
|---------|------|----------------|
| fastapi | Web framework | Async HTTP, OpenAPI docs auto-generated |
| sqlalchemy | ORM | Database models + query builder |
| alembic | DB migrations | Schema versioning |
| pydantic | Data validation | Request/response models |
| httpx | HTTP client | Internal + external API calls |
| pytest | Test runner | Unit + integration tests |
| redis-py | Cache client | Session storage, rate limiting |

---

## Data Flow

HTTP Request ↓ FastAPI Router (src/api/) ↓ Pydantic validation ↓ Service layer (src/core/services.py) ↓ SQLAlchemy ORM (src/core/models.py) ↓ PostgreSQL ←→ Redis (cache) ↓ Pydantic response model ↓ HTTP Response

---

## Environment Variables

Required (see `.env.example`):
```bash
DATABASE_URL=postgresql://user:pass@localhost/dbname
REDIS_URL=redis://localhost:6379
SECRET_KEY=your-jwt-secret
API_PORT=8000

Optional:

LOG_LEVEL=INFO
SENTRY_DSN=                    # Error tracking
MAX_CONNECTIONS=10             # DB pool size

---

Where to Start 🚀

New contributor quick path:

1. Understand the domain: Read README.md + skim src/core/models.py (data model = mental model)
2. Run it locally: docker-compose up or follow docs/local-setup.md
3. Explore the API: Hit http://localhost:8000/docs (auto-generated Swagger)
4. Read the tests: tests/integration/test_api.py shows how every endpoint behaves
5. Find your first task: Search TODO, FIXME, HACK in src/ — or check open issues

Files to read first (in order):

1. src/main.py — app wiring, middleware, routers
2. src/core/models.py — data structure
3. src/api/ — pick one route file, trace a request end-to-end
4. tests/integration/ — see expected behavior

---

Potential Gotchas

• [List any non-obvious things: env var requirements, DB setup steps, version constraints]
• [e.g., "Requires PostgreSQL 14+ for JSONB features used in models.py"]
• [e.g., "Frontend expects API at /api/ — set VITE_API_URL in frontend/.env"]

---

Architecture Decisions Worth Knowing

• [Why X was chosen over Y, if evident from comments/docs/commit messages]
• [Any known tech debt: "The auth module is being rewritten — don't extend it"]
• [Anything that surprised you during analysis]

---

Generated by explain-codebase · MIT License

---

## Adaptation Notes

### For different project types

**Node/TypeScript projects** — also check:
```bash
cat tsconfig.json
cat .eslintrc* .prettierrc* 2>/dev/null
ls src/ lib/ app/ pages/ components/ 2>/dev/null

Python projects — also check:

cat setup.py setup.cfg pyproject.toml requirements*.txt 2>/dev/null
python -c "import ast, sys; [print(f.__name__) for f in ast.walk(ast.parse(open('main.py').read())) if isinstance(f, ast.FunctionDef)]" 2>/dev/null

Go projects — also check:

cat go.mod go.sum
find . -name "main.go" | head -5

Monorepos — structure overview first, then recurse into each package:

ls packages/ apps/ libs/ services/ 2>/dev/null

Keep it honest

• If you can't determine something, say "unclear from static analysis — check [specific file/URL]"
• Don't invent architectural decisions you didn't observe
• If the codebase is messy, say so — "no clear separation of concerns in src/" is useful information
• Flag anything that looks like a security issue (hardcoded secrets, missing auth, etc.)