codebase-summarizer

コードベースの概要

リポジトリを分析し、包括的なアーキテクチャドキュメントを生成します。

コアワークフロー

1. 構造をスキャンする：フォルダーツリーとファイル構成を再帰的に分析します
2. パターンを特定する：フレームワーク、アーキテクチャスタイル、主要なディレクトリを検出します
3. エントリーポイントを把握する：メインファイル、ルート、API、CLI コマンドを見つけます
4. データフローを追跡する：リクエストをレイヤー（コントローラー → サービス → モデル）に沿って追跡します
5. モジュールをドキュメント化する：各ディレクトリの目的と責務を説明します
6. ナビゲーションを作成する：一般的なタスク向けの「方法」ガイドを作成します
7. 図を生成する：アーキテクチャを視覚化する Mermaid 図を追加します

ドキュメント構成

ARCHITECTURE.md テンプレート

# 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

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

プロジェクト構成

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/page.tsx

• アプリケーションのエントリーポイント
• プロバイダーとルーティングを初期化します
• グローバルエラーバウンダリーを処理します

API ルート： src/app/api/

• RESTful API エンドポイント
• 認証ミドルウェア
• リクエストの検証

コアモジュール

認証（src/services/auth/）

• ユーザーのログインと登録
• JWT トークンの管理
• OAuth2 の統合
• 依存関係：bcrypt、jsonwebtoken

ユーザー管理（src/services/users/）

• ユーザーの CRUD 操作
• プロファイル管理
• ロールベースのアクセス制御
• 依存関係：Prisma、検証ライブラリ

データレイヤー（src/models/）

• データベーススキーマ
• Prisma モデル
• クエリビルダー
• 依存関係：Prisma Client

データフロー

ユーザー登録フロー

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

リクエストのライフサイクル

1. リクエストを受信 → API ルートハンドラー（src/app/api/[endpoint]/route.ts）
2. ミドルウェア → 認証、検証、レート制限
3. サービスレイヤー → ビジネスロジック（src/services/）
4. データレイヤー → データベースクエリ（src/models/）
5. レスポンス → データを整形して返します

一般的なパターン

サービスパターン

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

リポジトリパターン

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

手順ガイド

新しい API エンドポイントを追加する

1. ルートファイルを作成： src/app/api/[name]/route.ts

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

2. サービスロジックを追加： src/services/[name].service.ts

3. 型を定義： src/types/[name].ts

4. テストを追加： src/app/api/[name]/route.test.ts

5. API ドキュメントを更新： OpenAPI/Swagger に記載します

新しいデータベースモデルを追加する

1. スキーマを更新： prisma/schema.prisma

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

2. マイグレーションを実行： npx prisma migrate dev --name add-new-model

3. 型を生成： npx prisma generate

4. サービスを作成： src/services/new-model.service.ts

5. CRUD ルートを追加： src/app/api/new-model/

新しい React コンポーネントを追加する

1. コンポーネントを作成： src/components/NewComponent/NewComponent.tsx
2. スタイルを追加： NewComponent.module.css またはインライン Tailwind
3. テストを作成： NewComponent.test.tsx
4. ストーリーを追加： NewComponent.stories.tsx（Storybook を使用する場合）
5. エクスポート： src/components/index.ts を更新します

認証を変更する

1. サービスレイヤー： src/services/auth/auth.service.ts
2. ミドルウェア： src/middleware/auth.middleware.ts
3. ルート： src/app/api/auth/
4. テストを更新： 認証フローが引き続き動作することを確認します

主要ファイル一覧

ファイル	目的	変更する場面
src/app/layout.tsx	ルートレイアウト、プロバイダー	グローバルレイアウトの変更
src/lib/db.ts	データベース接続	接続設定の変更
src/lib/api.ts	API クライアントの設定	リクエストインターセプター
src/middleware.ts	Next.js ミドルウェア	認証、リダイレクト
prisma/schema.prisma	データベーススキーマ	データモデルの変更
.env.example	環境変数	設定値の追加

依存関係

重要な依存関係

• next - React フレームワーク
• prisma - ORM およびデータベースツールキット
• react - UI ライブラリ
• typescript - 型安全性

主要なライブラリ

• zod - スキーマ検証
• bcrypt - パスワードのハッシュ化
• jsonwebtoken - JWT の処理
• date-fns - 日付ユーティリティ

開発ワークフロー

1. ローカル環境のセットアップ： DEVELOPMENT.md を参照してください
2. 変更の実施： ブランチ作成 → 実装 → テスト → PR
3. テストの実行： pnpm test
4. データベースの変更： Prisma のマイグレーションワークフロー
5. デプロイ： Vercel による自動デプロイ

トラブルシューティング

データベース接続エラー

• .env の DATABASE_URL を確認します
• データベースが稼働していることを確認します
• npx prisma generate を実行します

スキーマ変更後の型エラー

• npx prisma generate を実行します
• TypeScript サーバーを再起動します

ビルドの失敗

• .next フォルダーを削除します：rm -rf .next
• node_modules を削除します：rm -rf node_modules && pnpm install

追加リソース

• API ドキュメント - エンドポイントのリファレンス
• 開発ガイド - セットアップとワークフロー
• 貢献ガイド - コード規約
• データベーススキーマ - データモデルの詳細

## 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
```mermaid
graph LR
    Client --> NextJS
    NextJS --> API
    API --> Services
    Services --> Prisma
    Prisma --> PostgreSQL

データフロー

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

モジュール間の関係

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

ベストプラクティス

1. 概要から始める： 詳細の前に概要を示します
2. まず視覚化する： 複雑なフローには図を使います
3. 具体的にする： 実際のファイルパスを記載します
4. 例を示す： コードスニペットを含めます
5. 関連ドキュメントにリンクする： 他のドキュメントを参照します
6. 最新の状態に保つ： アーキテクチャの進化に合わせて更新します
7. 開発者向けにする： オンボーディングや日常的な利用を想定して記述します

出力チェックリスト

すべてのコードベースの概要に、以下を含めてください。

• システム概要と技術スタック
• 高レベルのアーキテクチャ図
• プロジェクト構造の説明
• エントリーポイントの特定
• モジュール／ディレクトリの目的
• データフロー図
• 一般的なパターンの文書化
• 一般的なタスクの「方法」ガイド
• 主要ファイルのリファレンステーブル
• 依存関係の説明
• トラブルシューティングのセクション