Codebase Summarizer

Generate comprehensive architecture documentation from repository analysis.

Core Workflow

1. Scan structure: Recursively analyze folder tree and file organization
2. Identify patterns: Detect framework, architecture style, key directories
3. Map entry points: Find main files, routes, APIs, CLI commands
4. Trace data flow: Follow requests through layers (controllers → services → models)
5. Document modules: Explain purpose and responsibilities of each directory
6. Create navigation: Build "how to" guides for common tasks
7. Generate diagrams: Add Mermaid diagrams for visual architecture

Documentation Structure

ARCHITECTURE.md Template

````markdown

Architecture Overview

System Summary

[Project Name] is a [type] application built with [stack]. It follows [architecture pattern] and handles [primary use cases].

Tech Stack:

• Frontend: [framework + key libraries]
• Backend: [framework + key libraries]
• Database: [database + ORM]
• Infrastructure: [hosting + CI/CD]

High-Level Architecture

graph TB
    Client[Client/Browser] --> API[API Layer]
    API --> Services[Business Logic]
    Services --> DB[(Database)]
    Services --> Cache[(Redis Cache)]
    API --> Queue[Message Queue]

````

Project Structure

src/
├── app/              # Application entry point and routing
├── components/       # Reusable UI components
├── lib/              # Utility functions and helpers
├── services/         # Business logic layer
├── models/           # Data models and schemas
└── types/            # TypeScript type definitions

Key Components

Entry Points

Main Application: src/app/page.tsx

• Application entry point
• Initializes providers and routing
• Handles global error boundaries

API Routes: src/app/api/

• RESTful API endpoints
• Authentication middleware
• Request validation

Core Modules

Authentication (src/services/auth/)

• User login and registration
• JWT token management
• OAuth2 integration
• Dependencies: bcrypt, jsonwebtoken

User Management (src/services/users/)

• CRUD operations for users
• Profile management
• Role-based access control
• Dependencies: Prisma, validation libraries

Data Layer (src/models/)

• Database schemas
• Prisma models
• Query builders
• Dependencies: Prisma Client

Data Flow

User Registration Flow

sequenceDiagram
    Client->>API: POST /api/auth/register
    API->>Validation: Validate input
    Validation->>Services: UserService.create()
    Services->>Database: Insert user
    Database-->>Services: User created
    Services->>Email: Send welcome email
    Services-->>API: Return JWT
    API-->>Client: 201 Created

Request Lifecycle

1. Request arrives → API route handler (src/app/api/[endpoint]/route.ts)
2. Middleware → Auth, validation, rate limiting
3. Service layer → Business logic (src/services/)
4. Data layer → Database queries (src/models/)
5. Response → Format and return data

Common Patterns

Service Pattern

// src/services/users/user.service.ts
export class UserService {
  async findById(id: string) {
    return prisma.user.findUnique({ where: { id } });
  }

  async create(data: CreateUserDto) {
    // Validation, business logic, database operations
  }
}

Repository Pattern

// src/repositories/user.repository.ts
export class UserRepository {
  async findAll() {
    /* DB queries only */
  }
  async findById(id: string) {
    /* DB queries only */
  }
}

How To Guides

Add a New API Endpoint

1. Create route file: src/app/api/[name]/route.ts

``typescript export async function GET(req: Request) { // Implementation } ``

1. Add service logic: src/services/[name].service.ts
2. Define types: src/types/[name].ts
3. Add tests: src/app/api/[name]/route.test.ts
4. Update API docs: Document in OpenAPI/Swagger

Add a New Database Model

1. Update schema: prisma/schema.prisma

``prisma model NewModel { id String @id @default(cuid()) // fields } ``

1. Run migration: npx prisma migrate dev --name add-new-model
2. Generate types: npx prisma generate
3. Create service: src/services/new-model.service.ts
4. Add CRUD routes: src/app/api/new-model/

Add a New React Component

1. Create component: src/components/NewComponent/NewComponent.tsx
2. Add styles: NewComponent.module.css or inline Tailwind
3. Write tests: NewComponent.test.tsx
4. Add stories: NewComponent.stories.tsx (if using Storybook)
5. Export: Update src/components/index.ts

Modify Authentication

1. Service layer: src/services/auth/auth.service.ts
2. Middleware: src/middleware/auth.middleware.ts
3. Routes: src/app/api/auth/
4. Update tests: Ensure auth flows still work

Key Files Reference

Dependencies

Critical Dependencies

• next - React framework
• prisma - ORM and database toolkit
• react - UI library
• typescript - Type safety

Key Libraries

• zod - Schema validation
• bcrypt - Password hashing
• jsonwebtoken - JWT handling
• date-fns - Date utilities

Development Workflow

1. Local setup: See [DEVELOPMENT.md](DEVELOPMENT.md)
2. Making changes: Branch → Implement → Test → PR
3. Running tests: pnpm test
4. Database changes: Prisma migrate workflow
5. Deployment: Vercel automatic deployment

Troubleshooting

Database connection errors

• Check DATABASE_URL in .env
• Ensure database is running
• Run npx prisma generate

Type errors after schema changes

• Run npx prisma generate
• Restart TypeScript server

Build fails

• Clear .next folder: rm -rf .next
• Clear nodemodules: rm -rf nodemodules && pnpm install

Additional Resources

• [API Documentation](./API.md) - Endpoint reference
• [Development Guide](./DEVELOPMENT.md) - Setup and workflow
• [Contributing Guide](./CONTRIBUTING.md) - Code standards
• [Database Schema](./DATABASE.md) - Data model details

````

Analysis Techniques

Identify Framework

Look for telltale files:

• next.config.js → Next.js
• vite.config.ts → Vite
• nest-cli.json → NestJS
• manage.py → Django
• Cargo.toml → Rust

Map Entry Points

• Frontend: index.html, main.tsx, app.tsx, _app.tsx
• Backend: main.ts, server.ts, app.py, index.js
• CLI: cli.ts, main.py, main.go

Trace Request Flow

Follow typical paths:

1. Route/endpoint definition
2. Middleware/guards
3. Controller/handler
4. Service/business logic
5. Repository/model
6. Database query

Module Categories

• Core: Essential business logic
• Infrastructure: Database, cache, queue
• Utilities: Helpers, formatters, validators
• Features: User-facing functionality
• Config: Environment, settings

Mermaid Diagrams

Architecture Diagram

graph LR
    Client --> NextJS
    NextJS --> API
    API --> Services
    Services --> Prisma
    Prisma --> PostgreSQL
````

### Data Flow

sequenceDiagram participant Client participant API participant Service participant DB Client->>API: Request API->>Service: Process Service->>DB: Query DB-->>Service: Data Service-->>API: Result API-->>Client: Response

### Module Relationships

graph TB API[API Layer] --> Auth[Auth Service] API --> Users[User Service] Auth --> DB[(Database)] Users --> DB Users --> Cache[(Cache)]

## Best Practices

1. **Start high-level**: Overview before details
2. **Visual first**: Use diagrams for complex flows
3. **Be specific**: Reference actual file paths
4. **Show examples**: Include code snippets
5. **Link related docs**: Reference other documentation
6. **Keep updated**: Update as architecture evolves
7. **Developer-focused**: Write for onboarding and daily use

## Output Checklist

Every codebase summary should include:

- [ ] System overview and tech stack
- [ ] High-level architecture diagram
- [ ] Project structure explanation
- [ ] Entry points identification
- [ ] Module/directory purposes
- [ ] Data flow diagrams
- [ ] Common patterns documented
- [ ] "How to" guides for common tasks
- [ ] Key files reference table
- [ ] Dependencies explanation
- [ ] Troubleshooting section