Understand Codebase Command

Command

/understand

Description

Analyzes the project structure and generates a comprehensive codebase overview. Designed for new team members, code reviewers, or anyone who needs to quickly understand how a project is organized, what patterns it uses, and where to find things.

Behavior

Arguments

• $ARGUMENTS -- Optional focus area (e.g., "authentication flow", "database layer", "API routes")

Analysis Steps

1. Project Identity:

   • Read package.json, pyproject.toml, Cargo.toml, or equivalent
   • Identify the language, framework, and key dependencies
   • Determine the project type (API server, web app, CLI tool, library, monorepo)

2. Directory Structure:

   Copy
   # Map the project layout
   find . -type f -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.py' | \
     head -100 | sort

   Explain what each top-level directory contains and why.

3. Architecture Pattern:

   • MVC, Clean Architecture, Hexagonal, Feature-based?
   • Where does business logic live?
   • How are layers separated?
   • What's the dependency direction?

4. Entry Points:

   • Main entry file(s)
   • Route definitions (for web apps/APIs)
   • CLI command definitions (for CLI tools)
   • Export surface (for libraries)

5. Key Abstractions:

   • Core types/interfaces that appear everywhere
   • Base classes or shared utilities
   • Configuration patterns
   • Error handling approach

6. Data Flow:

   • How does a request flow through the system?
   • What middleware/interceptors are in the pipeline?
   • How is state managed?
   • Where does data validation happen?

7. Testing Strategy:

   • Test runner and framework
   • Test file naming convention
   • Fixture/factory patterns
   • Coverage configuration

Output Format

Copy
## Codebase Overview: MyApp

### Identity
- **Type**: REST API server
- **Language**: TypeScript 5.3
- **Framework**: Express.js 4.18
- **Database**: PostgreSQL via Prisma ORM
- **Auth**: JWT with refresh tokens

### Project Structure

src/ controllers/ # HTTP request handlers (thin layer) services/ # Business logic (core layer) repositories/ # Database access (data layer) middleware/ # Auth, validation, error handling types/ # Shared TypeScript interfaces utils/ # Pure utility functions prisma/ schema.prisma # Database schema migrations/ # SQL migration files tests/ unit/ # Fast, isolated tests integration/ # Tests with database

### Request Flow

Client -> middleware/auth.ts -> controllers/userController.ts -> services/userService.ts -> repositories/userRepository.ts -> Prisma -> PostgreSQL

### Key Files to Read First
1. `src/app.ts` -- Express setup, middleware chain, route mounting
2. `src/types/index.ts` -- Core TypeScript interfaces
3. `src/services/userService.ts` -- Typical service pattern example
4. `prisma/schema.prisma` -- Database schema and relations

### Patterns & Conventions
- Controllers are thin: validate input, call service, format response
- Services contain all business logic and throw custom errors
- Repositories are Prisma wrappers for complex queries
- All errors are caught by errorMiddleware and formatted consistently

Examples

Copy
# Full codebase overview
/understand

# Focus on a specific area
/understand the authentication and authorization flow

# Understand the database layer
/understand database schema and data access patterns

# Understand the testing setup
/understand testing strategy and how to write new tests