Codebase Summarizer

Generate comprehensive architecture documentation from repository analysis.

Core Workflow

• Scan structure: Recursively analyze folder tree and file organization

• Identify patterns: Detect framework, architecture style, key directories

• Map entry points: Find main files, routes, APIs, CLI commands

• Trace data flow: Follow requests through layers (controllers → services → models)

• Document modules: Explain purpose and responsibilities of each directory

• Create navigation: Build "how to" guides for common tasks

• Generate diagrams: Add Mermaid diagrams for visual architecture

Documentation Structure

ARCHITECTURE.md Template

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

• Request arrives → API route handler (src/app/api/[endpoint]/route.ts )

• Middleware → Auth, validation, rate limiting

• Service layer → Business logic (src/services/ )

• Data layer → Database queries (src/models/ )

• 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

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

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

Add service logic: src/services/[name].service.ts

Define types: src/types/[name].ts

Add tests: src/app/api/[name]/route.test.ts

Update API docs: Document in OpenAPI/Swagger

Add a New Database Model

Update schema: prisma/schema.prisma

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

Run migration: npx prisma migrate dev --name add-new-model

Generate types: npx prisma generate

Create service: src/services/new-model.service.ts

Add CRUD routes: src/app/api/new-model/

Add a New React Component

• Create component: src/components/NewComponent/NewComponent.tsx

• Add styles: NewComponent.module.css or inline Tailwind

• Write tests: NewComponent.test.tsx

• Add stories: NewComponent.stories.tsx (if using Storybook)

• Export: Update src/components/index.ts

Modify Authentication

• Service layer: src/services/auth/auth.service.ts

• Middleware: src/middleware/auth.middleware.ts

• Routes: src/app/api/auth/

• Update tests: Ensure auth flows still work

Key Files Reference

File Purpose Modify For

src/app/layout.tsx

Root layout, providers Global layout changes

src/lib/db.ts

Database connection Connection config

src/lib/api.ts

API client setup Request interceptors

src/middleware.ts

Next.js middleware Auth, redirects

prisma/schema.prisma

Database schema Data model changes

.env.example

Environment vars Adding config values

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

• Local setup: See DEVELOPMENT.md

• Making changes: Branch → Implement → Test → PR

• Running tests: pnpm test

• Database changes: Prisma migrate workflow

• 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 node_modules: rm -rf node_modules && pnpm install

Additional Resources

• API Documentation - Endpoint reference

• Development Guide - Setup and workflow

• Contributing Guide - Code standards

• Database Schema - 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

- Start high-level: Overview before details

- Visual first: Use diagrams for complex flows

- Be specific: Reference actual file paths

- Show examples: Include code snippets

- Link related docs: Reference other documentation

- Keep updated: Update as architecture evolves

- 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