Services — continuum

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

Note: 本ドキュメントは 論理サービス層 を定義する。物理 Lambda 関数の集合ではなく、ユースケースを統合的にオーケストレーションする論理単位として記述する。各サービスは複数のコンポーネントを協調させて1つのビジネスゴールを達成する。

1. Service Layer Overview

論理サービスを 6つ 定義：

横断インフラ: WebSocketBroker (C-BE-09) は全サービスから利用される配信レイヤー。

2. S-1: UserAccountService

責務

• ユーザーのライフサイクル管理（サインアップ → アクティブ → Lv5 涅槃 → アーカイブ）
• 認証・認可ガード
• 初期 Maturity Phase 設定（Lv1）
• プロファイル更新

主要ユースケース

• UC-1.1: 新規ユーザー登録: Cognito User Pool への登録 → Post-Confirmation トリガーで AuthHandler が DynamoDB にプロファイル作成 + MaturityPhaseManager が Lv1 状態を初期化
• UC-1.2: ログイン → JWT 発行: Cognito 認証成功で JWT 取得、後続 API 呼び出しに利用
• UC-1.3: プロファイル更新: 表示名・Default Communication Style の変更（変更時、未送信の応答は新スタイルで再生成 — US-1.3）

Orchestration Pattern

• 同期 REST（API Gateway → Lambda）
• 単一トランザクション境界（DynamoDB の Conditional Write でアトミック性確保）

サービス間連携

• → ContactManagementService: なし（独立）
• → MaturityPhaseManager: 初期化呼び出し（プロファイル作成時）

3. S-2: ContactManagementService

責務

• コンタクトプロファイルの CRUD
• Engagement Cadence 設定
• Critical タグの付与
• Mock Social Feed の投入と紐付け

主要ユースケース

• UC-2.1: コンタクト追加: 名前・関係カテゴリ・Tier・Tone Preference を受け、DynamoDB に永続化 + Mock Feed テンプレート紐付け（US-2.1）
• UC-2.2: Cadence 設定: 関係カテゴリ・Tier から推定されるデフォルト Cadence を提示、ユーザーが上書き可（US-2.2）
• UC-2.3: Critical タグ管理: トグル ON/OFF で is_critical 更新（US-2.3）
• UC-2.4: Seed Mock Feed: ハッカソンデモ用に MockSocialFeedSeeder が一括投入（US-4.7）

Orchestration Pattern

• 同期 REST が主
• Seeding は CDK Custom Resource または手動 CLI 実行

4. S-3: InboundCommunicationService（Inbound Arm）

責務

• 受信メッセージへの 応答生成 + 送信 の全フロー
• Maturity Phase に応じた UI 動作の判定
• ユーザーの Inbound 履歴管理

主要ユースケース

UC-3.1: メッセージ受信 → 応答生成（Lv1 慎重期）

1. Frontend が GET /inbox で受信ボックス取得（FR-1）
2. ユーザーがメッセージ詳細を開く
3. Frontend が POST /inbound/{id}/generate 呼び出し
4. InboundResponseEngine が起動:
   • ContactHandler から相手のプロファイル取得
   • AgentCore Memory から過去応答履歴を取得（Context Injection）
   • Bedrock LLM で 3バリエーション（Conservative/Pragmatic/Cordial）生成
   • Relational Calibration: 関係カテゴリに応じてトーン調整
   • Plausibility Constraint: 案間の類似度 0.7 以下を担保（不整合時は再生成）
5. Frontend に 3案返却
6. ユーザーが選択 → 編集（Lv1 のみ） → 送信
7. 送信時: メッセージステータスを responded 化 + AgentCore Memory に履歴永続化 + DashboardEngine の counter +1

UC-3.2: 自動応答（Lv2-5）

• Lv2: メッセージ受信時に 30% 確率で レビュースキップ → 即時送信
• Lv3: Critical タグ以外は自動 → Critical のみ UC-3.1 の流れ
• Lv4: 全自動（自然な遅延後 EventBridge 経由送信）
• Lv5: 全自動 + ユーザー通知なし

UC-3.3: 応答スタイル再生成（プロファイル更新時）

• Default Communication Style 変更 → 未送信応答の再生成（US-1.3）

Orchestration Pattern

• 同期 REST（応答生成・送信操作）
• 非同期 EventBridge（Lv4 自動送信のスケジューリング）

サービス間連携

• ← MaturityPhaseManager: shouldReviewInbound() 判定
• → AgentCore Memory: 履歴 R/W
• → AnalyticsService: 送信完了通知

5. S-4: OutboundCommunicationService（Outbound Arm）

責務

• 戦略的アウトリーチ（Strategic Outreach）の生成・スケジューリング
• Engagement Heartbeat の定期実行
• Conflict Detection + Plausibility Engineering
• Mock Social Feed からの Signal 抽出と Window 確定

主要ユースケース

UC-4.1: Strategic Outreach Generation

1. OutboundOrchestrator が scheduleStrategicOutreach(userId) を起動（バッチ or イベントトリガー）
2. ユーザーの全コンタクトに対し:
   • SignalExtractor が Mock Social Feed を解析 → Availability Windows を取得
   • Confidence ≥ 0.7 の Window を Optimal Outreach Window として確定（US-4.1）
3. 各 Window に対し:
   • Bedrock で誘い文を生成（FR-8.1, US-4.2）
   • Plausibility Constraint チェック（直近30日内に同種誘いなし）
   • Conflict Detection: Inbound 履歴と整合性確認（US-4.4）
   • Plausibility Engineering: 送信時刻のランダム化、文体学習適用（US-4.5）
4. 候補を outbound_pending 状態で永続化
5. MACP 試行: FederatedCoordinationService に試行依頼
   • MACP 不成立 → そのまま Outbound 候補として残存
   • MACP 成立 → MACP Session の Theatrical メッセージとして登録、通常 Outbound から除外

UC-4.2: Engagement Heartbeat Scheduling

• 各コンタクトの Cadence（weekly/biweekly/monthly/quarterly）に応じた送信時刻計算
• Content Diversity Engine でカテゴリ重複回避（US-4.3）
• Lv1: ユーザーレビュー必須 / Lv2-5: フェーズ別動作

UC-4.3: Outbound Pre-send Review (Lv1-2)

• Frontend が GET /outbound/pending で候補一覧取得
• ユーザーが承認 → POST /outbound/{id}/approve で送信完了
• ユーザーが却下 → POST /outbound/{id}/reject で破棄
• Lv2 では 30% は確率的にレビューUIスキップ（自動送信）

UC-4.4: Scheduled Delivery

• 承認済み候補は EventBridge スケジュールで指定時刻に配送
• Lambda が Trigger され executeTheaterStep または sendOutbound を呼ぶ

Orchestration Pattern

• Hybrid（Sync REST + Async EventBridge）
• バッチ的な Window 抽出（日次） + リアルタイムなレビュー操作

サービス間連携

• ← MaturityPhaseManager: shouldReviewOutbound() 判定
• → FederatedCoordinationService: MACP 試行
• → AnalyticsService: 送信メトリクス更新

6. S-5: FederatedCoordinationService（Federated Layer / MACP）

責務

• 他テナント Continuum 利用者との連携処理
• MACP プロトコルの 4ステップ実行（Discovery → Negotiation → Theatrical → Outcome）
• AgentCore Identity / Gateway / Memory の統合運用
• 失敗時の Graceful Degradation

主要ユースケース

UC-5.1: MACP Trigger（Outbound 送信前）

1. OutboundOrchestrator から MACPCoordinator.attemptMACP(candidate) 呼び出し
2. Peer Discovery（FR-9.2）:
   • コンタクトのメールアドレスを SHA256 ハッシュ化
   • AgentCore Identity で Continuum Subscriber Registry を Lookup
   • ヒットしない場合: null 返却 → 通常 Outbound フローへ復帰
3. Inter-Agent Negotiation（FR-9.3）:
   • AgentCore Gateway 経由で相手テナントの MACPCoordinator に接続
   • JSON プロトコル（Mutual Decline Intent / Theater Topic / Duration / Cadence / Tone / Resolution Pattern / Privacy Boundaries）を交換
   • 合意成立: MACPSession 作成、AgentCore Memory に永続化
   • 合意不成立: 通常 Outbound へ復帰
4. Theatrical Performance Scheduling（FR-9.4）:
   • 合意済み脚本の各メッセージを EventBridge スケジュール送信
   • 各メッセージは自然な遅延（数時間〜数日）で順次配信
5. Outcome Confirmation（FR-9.5）:
   • 全メッセージ送信完了後、両テナントの DashboardEngine に "Bilateral Optimization Specialist" バッジを同期付与
   • WebSocketBroker 経由で両ユーザーに完了通知
6. AgentCore Memory に MACP 履歴永続化（次回同一ペアでの効率化のため）

UC-5.2: Failure Handling

• Gateway タイムアウト → MACPCoordinator.abortSession(sessionId, 'gateway_timeout') → 通常 Outbound へ復帰
• 認証失敗 → 同上、reason='auth_failure'
• 一方の利用者が Continuum を解約 → 'counterpart_unavailable'
• 一方が "実際に会いたい" → 'mutual_intent_mismatch'

Orchestration Pattern

• Async Cross-Tenant（AgentCore Gateway）
• EventBridge Scheduling（Theatrical メッセージ配信）
• Event-Driven Notification（WebSocket 経由でデモ画面更新）

サービス間連携

• ← OutboundCommunicationService: トリガー
• → AgentCore Identity / Gateway / Memory: 主要利用先
• → InboundCommunicationService: Theatrical メッセージは相手側の Inbound として表示
• → AnalyticsService: バッジ付与
• → WebSocketBroker: リアルタイム配信

7. S-6: AnalyticsService

責務

• KPI 集計
• Maturity Certification バッジ管理
• Outbound メトリクス
• Recommendation バナー判定

主要ユースケース

UC-6.1: Dashboard 表示（Frontend Pull）

• Frontend が GET /dashboard/kpi 呼び出し
• DashboardEngine がリアルタイムで集計（クエリ）
• 集計結果を返却（FR-3, US-6.1）

UC-6.2: バッジ付与（イベント駆動）

• Inbound/Outbound/MACP の各イベントで DashboardEngine が監視
• 達成条件を満たした時点で awardBadge(userId, badge) を実行（US-6.2）
• WebSocketBroker 経由で Frontend にプッシュ

UC-6.3: Recommendation 表示判定

• 累計応答件数が 5件達成 → Lv2 推奨
• 20件達成 → Lv3 推奨
• Lv4-5 への推奨は出さない（FR-7.2）
• GET /dashboard/recommendations で取得

Orchestration Pattern

• 同期 Pull（Frontend からの集計要求）
• イベント駆動 Push（バッジ付与・WebSocket 通知）

サービス間連携

• ← All Services: 各種イベント受信
• → MaturityPhaseManager: 累計件数照会
• → WebSocketBroker: リアルタイム通知

8. Service Orchestration: End-to-End Flow Examples

8.1 Flow A: Lv1 ユーザーが受信 → 応答（最頻フロー）

[Frontend InboxView]
  │ GET /inbox
  v
[S-3 InboundCommunicationService]
  │ list messages from DynamoDB
  v
[Frontend InboxView] (display)
  │ POST /inbound/{id}/generate
  v
[S-3 InboundCommunicationService]
  │ check Maturity Phase (S-1.MaturityPhaseManager) → Lv1
  │ fetch contact (S-2.ContactHandler)
  │ fetch past interactions (AgentCore Memory)
  │ Bedrock LLM call (3 variations)
  │ apply Relational Calibration
  │ validate Plausibility Constraint
  v
[Frontend InboxView] (display 3 variations)
  │ user selects + edits + sends
  │ POST /inbound/{id}/send
  v
[S-3 InboundCommunicationService]
  │ persist to DynamoDB (responded)
  │ persist to AgentCore Memory
  │ event: response.sent → S-6 AnalyticsService
  v
[S-6 AnalyticsService]
  │ counter +1
  │ check badge conditions (5 件達成 → Recommendation Lv2)
  │ WebSocketBroker push to user

8.2 Flow B: Outbound Strategic Outreach + MACP Trigger

[Daily Batch: EventBridge → S-4 OutboundCommunicationService.scheduleStrategicOutreach]
  │ for each contact:
  │   S-5 SignalExtractor.extractWindowsForContact(contactId)
  │   filter Confidence >= 0.7
  │   for each Optimal Window:
  │     generate invitation text (Bedrock)
  │     check Plausibility Constraint
  │     check Conflict (Inbound history)
  │     apply Plausibility Engineering (timing + style)
  │   create OutboundCandidate
  v
[S-5 FederatedCoordinationService.attemptMACP(candidate)]
  │ Peer Discovery via AgentCore Identity
  │ if Continuum user:
  │   negotiate via AgentCore Gateway
  │   if mutual decline intent matches:
  │     create MACPSession
  │     schedule theatrical messages
  │     mark candidate as MACP-handled
  │ else:
  │   leave as normal Outbound
  v
[Outbound Pending or MACP Theater]

8.3 Flow C: Maturity Phase Lv1 → Lv2 推奨 → 移行

[ユーザーが累計5件目の応答完了]
  v
[S-3 InboundCommunicationService → S-1 MaturityPhaseManager.incrementResponseCount]
  │ totalResponses = 5
  │ check threshold → Lv2 推奨
  v
[S-6 AnalyticsService.recommendationAvailable]
  │ WebSocketBroker push to user
  v
[Frontend DashboardView] displays banner
  │ ユーザーが "Move to Trust Phase" をタップ
  │ PUT /maturity/phase { targetPhase: "Lv2" }
  v
[S-1 MaturityPhaseManager.changePhase]
  │ confirmation modal
  │ update DynamoDB
  │ award "Adaptive Delegation Specialist" badge
  v
[Frontend] receives confirmation, UI updates to Lv2 mode

8.4 Flow D: Lv5 Auto-Detection（日次バッチ）

[EventBridge Scheduler: daily 03:00 JST]
  v
[S-1 MaturityPhaseManager.detectNirvanaCandidates]
  │ query DynamoDB: WHERE phase = Lv4 AND consecutiveDays >= 30 AND lastAppOpenAt < now - 7d
  │ for each candidate:
  │   promoteToLv5(userId)
  │   stop push notifications
  │   stop monthly summary
  │   internal counter: daysInNirvana += 1 (daily)
  v
[ユーザーがアプリを起動]
  │ POST /me (any API call)
  v
[S-1 MaturityPhaseManager.handleAppOpen]
  │ if currentPhase == Lv5:
  │   demote to Lv4
  │   record lifetime daysInNirvana
  │   award "Transcendence Achieved" badge (if not awarded)
  v
[Frontend] displays "Days in Nirvana: N" + 認定バッジ

9. Transaction Boundaries

10. Service Discovery & Configuration

• Lambda → Lambda 同期呼び出し: 直接 Lambda Invoke（同一サービス内）または API Gateway 内部経由
• イベント発行: EventBridge Custom Bus（continuum-bus）に発行
• 設定値: Secrets Manager + Parameter Store
  • Bedrock Model ID
  • AgentCore Gateway Endpoint
  • DynamoDB Table Name
  • Cognito User Pool ID