Components — continuum

Project: continuum Phase: INCEPTION — Application Design Date: 2026-05-08 Depth: Comprehensive

Note: 本ドキュメントはコンポーネントの 高レベル責務とインターフェース を定義する。各コンポーネントの詳細業務ルール・入出力データ構造の精緻化は Functional Design（Construction Phase per-unit） で実施する。

0. Architectural Overview

0.1 アーキテクチャスタイル

• Backend: Serverless First（AWS Lambda + API Gateway + DynamoDB） — Q1=A
• Frontend: Vite + React + S3 + CloudFront（PWA: Service Worker は手動実装 / Workbox） — Q2=B
• Service 境界粒度: Per-Use-Case 中粒度（Lambda 8-12個） — Q3=C
• 通信パターン: Hybrid（Sync REST 主 / EventBridge 非同期） — Q4=C
• データストア: DynamoDB Single-Table Design — Q5=A
• リアルタイム: API Gateway WebSocket API — Q6=A
• AI 基盤: Amazon Bedrock + AgentCore（Runtime / Memory / Identity / Gateway / Browser Tool） — Q7=ABCDE
• 認証: Cognito User Pool + JWT — Q8=A
• ロギング: Phase 2 Minimal / Phase 3 + X-Ray — Q9=D
• リポジトリ: Monorepo — Q10=A

0.2 3層アーキテクチャ（要件定義 §2 由来）

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (PWA)                           │
│  Vite + React + Service Worker / S3 + CloudFront                │
└──────────────────┬──────────────────┬──────────────────┬────────┘
                   │ REST             │ WebSocket        │
                   v                  v                  │
┌──────────────────────────────────────────────────────┐ │
│            API Gateway (REST + WebSocket)            │ │
└──────────────────┬───────────────────────────────────┘ │
                   │                                     │
   ┌───────────────┴────────────────────────────────┐    │
   │                                                │    │
   v                                                v    │
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│  Inbound Arm     │  │  Outbound Arm    │  │  Federated Layer │
│  (FR-2)          │  │  (FR-8)          │  │  (FR-9 MACP)     │
│  - Response Gen  │  │  - Outreach Sched│  │  - Peer Discovery│
│  - Variations    │  │  - Heartbeat     │  │  - Negotiation   │
│  - Calibration   │  │  - Plausibility  │  │  - Theatrical    │
└────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘
         │                     │                      │
         v                     v                      v
┌──────────────────────────────────────────────────────────────┐
│   Cross-Cutting: Maturity Phase Manager (FR-7) Lv1〜Lv5      │
└────────┬─────────────────────────────────────────────────────┘
         │
         v
┌──────────────────────────────────────────────────────────────┐
│   Foundation: Auth / Profile / Contact / Mock Feed / Dashbd  │
└────────┬─────────────────────────────────────────────────────┘
         │
         v
┌──────────────────────────────────────────────────────────────┐
│   Persistence: DynamoDB Single-Table  /  EventBridge  /      │
│                AgentCore Memory  /  Bedrock                  │
└──────────────────────────────────────────────────────────────┘

1. Component Inventory

合計 18 コンポーネント を識別。論理層別に整理：

2. Frontend Components 詳細

C-FE-01: WebApp (PWA Shell)

責務:

• アプリ全体のルーティング (React Router)
• グローバル状態管理（React Context / Zustand）
• Service Worker 登録（オフライン最低限のキャッシュ + マニフェスト）
• 共通 UI レイアウト（ナビバー、サイドバー、フッタ）
• 各 View へのスクリーンディスパッチ

インターフェース:

• 入力: ブラウザ URL, ユーザー操作イベント
• 出力: HTML 描画, 各 View へのレンダリング委譲

依存: 全 Frontend View コンポーネント, AuthUI

C-FE-02: AuthUI

責務:

• サインアップ画面（メール・パスワード・表示名）
• ログイン画面
• ログアウト処理
• JWT トークンの localStorage 管理 + 自動更新
• 認証ステートをグローバルに公開

インターフェース:

• 入力: ユーザー入力（メール・パスワード）
• 出力: Cognito User Pool への認証リクエスト, JWT を保持

依存: AWS Amplify Auth ライブラリ, AuthHandler API

C-FE-03: InboxView

責務:

• 受信メッセージの時系列リスト表示（FR-1, US-3.1）
• メッセージ詳細表示（送信者・本文・関係性）
• 応答生成リクエスト送信 → 3バリエーション表示（FR-2, US-3.2）
• 案選択 + 編集UI（Lv1 慎重期のみ — US-3.3）
• 案送信操作
• Maturity Phase に応じた UI 切替（Lv1: 全表示 / Lv2: 確率的スキップ / Lv3: Critical のみ表示 / Lv4-5: 表示なし）

インターフェース:

• 入力: ユーザー操作（開く・選択・編集・送信）
• 出力: InboundResponseEngine API 呼び出し, 状態更新

依存: InboundResponseEngine, MaturityPhaseManager（フェーズ取得）

C-FE-04: OutboundReviewView

責務:

• Outbound 候補（Strategic Outreach + Heartbeat）のレビューUI（US-4.6）
• 送信前の編集・破棄・承認操作（Lv1 慎重期）
• Lv2 信頼期では 70% のみ表示
• 自動送信履歴の閲覧

依存: OutboundOrchestrator, MaturityPhaseManager

C-FE-05: DashboardView

責務:

• KPIカード表示（Responses Delegated / Time Reclaimed / Streak / Score / Current Phase — US-6.1）
• Maturity Certification バッジ表示（US-6.2）
• Outbound メトリクス（Optimal Window Hit Rate / Relationship Health Score / Engagement Coverage — US-6.3）
• Days in Nirvana 表示（Lv5 専用 — US-6.4）
• Maturity Recommendation バナー表示（US-5.6）

依存: DashboardEngine

C-FE-06: MaturitySettingsView

責務:

• 現在のフェーズ表示
• Lv1〜Lv4 への手動切替UI（確認モーダル付き — US-5.4）
• "Advanced Delegation Options" セクション（Lv4 自己有効化トグル）
• Lv5 認定状態表示（読み取り専用）

依存: MaturityPhaseManager

C-FE-07: DemoSetPieceView

責務:

• 決勝デモ用 Split-Screen UI（DS-1, DS-3）
• 左右分割: UserA / UserB の同期画面
• 下部: Inter-Agent Negotiation Log（JSON ストリーム）
• タイムラプス再生制御
• 締めナレーション + ロゴ演出（DS-4）

依存: WebSocketClient, MACPCoordinator

C-FE-08: WebSocketClient

責務:

• API Gateway WebSocket への接続管理
• 接続維持（heartbeat）
• 受信メッセージの dispatch（DemoSetPieceView や InboxView へ）
• 切断時の再接続

依存: API Gateway WebSocket

3. Backend Components 詳細

C-BE-01: AuthHandler

責務:

• Cognito User Pool との連携
• ユーザープロファイル CRUD（表示名・Default Communication Style）
• JWT 検証ミドルウェア提供
• サインアップ後の初期化（プロファイル作成・初期 Maturity Phase = Lv1 設定）

インターフェース:

• HTTP API: POST /auth/signup, POST /auth/login, GET /me, PUT /me

依存: Cognito User Pool, DynamoDB Single-Table

C-BE-02: ContactHandler

責務:

• コンタクト CRUD（FR-4 / US-2.1）
• Engagement Cadence 設定（US-2.2）
• Critical タグ管理（US-2.3）
• Mock Social Feed への紐付け管理

インターフェース:

• HTTP API: GET /contacts, POST /contacts, PUT /contacts/{id}, DELETE /contacts/{id}

依存: DynamoDB Single-Table

C-BE-03: InboundResponseEngine

責務:

• 受信メッセージへの 3バリエーション応答生成（FR-2 / US-3.2, US-3.4）
  • Conservative: 丁重・慎重・間接的辞退・次回示唆
  • Pragmatic: 簡潔・効率的
  • Cordial: 温度感ある気遣い・絵文字含む
• Relational Calibration（US-3.5）: 関係カテゴリに応じたトーン調整
• Plausibility Constraint: 案間の文字列類似度 0.7 以下を担保（US-3.4）
• 過去応答履歴を AgentCore Memory から取得し Context Injection
• Bedrock LLM への Prompt Template 管理

インターフェース:

• HTTP API: POST /inbound/{messageId}/generate → 3案返却
• HTTP API: POST /inbound/{messageId}/send → 選択した案を送信完了状態へ

依存: Bedrock, AgentCore Runtime, AgentCore Memory, MaturityPhaseManager（Lv1判定）, ContactHandler（プロファイル取得）

C-BE-04: OutboundOrchestrator

責務:

• Strategic Outreach Scheduling（FR-8.1）: SignalExtractor から Window 取得 → 誘い文生成 → 送信スケジュール（EventBridge 経由）
• Engagement Heartbeat（FR-8.2）: Cadence 別の定期送信スケジューリング + Content Diversity 担保
• Conflict Detection & Coherence Layer（FR-8.3）: Inbound-Outbound 整合性 + 重複回避
• Plausibility Engineering（FR-8.4）: 時刻分散 + 文体学習 + Context Echo + Restraint
• Maturity Phase 連動: Lv1 全レビュー / Lv2 30%スキップ / Lv3 Critical 以外自動 / Lv4-5 全自動

インターフェース:

• HTTP API: GET /outbound/pending, POST /outbound/{id}/approve, POST /outbound/{id}/reject
• EventBridge Subscriber: outbound.scheduled.send イベント受信
• Internal: SignalExtractor へクエリ

依存: SignalExtractor, Bedrock, AgentCore Memory, MaturityPhaseManager, ContactHandler, EventBridge

C-BE-05: SignalExtractor

責務:

• Mock Social Feed の解析（FR-8.5 / US-4.1, US-4.7）
• Signal Extraction Pipeline 実行:
  1. Ingestion（モックデータ取得）
  2. Normalization
  3. Bedrock LLM による NER + 意図理解
  4. Confidence Scoring（0〜1）
  5. Window Aggregation
  6. DynamoDB 永続化
• 5種別の Signal Categories 対応（Explicit / Implicit / Inferred / Predictive / Cross-Source Triangulation）
• Cross-Source Triangulation で Confidence 上昇

インターフェース:

• Internal API: extractSignals(contactId) → Window[]
• Internal API: getOptimalWindows(contactId, threshold) → Window[]

依存: Bedrock, DynamoDB Single-Table

C-BE-06: MaturityPhaseManager

責務:

• 現在の Maturity Phase 状態保持（FR-7 / US-5.1〜5.6）
• フェーズ移行ロジック（手動切替 / Recommendation 表示 / Lv4 自己有効化 / Lv5 自動認定）
• 累計応答件数の追跡 + Recommendation トリガー判定（5/20件閾値）
• Lv5 認定条件チェック（Lv4 で 30日連続 + アプリ起動 7日以上ない）
• Lv5 → Lv4 自動降格（アプリ再起動時）
• 各フェーズの Inbound/Outbound 動作判定をロジック化

インターフェース:

• HTTP API: GET /maturity/status, PUT /maturity/phase, POST /maturity/activate-autonomous
• Internal API: shouldReviewInbound(messageId) → boolean
• Internal API: shouldReviewOutbound(outboundId) → boolean
• EventBridge Subscriber: maturity.daily.check イベント受信（Nirvana 認定）

依存: DynamoDB Single-Table, EventBridge

C-BE-07: MACPCoordinator

責務（FR-9）:

• Peer Discovery（FR-9.2 / US-7.1）: AgentCore Identity による他テナントの存在確認（片方向ハッシュ）
• Inter-Agent Negotiation（FR-9.3 / US-7.2）: AgentCore Gateway 経由の合意形成プロトコル
• Theatrical Performance Director（FR-9.4 / US-7.3）: 合意済み脚本の各メッセージを EventBridge スケジュール送信
• Outcome Confirmation（FR-9.5 / US-7.4）: バッジ同期付与 + Memory 永続化
• Failure Handling（US-7.5）: タイムアウト / 認証失敗時の通常 Outbound への復帰

インターフェース:

• Internal API: attemptMACP(outboundCandidate) → MACPSession | null
• HTTP API: POST /macp/negotiate (cross-tenant via AgentCore Gateway)
• EventBridge Subscriber: macp.theater.send イベント受信

依存: AgentCore Identity, AgentCore Gateway, AgentCore Memory, Bedrock, OutboundOrchestrator, EventBridge

C-BE-08: DashboardEngine

責務:

• KPI 集計（Responses Delegated / Time Reclaimed / Streak / Score — US-6.1）
• Maturity Certification バッジ管理（US-6.2 / 各レベル初到達でバッジ付与）
• Outbound メトリクス算出（Optimal Window Hit Rate / Relationship Health Score / Engagement Coverage — US-6.3）
• Days in Nirvana 計算（US-6.4）
• Maturity Recommendation バナーの表示判定（5件 / 20件閾値）

インターフェース:

• HTTP API: GET /dashboard/kpi, GET /dashboard/badges, GET /dashboard/recommendations

依存: DynamoDB Single-Table, MaturityPhaseManager

C-BE-09: WebSocketBroker

責務:

• API Gateway WebSocket 接続イベント処理（$connect / $disconnect / $default）
• 接続情報の DynamoDB 永続化
• 特定ユーザー / 全ユーザーへのメッセージ配信
• 決勝デモ用の MACP リアルタイムイベント配信

インターフェース:

• WebSocket Routes: $connect, $disconnect, $default
• Internal API: pushToUser(userId, event), broadcastDemo(event)

依存: DynamoDB Single-Table（Connection Table）, MACPCoordinator（イベント源）

C-BE-10: MockSocialFeedSeeder

責務:

• ハッカソンデモ用の Mock Social Feed データを DynamoDB に事前投入（FR-8.5.4 / US-4.7）
• Phase 2: 3 コンタクト × 各 2 投稿 = 合計 6 投稿（Mock X + Mock Instagram Story の 2 プラットフォーム）— Explicit Unavailability 中心
• Phase 3: 5〜10 名のサンプルコンタクトに対し、5 種別 Signal Categories 全網羅のサンプル投稿を投入（Mock LinkedIn / Mock TimeTree 等を追加）
• Phase 2 の 2 プラットフォーム構成は「テキスト + 位置タグ付き画像」の最小限の裏取り演出を狙う（Cross-Source Triangulation は Phase 3 Stretch）

インターフェース:

• CLI: seed-mock-feed.sh （CDK Deploy 時のカスタムリソース or 手動実行）

依存: DynamoDB Single-Table

4. Component Boundaries Rationale

4.1 なぜ Per-Use-Case 中粒度（10 コンポーネント / Lambda）？

• 粗粒度すぎる場合のリスク: 1つの Lambda が肥大化、IAM ロールが過度になる、責務不明瞭
• 細粒度すぎる場合のリスク: 管理オーバーヘッド増加、ハッカソン2週間 MVP 制約と不整合
• 中粒度の利点: ユースケース単位で責務明確、独立デプロイ可能、AI フル実装で並列開発しやすい

4.2 Frontend / Backend の境界

• Frontend は表示・操作のみ、ビジネスロジックは Backend に集中
• Frontend は API 呼び出しと状態管理に専念
• 認証は Cognito SDK を Frontend で利用、JWT 取得後に Backend を呼ぶ

4.3 Inbound / Outbound / Federated の3層分離

• 各層が独立した責務を持ち、Maturity Phase Manager が横断的に制御
• 3層は要件定義 §2 のアーキテクチャに直接対応
• MACP（Federated）は Single-Tenant 簡易版（Phase 2）と Federated 本実装（Phase 3）で実装が異なるが、コンポーネント境界は同一

4.4 Maturity Phase Manager の cross-cutting 配置

• Inbound, Outbound, Federated すべてが Maturity Phase に応じて挙動を変える
• 単一の真実の源として MaturityPhaseManager に集中
• 各エンジンは「現在のフェーズで自分はどう動くべきか」を MaturityPhaseManager に問い合わせる

5. AgentCore サービス利用マッピング

6. AWS リソースマッピング（暫定）