---
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)

```bash
# 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

```markdown
# 📦 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:
```bash
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](https://github.com/suryast/free-ai-agent-skills) · 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:
```bash
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:
```bash
cat go.mod go.sum
find . -name "main.go" | head -5
```

**Monorepos** — structure overview first, then recurse into each package:
```bash
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.)