Codebase Overview

---
name: codebase-overview
description: Explores the current repository and generates a comprehensive codebase overview — architecture, module map, data flow, infrastructure (local + production), key patterns, and onboarding context for new engineers. Use when the user says "explain this codebase", "codebase overview", "onboard me", "how does this repo work", "walk me through the code", "help me understand this project", "review this codebase", "what is this repo", "explain the architecture", "give me the big picture", "what does this codebase do", or "how is this project structured".
argument-hint: [optional-focus-area]
---

# Codebase Overview

Explore the current repository and generate a structured, progressive-depth overview suitable for onboarding a new engineer.

## Workflow

1. **Discovery — scan the repo**
   - Read `CLAUDE.md`, `README.md`, `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` (whichever exists) for project metadata
   - Run `git log --oneline -20` to understand recent activity
   - Glob for key structural files:
     - `**/docker-compose*`, `**/Dockerfile*` (containerization)
     - `**/pulumi/**`, `**/terraform/**`, `**/cdk/**` (IaC)
     - `**/.github/workflows/*`, `**/Jenkinsfile`, `**/.gitlab-ci*` (CI/CD)
     - `**/tsconfig.json`, `**/eslint*`, `**/.prettierrc*` (tooling)
     - `**/*.env.example`, `**/config.*` (configuration)
   - List top-level directories and understand the module layout
   - If `$ARGUMENTS` is provided, focus the deep-dive on that area

2. **Analysis — understand the architecture**
   - **Entry points**: Find where the application starts (main files, index files, server bootstrap)
   - **Module map**: For each top-level directory, read 1-2 key files to understand its purpose
   - **Dependencies**: Review package manifest for key dependencies and what they signal about the stack
   - **Data flow**: Trace how data moves through the system (API requests, event processing, database interactions)
   - **Infrastructure**: Identify what runs locally vs what's cloud-managed, how deploys work
   - **Configuration**: How env vars, secrets, and feature flags are managed
   - **Key patterns**: Identify architectural patterns (monorepo, microservices, event-driven, IaC, etc.)

3. **Present the overview**

   Structure the output as follows:

   ---

   ## {Project Name} — Codebase Overview

   ### What This Project Does
   1-3 sentences: what the project is, who it serves, what problem it solves.

   ### Tech Stack
   Table of: language, framework, database, cloud provider, IaC tool, CI/CD, key libraries.

   ### Repository Structure
   ```
   directory/        — purpose (1 line)
   directory/        — purpose (1 line)
   ...
   ```

   ### Architecture
   How the system is organized at a high level. Include:
   - Runtime components (services, workers, queues, databases)
   - How they communicate (HTTP, events, shared DB, etc.)
   - External integrations

   ### Module Deep-Dive
   For each major module/directory:
   - **Purpose**: What it does
   - **Key files**: 2-3 most important files and what they contain
   - **Patterns**: Notable patterns or conventions used
   - **Dependencies**: What it depends on and what depends on it

   ### Data Flow
   Walk through 1-2 key user journeys showing how data moves through the system:
   ```
   User action → API route → service → database → response
   ```

   ### Infrastructure

   #### Local Development
   - How to run locally (commands, prerequisites)
   - What services need to be running (DB, queues, etc.)
   - Key environment variables

   #### Production
   - Where it's deployed (cloud provider, services used)
   - How deploys happen (CI/CD pipeline, manual steps)
   - Infrastructure components (compute, database, networking, secrets)
   - Environment/stack separation (test, staging, production)

   ### Configuration & Secrets
   How configuration is managed:
   - Environment variables vs config files vs IaC config
   - Where secrets live and how they're accessed
   - What changes between environments

   ### Key Patterns & Conventions
   - Naming conventions
   - Error handling patterns
   - Testing approach
   - Code organization rules

   ### Gotchas & Tribal Knowledge
   Things that aren't obvious from reading the code:
   - Known pitfalls
   - Non-obvious dependencies
   - "Why is it done this way?" explanations
   - Critical settings that must not change

   ---

4. **Optional: focused deep-dive**
   - If `$ARGUMENTS` specifies a focus area (e.g., "infrastructure", "data flow", "auth"), go deeper on that topic
   - Read more files in the relevant area
   - Provide code-level detail with file paths and line references

## Guidelines

- Start broad, go deep — don't overwhelm with details upfront
- Always include file paths so the reader can navigate to source
- Prefer concrete examples over abstract descriptions
- If something is unclear from the code alone, say so rather than guessing
- Pull from CLAUDE.md, README, and inline comments for context the code can't convey
- Keep each section concise — this is a reference document, not a novel
- If the repo has documentation in a `docs/` directory, read and reference it
- Highlight anything that would surprise a new engineer or cause a production incident if misunderstood