api-user 概要

apps/app はエンドユーザー向けの REST API です。Hono + Bun で実装され、PostgreSQL をデータストアとして使用します。コード生成などの重い処理は SQS 経由で AI ワーカーに非同期委譲します。

アーキテクチャ

Routes → Services → Repositories → Database の 4 層構成です。

クライアントリクエスト
    ↓
Middlewares（認証・ログ・エラーハンドリング）
    ↓
Routes（リクエストバリデーション・レスポンス整形）
    ↓
Services（ビジネスロジック）
    ↓
Repositories（データアクセス）
    ↓
Database / 外部サービス（AWS Cognito, S3, SQS）

エンドポイント一覧

すべてのエンドポイントは /v1 プレフィックスでバージョン管理されています。

パス	担当ファイル	内容
`/v1/auth/*`	`routes/v1/auth.ts`	認証・セッション管理
`/v1/users/*`	`routes/v1/user.ts`	ユーザー管理
`/v1/organizations/*`	`routes/v1/organization.ts`	組織 CRUD
`/v1/projects/*`	`routes/v1/project.ts`	プロジェクト管理
`/v1/designs/*`	`routes/v1/design.ts`	デザインファイル管理
`/v1/code/*`	`routes/v1/code.ts`	コード操作
`/v1/des2code/*`	`routes/v1/des2code.ts`	Des2Code 操作
`/v1/organizations/:organizationId/projects/:projectId/page-imports/*`	`routes/v1/page-import.ts`	Public URL capture の作成、lifecycle polling、completed import 一覧
`/v1/organizations/:organizationId/projects/:projectId/code2des/*`	`routes/v1/code2des.ts`	Selected completed Page Import の conversion と Figma placement tracking
`/v1/organizations/:organizationId/projects/:projectId/code2wf/*`（計画中）	`routes/v1/code2wf.ts`	Code2WF生成、結果取得、Figma配置
`/v1/generated-code/*`	`routes/v1/generated-code.ts`	コード生成
`/v1/figma/*`	`routes/v1/figma.ts`	Figma API 連携
`/v1/webhooks/*`	`routes/v1/webhook.ts`	AI ワーカーからの Webhook 受信
`/v1/ping`	`routes/v1/ping.ts`	ヘルスチェック

ミドルウェアパイプライン

ミドルウェア	ファイル	役割
`requestId()`	`hono/request-id`	トレース用の一意なリクエスト ID を付与
`winstonLogger()`	`middlewares/winston-logger.ts`	リクエスト / レスポンスの構造化ログ（所要時間含む）
`cors()`	`hono/cors`	クロスオリジンリソース共有
`compress()`	`hono/compress`	Gzip レスポンス圧縮
`rateLimit()`	`middlewares/rate-limit.ts`	リクエストレート制限
`protectedRoute`	`middlewares/protected-route.ts`	JWT 検証・Cognito sub 抽出
`errorHandler`	`middlewares/error-handler.ts`	集中エラーハンドリング・統一フォーマット返却

認証フロー

sequenceDiagram
    participant User as ユーザー
    participant API as API Gateway
    participant Lambda as Lambda (api-user)
    participant Cognito as AWS Cognito

    User->>API: POST /v1/auth/login
    API->>Lambda: リクエスト転送
    Lambda->>Cognito: initiateAuth()
    Cognito-->>Lambda: JWT アクセストークン
    Lambda-->>User: 200 { token, user }

    User->>API: 保護されたエンドポイント呼び出し
    API->>Lambda: Authorization: Bearer <token>
    Lambda->>Lambda: protectedRoute ミドルウェアで JWT 検証
    Lambda-->>User: レスポンス

認可（Organization メンバーシップ検証・リソース所有権確認）はサービスレイヤーで実装します。

エラーハンドリング

すべてのエラーは以下の JSON 形式で返却されます。

{
  "error": {
    "message": "エラーの説明",
    "code": "ERROR_CODE",
    "details": {}
  }
}

ステータス	用途
`400 Bad Request`	無効な入力データ
`401 Unauthorized`	認証がないか無効
`403 Forbidden`	権限不足
`404 Not Found`	リソースが見つからない
`409 Conflict`	リソースの競合（重複など）
`500 Internal Server Error`	予期しないサーバーエラー

バリデーション

Zod スキーマでリクエストのすべての入力点を検証します。

入力種別	取得方法
リクエストボディ	`c.req.valid('json')`
パスパラメータ	`c.req.valid('param')`
クエリパラメータ	`c.req.valid('query')`

レスポンスも OpenAPI スキーマ（@hono/zod-openapi）で型安全性と契約準拠を保証します。

ロギング

すべての操作を構造化ログとして出力します。

logger.info('Operation completed', {
  operation: 'domain.action',
  duration: 123,
  requestId: 'uuid',
  userId: 'user-id',
});

レベル	用途
`info`	成功した操作
`warn`	回復可能な問題
`error`	失敗・例外
`debug`	詳細デバッグ情報（開発環境のみ）

テスト

種別	ディレクトリ	内容
ユニットテスト	`__tests__/unit/`	サービスロジック・リポジトリ操作・ユーティリティ
統合テスト	`__tests__/integration/`	リクエスト〜レスポンスのフルサイクル・DB との相互作用

bun test