Application Design — continuum

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

本ドキュメントは Application Design ステージの統合ドキュメントです。詳細はそれぞれのリファレンスドキュメントを参照してください：

• 📄 components.md — コンポーネント定義 + 高レベル責務
• 📄 component-methods.md — メソッドシグネチャ + 入出力型
• 📄 services.md — 論理サービス層 + オーケストレーション
• 📄 component-dependency.md — 依存関係マトリクス + データフロー図

1. Executive Summary

continuum は、AWS主催「人をダメにするサービス」ハッカソン作品として開発される AI 駆動コミュニケーション委任プラットフォーム である。本作品は以下3層のアーキテクチャを Serverless First で実装する：

1. Inbound Arm — 受信メッセージへの代理応答生成（Bedrock + AgentCore Runtime/Memory）
2. Outbound Arm — 戦略的アウトリーチ + 定期 Heartbeat による能動的関係維持
3. Federated Layer (MACP) — 他 Continuum 利用者との裏交渉 + 表向き社交劇場演出（AgentCore Identity/Gateway）

これらを Maturity Phase Manager（Lv1〜Lv5: 慎重期 → 涅槃期） が横断的に制御し、ユーザーの委任成熟度に応じた段階的自律化を実現する。

1.1 設計方針サマリ

2. Component Inventory（18コンポーネント / 詳細は components.md）

2.1 Frontend Components（8）

2.2 Backend Components（10）

3. Service Layer（6 論理サービス / 詳細は services.md）

4. Architecture Diagram

flowchart TB
    User[("👤 User<br/>Browser/Mobile")]

    subgraph Frontend["🟦 Frontend (S3 + CloudFront)"]
        WebApp["WebApp Shell"]
        AuthUI["AuthUI"]
        InboxView["InboxView"]
        OutboundReview["OutboundReview"]
        Dashboard["Dashboard"]
        MaturitySettings["MaturitySettings"]
        DemoView["DemoSetPiece"]
        WSClient["WSClient"]
    end

    subgraph APIGW["🟪 API Gateway"]
        REST["REST API<br/>+ Cognito Authorizer"]
        WS["WebSocket API"]
    end

    Cognito["🔐 Cognito User Pool"]

    subgraph Backend["🟩 Backend (Lambda Functions)"]
        Auth["AuthHandler"]
        Contact["ContactHandler"]
        Inbound["InboundResponseEngine"]
        Outbound["OutboundOrchestrator"]
        Signal["SignalExtractor"]
        Maturity["MaturityPhaseManager"]
        MACP["MACPCoordinator"]
        Dash["DashboardEngine"]
        WSBroker["WSBroker"]
        Seeder["FeedSeeder"]
    end

    subgraph AI["🟨 Amazon Bedrock + AgentCore"]
        Bedrock["Bedrock LLM"]
        ACRuntime["AgentCore Runtime"]
        ACMemory["AgentCore Memory"]
        ACIdentity["AgentCore Identity"]
        ACGateway["AgentCore Gateway"]
    end

    subgraph Storage["🟧 Storage & Eventing"]
        DDB[("DynamoDB<br/>Single-Table")]
        EventBridge["EventBridge"]
    end

    User --> Frontend
    Frontend --> REST
    Frontend --> WS

    REST --> Auth
    REST --> Contact
    REST --> Inbound
    REST --> Outbound
    REST --> Maturity
    REST --> Dash
    WS --> WSBroker

    Auth --> Cognito
    Auth --> DDB
    Contact --> DDB
    Inbound --> Bedrock
    Inbound --> ACRuntime
    Inbound --> ACMemory
    Inbound --> Maturity
    Inbound --> Contact
    Outbound --> Signal
    Outbound --> Bedrock
    Outbound --> ACMemory
    Outbound --> Maturity
    Outbound --> MACP
    Signal --> DDB
    Signal --> Bedrock
    Maturity --> DDB
    MACP --> ACIdentity
    MACP --> ACGateway
    MACP --> ACMemory
    MACP --> Bedrock
    Dash --> DDB
    WSBroker --> DDB
    Seeder --> DDB

    Auth -.publishes.-> EventBridge
    Inbound -.publishes.-> EventBridge
    Outbound -.publishes.-> EventBridge
    MACP -.publishes.-> EventBridge
    Maturity -.publishes.-> EventBridge

    EventBridge -.triggers.-> Outbound
    EventBridge -.triggers.-> MACP
    EventBridge -.triggers.-> Maturity
    EventBridge -.triggers.-> Dash

    WSBroker -.realtime push.-> WS

    style Frontend fill:#BBDEFB,stroke:#1565C0,color:#000
    style APIGW fill:#E1BEE7,stroke:#6A1B9A,color:#000
    style Backend fill:#C8E6C9,stroke:#2E7D32,color:#000
    style AI fill:#FFF59D,stroke:#F57F17,color:#000
    style Storage fill:#FFCCBC,stroke:#BF360C,color:#000

4.1 Text Alternative

[User] → [Frontend (S3+CloudFront)]
         ├── REST → API Gateway REST → 10 Lambda Functions
         └── WebSocket → API Gateway WS → WSBroker Lambda

[Frontend] uses Cognito SDK directly for authentication

Backend Lambdas use:
  - DynamoDB (Single-Table) — persistence
  - Bedrock + AgentCore (Runtime/Memory/Identity/Gateway) — AI
  - EventBridge — async events between services

EventBridge triggers Lambdas asynchronously for:
  - Scheduled Outbound delivery
  - MACP theatrical message scheduling
  - Daily Nirvana detection
  - Analytics event aggregation

WebSocketBroker pushes realtime events to connected clients for:
  - MACP demo split-screen
  - Maturity recommendation banners
  - Badge award notifications

5. Communication Patterns（詳細は component-dependency.md）

6. Data Architecture

6.1 DynamoDB Single-Table Design

スコープ管理方針: Phase 2 Must スコープ確定 / Phase 3 拡張（MACP Federated cross-tenant / Badge GSI ranking 等）は Construction Functional Design で精緻化する。

6.1.1 テーブル属性（共通スキーマ）

6.1.2 Phase 2 Must アクセスパターン（確定 — 10 パターン）

Phase 2 GSI 利用方針: GSI1 / GSI2 は Phase 2 Must スコープでは未使用（全アクセスパターンが PK/SK で完結）。ただし Phase 2 でも MACP Simulator (US-7.1 簡易版) は Single-Tenant 内で完結するため、PK=USER#<userId> の主キーで十分。

6.1.3 Phase 3 拡張アクセスパターン（TBD — Construction Phase で精緻化）

Note: 上記 Phase 3 拡張は 本ドキュメントでは確定しない。各 Unit の Functional Design ステージで精緻化し、必要に応じて GSI 追加を判断する。

6.2 AgentCore Memory（補完的データストア）

• 用途: 過去のやり取り、MACP 交渉履歴、ユーザー文体学習データの永続化
• 特性: ベクトル類似性検索可能（必要時）
• DynamoDB との分担: 構造化データは DynamoDB、テキスト・コンテキストは AgentCore Memory

7. AWS Service Mapping

8. Phase Strategy（Phase 2 vs Phase 3）

🔄 SCOPE REVISION 2026-05-08T06:26:52Z: デモ視点見直しによりスコープを大幅縮小。詳細は ../plans/scope-revision-2026-05-08.md。

9. Cross-Cutting Concerns

9.1 Authentication & Authorization

• すべての REST API は Cognito Authorizer で JWT 検証
• WebSocket は接続時に JWT を query string で送信、$connect で検証
• Lambda 内では JWT から抽出した userId を context として全処理に伝播
• Cross-tenant 通信（MACP）は AgentCore Identity で別途認証

9.2 Logging & Observability

• 構造化ログ: { timestamp, level, requestId, userId, component, method, durationMs, message }
• Phase 2: CloudWatch Logs のみ
• Phase 3: + X-Ray（Lambda 自動 instrumentation）+ CloudWatch Metrics（Lambda 標準）

9.3 Error Handling

• ドメインごとの Error クラス（InboundGenerationFailedError, MACPNegotiationTimeoutError, etc.）
• HTTP エラーは API Gateway でマッピング（4xx / 5xx）
• 内部エラーはユーザーに詳細を露出しない（汎用メッセージ + サポート用 requestId 提示）

9.4 Retry & Resilience

• Bedrock 呼び出し: リトライ 1回、それ以上はユーザーにエラー表示
• AgentCore Gateway: タイムアウト 5秒、失敗時は通常 Outbound へ Graceful Degradation
• DynamoDB: AWS SDK 標準リトライ（指数バックオフ）
• EventBridge: 失敗時 DLQ で 24時間保持 + アラート

9.5 Cost Optimization

• Lambda: 適切なメモリサイズ（128MB〜512MB）
• DynamoDB: On-Demand モード（ハッカソンスコープ）
• Bedrock: 同一シナリオの応答キャッシング検討
• CloudFront: コンテンツキャッシング積極利用

10. ハッカソンタイムラインへの整合

11. 次フェーズへの橋渡し（Units Generation）

本 Application Design は Units Generation ステージで以下のように Unit に分解される（暫定）：

最終的な Unit 構成は Units Generation ステージで確定する。

12. 設計検証チェックリスト

12.1 要件カバレッジ

• FR-1 モックインボックス → C-BE-02 ContactHandler + C-BE-10 Seeder + C-FE-03 InboxView
• FR-2 Response Generation Engine → C-BE-03 InboundResponseEngine
• FR-3 Productivity Analytics Dashboard → C-BE-08 DashboardEngine + C-FE-05 DashboardView
• FR-4 Contact Profile Management → C-BE-02 ContactHandler
• FR-5 User Account Management → C-BE-01 AuthHandler + C-FE-02 AuthUI
• FR-6 PWA + レスポンシブ → C-FE-01 WebApp Shell（Service Worker 手動）
• FR-7 Delegation Maturity Phases → C-BE-06 MaturityPhaseManager + C-FE-06 MaturitySettingsView
• FR-8 Relationship Maintenance Engine → C-BE-04 OutboundOrchestrator + C-BE-05 SignalExtractor
• FR-9 MACP → C-BE-07 MACPCoordinator + C-FE-07 DemoSetPieceView + C-BE-09 WebSocketBroker

12.2 NFR カバレッジ

• NFR-1 パフォーマンス → 応答 5秒以内（component-dependency.md §4.1 検証済み）
• NFR-2 セキュリティ（PoC ベースライン） → Cognito + HTTPS + 入力バリデーション + Secrets Manager
• NFR-3 スケーラビリティ → Lambda + DynamoDB On-Demand によるオートスケール
• NFR-4 クロスプラットフォーム → S3 + CloudFront + PWA
• NFR-5 ロケール → 日本語のみ（プロンプト + UI）
• NFR-6 コスト → Serverless 構成 + フリーティア活用 + キャッシング検討
• NFR-7 開発・運用制約 → AI フル実装 + Monorepo

12.3 ストーリーカバレッジ

38 ストーリー（34 implementation + 4 Demo Set Piece）すべてが本 Application Design でカバーされている：

• US-1.1〜1.3 Foundation → U-1
• US-2.1〜2.3 Contact → U-2
• US-3.1〜3.6 Inbound → U-3
• US-4.1〜4.7 Outbound → U-4
• US-5.1〜5.6 Maturity → U-5
• US-6.1〜6.4 Dashboard → U-6
• US-7.1〜7.5 MACP → U-7 / U-8
• DS-1〜DS-4 Demo Set Piece → U-10