システム全体像 System architecture

1. 接続先は BFF だけ 1. Only the BFF

Flutter クライアント（mobileapp/prototype/flutter/）から直接叩ける外部サーフェスは次の 2 種類だけです。

The Flutter client (mobileapp/prototype/flutter/) is allowed to hit only two external surfaces.

2. 責任分界 2. Responsibility split

BFF は data + validation + navigation + UI Config を ViewEnvelope で返します。 UI コンポーネント構造はサーバーから返しません（描画は Flutter ネイティブ）。 ViewEnvelope の詳細契約は API レスポンス構造 が正です。

The BFF returns data + validation + navigation + UI Config inside a ViewEnvelope. It does not return UI component trees (rendering stays Flutter-native). See API response structure for the authoritative ViewEnvelope contract.

責任分界表 Responsibility matrix

3. API サーフェスの 3 種類 3. Three API surfaces

モバイルが叩ける /v1/mobile/* の endpoint は以下の 3 種類。Resource API（/v1/parking-lots など）はモバイルからは叩きません。

Only three kinds of /v1/mobile/* endpoints exist. The generic resource API (/v1/parking-lots etc.) is off-limits for the mobile app.

ViewEnvelope の構造（要約） ViewEnvelope structure (summary)

{
  "data": { /* 画面固有の domain データ *//* screen-specific domain data */ },
  "ui_config": { /* 文言・theme hint・feature flag *//* copy, theme hint, feature flags */ },
  "navigation": { /* 次遷移先 / deep link target *//* next screen / deep link target */ },
  "validation": { /* フォーム validation ルール *//* form validation rules */ },
  "states": { /* loading / empty / error の判定ヒント *//* loading / empty / error hints */ },
  "fallback_behavior": {
    "on_version_mismatch": "force_update" | "degrade" | "ignore",
    "on_offline": "cache_last" | "block" | "degrade"
  },
  "meta": {
    "view_id": "search_results",
    "view_version": "1.0.0",
    "min_app_version": "1.2.0",
    "generated_at": "2026-01-01T00:00:00Z"
  }
}

4. 必須ヘッダーと契約 4. Required headers and contract

5. アーキテクチャ図 5. Architecture diagram

flowchart LR
  subgraph Client["Flutter クライアント"]
    UI[UI Layer / Widgets]
    State[Riverpod 3
(flutter_riverpod 3.3.x)]
    Repo[BFF Client
dio + generated Dart]
    SecStore[Secure Storage
JWT / refresh]
    LocalDB[(SharedPreferences +
SecureStorage
SDUI ui_layer cache)]
  end

  subgraph Edge["Cloudflare Workers BFF — 唯一の接続先"]
    Views["GET /v1/mobile/views/home-feed 等
ViewEnvelope"]
    Actions["POST /v1/mobile/actions/sessions/start 等
ActionEnvelope"]
    Telemetry["POST /v1/mobile/telemetry/events
TelemetryAck"]
    Core[Core / Data layers
Hyperdrive → Postgres]
    Queues[Queues
parky-fcm-dispatch
parky-store-sync]
    FCMOut[FCM v1 送信]
    R2Access[R2 / Image Resizing]
  end

  subgraph Auth["Supabase Auth — 例外的に直結"]
    SA["JWT 発行 / refresh
email / OTP / social"]
  end

  subgraph Media["画像配信"]
    R2[(Cloudflare R2)]
    Resize[Cloudflare
Image Resizing]
  end

  subgraph PushIn["プッシュ受信"]
    FCMIn[firebase_messaging
on device]
  end

  UI --> State --> Repo
  Repo --> Views
  Repo --> Actions
  Repo --> Telemetry
  Repo -.JWT 取得.-> SA
  Repo -.token 保存.-> SecStore
  Repo -.キャッシュ.-> LocalDB

  Views --> Core
  Actions --> Core
  Core --> Queues
  Queues --> FCMOut
  FCMOut --> FCMIn
  FCMIn --> UI

  Repo -->|cached_network_image| Resize
  Resize --> R2
  Core --> R2Access

6. Flutter クライアント構成 6. Flutter client composition

責務は描画・入力・ローカル状態・トークン保持に閉じます。ドメインロジック（料金計算・予約可否等）を Flutter に実装してはいけません。

Flutter's scope is limited to rendering, input, local state, and token storage. Do not implement domain logic (pricing, eligibility, etc.) on the client.

推奨レイヤ構成 Recommended layer layout

mobileapp/prototype/flutter/lib/
├── main.dart                       # Supabase 初期化 / dio 構築 / Riverpod root# Supabase init / dio bootstrap / Riverpod root
├── app.dart, app_router.dart       # go_router 定義 + ルートシェル# go_router config + root shell
├── config/                         # Supabase / BFF base URL / dart-define-from-file# Supabase / BFF base URL / dart-define-from-file
├── core/
│   ├── auth/                       # SessionController（Supabase Auth ラッパ）# SessionController (supabase_flutter wrapper)
│   ├── bff/                        # bff_client / view_envelope / action_envelope / async_swr / navigation_resolver# bff_client / view_envelope / action_envelope / async_swr / navigation_resolver
│   ├── sdui/                       # view_client / boot_revalidator / ui_layer_cache（SDUI L0/L1 永続化）# view_client / boot_revalidator / ui_layer_cache (SDUI L0/L1 persistence)
│   ├── i18n/, codes/, theme/       # 静的辞書 / コードマスタ / テーマ# Static dictionary / code master / theme
│   ├── notifications/, iap/, app_review/, observability/, telemetry/
│   ├── storage/                    # SharedPreferences / flutter_secure_storage ラッパ# SharedPreferences / flutter_secure_storage wrappers
│   └── widgets/                    # 共通 widget（envelope_consumer 等）# Shared widgets (envelope_consumer etc.)
├── features/                       # 1 機能 = data / application / presentation の 3 層# Per-feature trio: data / application / presentation
│   ├── splash/, onboarding/, auth/, permissions/
│   ├── home/, search/, search_presets/, destinations/, lot_detail/
│   ├── start_parking/, parking_session/, sessions/, history/, parking_completed/
│   ├── feedback_satisfied/, feedback_dissatisfied/
│   ├── saved/, notifications/, session_notifications/
│   ├── profile/, premium/, rewards/, gamification/, themes/
│   ├── media/, policies/, support/, lot_registration/, app_review/, error_fallback/
├── screens/                        # 旧構造（features/ へ段階的に移行中）# Legacy layout (being migrated into features/)
├── generated/parky_api/            # OpenAPI から生成された Dart クライアント（path 依存パッケージ）# OpenAPI-generated Dart client (path package)
└── widgets/, services/             # BottomNavShell・OS 連携サービス# BottomNavShell + OS-integration services

7. バックエンド側の構成 7. Backend composition

8. キャッシュ・オフライン戦略 8. Caching and offline strategy

• BFF 側キャッシュ：views 系（例: /v1/mobile/views/home-feed）は ETag + Cache API を使い、304 で Edge から直接返す構成。
• BFF-side cache: views endpoints (e.g. /v1/mobile/views/home-feed) use ETag + Cache API so 304 responses can be served directly from the edge.
• クライアント側キャッシュ：Flutter は core/sdui/ui_layer_cache.dart + SharedPreferences に SDUI L0/L1（ui_layer）を保存。L2 の data 自体は Riverpod 内 in-memory に保持し、画面遷移時の再 fetch を asyncSwr（core/bff/async_swr.dart）で stale-while-revalidate 実行する。
• Client-side cache: Flutter persists SDUI L0/L1 (ui_layer) via core/sdui/ui_layer_cache.dart + SharedPreferences. L2 data stays in-memory inside Riverpod providers and is refreshed on revisit through asyncSwr (core/bff/async_swr.dart) using stale-while-revalidate semantics.
• 楽観的更新：Action は ActionEnvelope.data に「次に描画すべき View 状態」を同梱して返すため、再 fetch 不要。Supabase Realtime による自動再同期は行わない。
• Optimistic updates: Actions return the next view state inside ActionEnvelope.data, so the client does not refetch the View afterwards. No Supabase Realtime resync.
• マスターデータ：コードマスター（codes）と app_config は /v1/mobile/views/boot 同梱、i18n 辞書は /v1/mobile/i18n/bundle から ETag/304 ベースで配信し、それぞれ version hash で差分更新する。
• Master data: Code masters and app_config ride on /v1/mobile/views/boot; the i18n dictionary is shipped separately via /v1/mobile/i18n/bundle with ETag/304. Both invalidate on a version-hash mismatch.

9. 通知パイプライン 9. Notification pipeline

flowchart LR
  Trigger["BFF イベント
(review reminder /
session alert /
admin push 等)"]
  Q["parky-fcm-dispatch
(Cloudflare Queue)"]
  Consumer["Consumer Worker
FCM v1 呼出"]
  FCM[(Firebase Cloud Messaging)]
  Device["Flutter
firebase_messaging"]
  Token["/v1/mobile/actions/push-tokens/register"]

  Trigger --> Q --> Consumer --> FCM --> Device
  Device -->|device_token| Token --> Q

• Flutter は device token を取得 → BFF に登録のみ。
• Flutter obtains the device token and registers it with the BFF. That's it.
• 実際の送信 / 再試行 / DLQ / 配信ログは BFF (Workers + Queues) が管理する。
• Sending, retries, DLQs, and delivery logs are owned by the BFF (Workers + Queues).
• 通知タップからの deep link は navigation と同じ形式で運ばれ、Flutter は go_router でそのまま遷移する。
• Deep links from notification taps arrive in the same shape as navigation, so Flutter passes them straight to go_router.

10. 関連ドキュメント 10. Related docs

• API レスポンス構造 (SSoT)API response structure (SSoT)
• 画面 × API マップ（25 画面）Screen × API map (25 screens)
• 機能一覧Features
• 画面カタログScreen catalog
• 利用フロー・状態遷移User flows & state transitions
• 認証フローAuth flows
• 通知設計Notifications design
• OpenAPI (Redoc)OpenAPI (Redoc)