./knowledge-base/docs/PROJECT_STRUCTURE.md

# Historical Research System - プロジェクト構造

```
HistorycalResearch/
│
├── README.md                              # プロジェクト概要
├── .gitignore                             # Git除外設定
├── deploy.sh                              # 自動デプロイスクリプト
├── era-list.json                          # 時代区分マスタ（元ファイル）
│
├── 仕様書_基本機能.md                      # 基本機能の詳細仕様書
├── 仕様書_基本機能_フロントエンド.md        # フロントエンド仕様書
├── 仕様書_時代考証アシスト.md              # 時代考証アシスト機能仕様（今回は未実装）
├── NHKAPIアクセスガイド.md                 # NHK AI Platform APIガイド
│
├── cdk/                                   # AWS CDKプロジェクト
│   ├── bin/
│   │   └── historical-research.ts        # CDKエントリーポイント
│   ├── lib/
│   │   └── historical-research-stack.ts  # メインCDKスタック定義
│   ├── package.json                       # Node.js依存関係
│   ├── tsconfig.json                      # TypeScript設定
│   └── cdk.json                           # CDK設定
│
├── lambda/                                # Lambda関数群
│   │
│   ├── layers/                            # Lambda Layer（共通ライブラリ）
│   │   └── common/
│   │       ├── python/
│   │       │   ├── utils.py              # ユーティリティ関数
│   │       │   └── aws_clients.py        # AWSクライアント
│   │       └── requirements.txt          # Python依存パッケージ
│   │
│   ├── upload-handler/                    # 画像アップロード処理
│   │   ├── handler.py                    # メイン処理
│   │   └── requirements.txt
│   │
│   ├── image-analyzer/                    # Claude Sonnet 4.5画像解析
│   │   ├── handler.py                    # 画像解析処理
│   │   └── requirements.txt
│   │
│   ├── embedding-generator/               # Titan Text V2エンベディング生成
│   │   ├── handler.py                    # エンベディング生成処理
│   │   └── requirements.txt
│   │
│   ├── search-api/                        # セマンティック検索API
│   │   ├── handler.py                    # 検索処理
│   │   └── requirements.txt
│   │
│   ├── bulk-processor/                    # 一括アップロード処理
│   │   ├── handler.py                    # 一括処理
│   │   └── requirements.txt
│   │
│   └── dlq-processor/                     # DLQ再処理
│       ├── handler.py                    # DLQ処理
│       └── requirements.txt
│
├── frontend/                              # Reactフロントエンド
│   ├── public/                           # 静的ファイル
│   ├── src/
│   │   ├── api/
│   │   │   └── client.ts                # APIクライアント
│   │   ├── components/                  # 共通コンポーネント（今後追加）
│   │   ├── pages/
│   │   │   ├── SearchPage.tsx          # 検索ページ
│   │   │   └── UploadPage.tsx          # アップロードページ
│   │   ├── types/
│   │   │   └── index.ts                # TypeScript型定義
│   │   ├── App.tsx                     # ルートコンポーネント
│   │   └── main.tsx                    # エントリーポイント
│   ├── index.html                       # HTMLテンプレート
│   ├── package.json                     # Node.js依存関係
│   ├── tsconfig.json                    # TypeScript設定
│   ├── vite.config.ts                   # Vite設定
│   ├── .env.example                     # 環境変数例
│   └── README.md                        # フロントエンドREADME
│
├── prompts/                               # プロンプト管理
│   ├── image-analysis/
│   │   ├── main.txt                     # 画像解析プロンプト
│   │   └── json-schema.json             # Claude出力スキーマ
│   └── master/
│       └── era-list.json                # 時代区分マスタ
│
└── docs/                                  # ドキュメント
    ├── DEPLOYMENT.md                      # 完全デプロイガイド
    └── opensearch-setup.md                # OpenSearchセットアップ
```

## 主要ファイルの説明

### CDK（インフラストラクチャ）

- **cdk/lib/historical-research-stack.ts**: すべてのAWSリソースを定義
  - S3バケット（3つ）
  - DynamoDB（処理ステータステーブル）
  - OpenSearch（ベクトル検索）
  - SQS（イメージ解析キュー、エンベディングキュー、DLQ）
  - Lambda関数（6つ）
  - API Gateway（REST API）
  - CloudFront（CDN配信）
  - VPC設定（既存VPC参照）

### Lambda関数

1. **upload-handler**: 
   - POST /process/upload - 単一画像アップロード
   - GET /process/status/{page_id} - ステータス取得

2. **image-analyzer**:
   - SQSトリガー
   - LiteLLM (Claude Sonnet 4.5)で画像解析
   - OpenSearchにドキュメント作成

3. **embedding-generator**:
   - SQSトリガー
   - OpenSearchから全属性取得
   - Bedrock Titan Text V2でエンベディング生成
   - OpenSearchに更新

4. **search-api**:
   - POST /search - テキスト検索
   - POST /search/image - 画像検索（未実装）
   - kNN検索でセマンティック検索

5. **bulk-processor**:
   - POST /process/bulk - 一括アップロード
   - 複数画像を同時処理

6. **dlq-processor**:
   - DLQトリガー
   - 失敗メッセージを再処理
   - リトライ回数管理

### フロントエンド

- **React 18 + TypeScript + Vite**
- **Material-UI v5**: UIコンポーネント
- **TanStack Query**: データフェッチング・キャッシング
- **React Router**: ルーティング

主要ページ：
- `/search`: 検索ページ
- `/upload`: アップロードページ

### プロンプトファイル

- **image-analysis/main.txt**: Claude Sonnet 4.5用プロンプト
- **image-analysis/json-schema.json**: Claude出力のJSONスキーマ
- **master/era-list.json**: 14時代区分マスタ

## データフロー

```
1. 画像アップロード
   Frontend → API Gateway → upload-handler → S3 + DynamoDB → SQS

2. 画像解析
   SQS → image-analyzer → LiteLLM(Claude) → OpenSearch → SQS

3. エンベディング生成
   SQS → embedding-generator → OpenSearch → Bedrock(Titan) → OpenSearch

4. 検索
   Frontend → API Gateway → search-api → OpenSearch(kNN) → Frontend
```

## デプロイ済みリソース

| リソース | 名前 | 説明 |
|---------|------|------|
| S3 | historical-research-images | 画像保存 |
| S3 | historical-research-web | フロントエンド配信 |
| S3 | historical-research-prompts | プロンプト管理 |
| DynamoDB | historical-research-processing-status | 処理ステータス |
| OpenSearch | historical-research-pages | ベクトル検索インデックス |
| SQS | historical-research-image-analysis-queue | 画像解析キュー |
| SQS | historical-research-embedding-queue | エンベディングキュー |
| Lambda | historical-research-* | 6つの処理関数 |
| API Gateway | historical-research-basic-api | REST API |
| CloudFront | - | CDN配信 |

## 次のステップ

1. **テストデータの投入**: サンプル画像をアップロード
2. **検索精度の検証**: セマンティック検索の精度確認
3. **プロンプトの最適化**: Claude Sonnet 4.5の出力品質向上
4. **フロントエンドの拡張**: 詳細ページ、履歴管理など
5. **時代考証アシスト機能の実装**: 次フェーズ