codebase-summarizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

扫描结构：递归分析文件夹树和文件组织
识别模式：检测框架、架构风格、关键目录
定位入口点：查找主文件、路由、API、CLI命令
追踪数据流：跟踪请求在各层的流转（控制器→服务→模型）
文档化模块：说明每个目录的用途和职责
创建导航：构建常见任务的操作指南
生成图表：添加Mermaid图表用于可视化架构

Documentation Structure

文档结构

ARCHITECTURE.md Template

ARCHITECTURE.md模板

markdown

undefined

markdown

undefined

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]

[项目名称]是一个基于[技术栈]构建的[类型]应用，采用[架构模式]，主要处理[核心用例]。

技术栈：

前端：[框架 + 核心库]
后端：[框架 + 核心库]
数据库：[数据库 + ORM]
基础设施：[托管服务 + CI/CD]

High-Level Architecture

高层架构

mermaid

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

undefined

mermaid

graph TB
    Client[客户端/浏览器] --> API[API层]
    API --> Services[业务逻辑]
    Services --> DB[(数据库)]
    Services --> Cache[(Redis缓存)]
    API --> Queue[消息队列]

undefined

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

src/
├── app/              # 应用入口与路由
├── components/       # 可复用UI组件
├── lib/              # 工具函数与辅助类
├── services/         # 业务逻辑层
├── models/           # 数据模型与 schema
└── types/            # TypeScript 类型定义

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

主应用：

src/app/page.tsx

应用入口文件
初始化提供者与路由
处理全局错误边界

API路由：

src/app/api/

RESTful API端点
认证中间件
请求校验

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

认证模块（
src/services/auth/
）

用户登录与注册
JWT令牌管理
OAuth2集成
依赖：bcrypt, jsonwebtoken

用户管理模块（
src/services/users/
）

用户CRUD操作
资料管理
基于角色的访问控制
依赖：Prisma、校验库

数据层（
src/models/
）

数据库schema
Prisma模型
查询构建器
依赖：Prisma Client

Data Flow

数据流

User Registration Flow

用户注册流程

mermaid

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

mermaid

sequenceDiagram
    Client->>API: POST /api/auth/register
    API->>Validation: 校验输入
    Validation->>Services: UserService.create()
    Services->>Database: 插入用户
    Database-->>Services: 用户创建完成
    Services->>Email: 发送欢迎邮件
    Services-->>API: 返回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

请求到达 → API路由处理器（
```
src/app/api/[endpoint]/route.ts
```
）
中间件处理 → 认证、校验、限流
服务层 → 业务逻辑处理（
```
src/services/
```
）
数据层 → 数据库查询（
```
src/models/
```
）
响应返回 → 格式化并返回数据

Common Patterns

常见模式

Service Pattern

服务模式

typescript

// 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
  }
}

typescript

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

  async create(data: CreateUserDto) {
    // 校验、业务逻辑、数据库操作
  }
}

Repository Pattern

仓库模式

typescript

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

typescript

// src/repositories/user.repository.ts
export class UserRepository {
  async findAll() {
    /* 仅包含数据库查询 */
  }
  async findById(id: string) {
    /* 仅包含数据库查询 */
  }
}

How To Guides

操作指南

Add a New API Endpoint

添加新API端点

Create route file:

src/app/api/[name]/route.ts

typescript

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

创建路由文件：

src/app/api/[name]/route.ts

typescript

export async function GET(req: Request) {
  // 实现逻辑
}

添加服务逻辑：
```
src/services/[name].service.ts
```
定义类型：
```
src/types/[name].ts
```
添加测试：
```
src/app/api/[name]/route.test.ts
```
更新API文档： 在OpenAPI/Swagger中添加文档

Add a New Database Model

添加新数据库模型

Update schema:

prisma/schema.prisma

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/
```

更新schema：

prisma/schema.prisma

prisma

model NewModel {
  id String @id @default(cuid())
  // 字段定义
}

执行迁移：

npx prisma migrate dev --name add-new-model

生成类型：
```
npx prisma generate
```
创建服务：
```
src/services/new-model.service.ts
```
添加CRUD路由：
```
src/app/api/new-model/
```

Add a New React Component

添加新React组件

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

创建组件：

src/components/NewComponent/NewComponent.tsx

添加样式：
```
NewComponent.module.css
```
或内联Tailwind
编写测试：
```
NewComponent.test.tsx
```
添加Story：
```
NewComponent.stories.tsx
```
（若使用Storybook）
导出组件： 更新
```
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

服务层：
```
src/services/auth/auth.service.ts
```
中间件：
```
src/middleware/auth.middleware.ts
```
路由：
```
src/app/api/auth/
```
更新测试： 确保认证流程正常工作

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

文件路径	用途	修改场景
`src/app/layout.tsx`	根布局、提供者配置	全局布局修改
`src/lib/db.ts`	数据库连接配置	连接参数调整
`src/lib/api.ts`	API客户端设置	请求拦截器配置
`src/middleware.ts`	Next.js中间件	认证、重定向逻辑
`prisma/schema.prisma`	数据库schema	数据模型修改
`.env.example`	环境变量示例	添加新配置项

Dependencies

依赖说明

Critical Dependencies

核心依赖

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

```
next
```
- React框架
```
prisma
```
- ORM与数据库工具包
```
react
```
- UI库
```
typescript
```
- 类型安全工具

Key Libraries

关键库

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

```
zod
```
- Schema校验
```
bcrypt
```
- 密码哈希
```
jsonwebtoken
```
- JWT处理
```
date-fns
```
- 日期工具

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

本地环境搭建： 参考 DEVELOPMENT.md
代码修改流程： 创建分支→实现功能→测试→提交PR
运行测试：
```
pnpm test
```
数据库变更： 遵循Prisma迁移流程
部署： Vercel自动部署

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

数据库连接错误

检查.env中的DATABASE_URL
确保数据库服务正在运行
执行
```
npx prisma generate
```

Schema变更后类型错误

执行
```
npx prisma generate
```
重启TypeScript服务

构建失败

清除.next文件夹：
```
rm -rf .next
```
清除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

undefined

API文档 - 端点参考
开发指南 - 环境搭建与工作流
贡献指南 - 代码规范
数据库Schema文档 - 数据模型细节

undefined

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

查找特征文件：

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

前端：
```
index.html
```
,
```
main.tsx
```
,
```
app.tsx
```
,
```
_app.tsx
```
后端：
```
main.ts
```
,
```
server.ts
```
,
```
app.py
```
,
```
index.js
```
CLI：
```
cli.ts
```
,
```
__main__.py
```
,
```
main.go
```

Trace Request Flow

追踪请求流

Follow typical paths:

Route/endpoint definition
Middleware/guards
Controller/handler
Service/business logic
Repository/model
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

Mermaid图表

Architecture Diagram

架构图

mermaid

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

mermaid

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

Data Flow

数据流

mermaid

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

mermaid

sequenceDiagram
    participant Client
    participant API
    participant Service
    participant DB
    Client->>API: 请求
    API->>Service: 处理
    Service->>DB: 查询
    DB-->>Service: 数据
    Service-->>API: 结果
    API-->>Client: 响应

Module Relationships

模块关系

mermaid

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

mermaid

graph TB
    API[API层] --> Auth[认证服务]
    API --> Users[用户服务]
    Auth --> DB[(数据库)]
    Users --> DB
    Users --> 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

从高层入手：先概述再细节
优先可视化：用图表展示复杂流程
内容具体：引用实际文件路径
提供示例：包含代码片段
关联相关文档：引用其他文档
保持更新：随架构演进更新文档
面向开发者：为入职和日常使用编写