システム全体像 System architecture

Parky モバイルアプリは、Cloudflare Workers BFFを介して Supabase に接続する構成です。 管理者ポータル・オーナーポータルと同じ Supabase プロジェクト（PostgreSQL + Auth + Realtime）を共有し、 クライアントが直接叩く API は Workers の /v1/* の 1 経路に一元化します（Auth / Realtime のみ SDK で Supabase を直接参照）。 書き込み可能範囲はコード層の user_id スコープと RLS（Row Level Security）で二重に防御します。

The Parky mobile app connects to Supabase through a Cloudflare Workers BFF. It shares the same Supabase project (PostgreSQL + Auth + Realtime) with the admin portal and owner portal; clients hit a single unified API surface at /v1/* on Workers (only Auth and Realtime use the Supabase SDK directly). Writable surface is gated by code-level user_id scoping and RLS as defense in depth.

モバイルアプリのチャネル接続 Mobile app channel view

モバイルアプリだけに関係する外部接続を抽出した図です。 全体像は 全体アーキテクチャ を参照してください。

The slice of the system that the mobile app actually touches. For the full picture see the overall architecture.

flowchart LR
  MA["Mobile App
Flutter prototype"]

  subgraph BFF["Cloudflare Workers BFF"]
    API["/v1/* endpoints"]
  end

  subgraph Supabase["Supabase (supabase_flutter)"]
    AUTH["Auth"]
    DB[("PostgreSQL
+ PostGIS")]
    RT["Realtime"]
  end

  subgraph Storage["Object storage"]
    CDN["cdn.parky.co.jp
(Cloudflare R2 public GET)"]
  end

  subgraph External["外部サービス"]
    MB["Mapbox
mapbox_maps_flutter"]
    IMG["cached_network_image"]
    URL["url_launcher"]
  end

  MA --> API
  API --> DB
  MA --> AUTH
  MA --> RT
  MA --> MB
  MA --> IMG
  MA --> URL
  IMG --> CDN

予定されているが未実装の接続Planned but not yet wired

• Push 通知受信 (FCM) — 仕様書の「通知機能」に記載。現時点で firebase_messaging は pubspec.yaml に未追加。Workers 側は parky-fcm-dispatch キュー + consumer で FCM v1 を叩く配線が完成済みのため、端末側が追加されれば配信経路は完成する見込み。
• Push notifications (FCM) — called out in the spec's "通知機能". firebase_messaging is not yet in pubspec.yaml. The server side is already wired (queue parky-fcm-dispatch + consumer against FCM v1); adding the device side would close the loop.
• カメラ / 写真添付 — 仕様書の「駐車中メモ機能」「駐車後メモ機能」「レビュー機能」で写真添付が想定されている。プロトタイプには image_picker / camera 等は未導入。
• Camera / photo attach — "駐車中メモ", "駐車後メモ", and the review feature all imply photo attachment. image_picker / camera packages are not yet in the prototype.
• 決済 (Stripe / IAP) — 仕様書の「プレミアムプラン画面」で課金が想定されている。プロトタイプには決済 SDK が未導入、DB スキーマ側には revenue_transactions.stripe_payment_intent_id 等の受け皿のみ存在する。
• Payments (Stripe / IAP) — implied by the "プレミアムプラン" screen in the spec. No payment SDK in the prototype today; the DB side has revenue_transactions.stripe_payment_intent_id columns reserved.
• 位置情報 / 駐車セッション — Mapbox SDK 自体はマップ上のユーザー位置表示に使えるが、駐車開始時の GPS ピン固定などのバックグラウンド取得は未実装。
• GPS / parking session capture — Mapbox can show the user on the map, but background GPS capture (e.g. pinning a parking spot on session start) is not yet implemented.

3.1 システムアーキテクチャ 3.1 System architecture

flowchart TB
  subgraph Client["モバイルクライアント (Flutter)"]
    UI[UI Layer
Widgets / Screens]
    State[State Management
Riverpod / BLoC]
    Repo[Repository Layer]
    Cache[(Local Cache
Isar / Hive)]
    Sec[Secure Storage
flutter_secure_storage]
  end
  subgraph Edge["BFF (Cloudflare Workers)"]
    BFF[Workers / Hono
/v1/* endpoints]
    HYP[Hyperdrive
PG connection pool]
    Q1[Queue
parky-fcm-dispatch]
    Q2[Queue
parky-store-sync]
    CRON[Cron Triggers
*/10 min]
  end
  subgraph Backend["バックエンド (Supabase)"]
    Auth[Supabase Auth
JWT / OTP]
    PG[(PostgreSQL 17
+ PostGIS)]
    RT[Realtime
WebSocket]
  end
  subgraph External["外部サービス"]
    Mapbox[Mapbox GL
Geocoding / Map Tile]
    FCM[Firebase Cloud Messaging
Push]
    R2[(Cloudflare R2
画像・レビュー写真)]
    AI[LLM Provider
AI検索]
    Sentry[Sentry
Crash/Error]
    GA4[Google Analytics 4
計測]
  end

  UI --> State
  State --> Repo
  Repo --> Cache
  Repo --> Sec
  Repo --> BFF
  Repo --> Auth
  Repo --> RT
  Repo --> Mapbox
  Repo --> R2
  BFF --> HYP
  HYP --> PG
  BFF --> Q1
  Q1 --> FCM
  BFF --> Q2
  CRON --> BFF
  BFF --> AI
  PG --> RT
  RT --> Repo
  UI --> Sentry
  UI --> GA4

3.2 クライアント構成 3.2 Client composition

モバイルアプリは Flutter で構築され、iOS / Android 両対応です。 プロトタイプは parky/mobileapp/prototype/flutter/ に存在します。

The mobile app is built on Flutter and targets both iOS and Android. The prototype lives in parky/mobileapp/prototype/flutter/.

技術スタック Technology stack

レイヤ構成（推奨） Layer composition (recommended)

mobileapp/
├── lib/
│   ├── main.dart
│   ├── app/                  # ルーティング・テーマ・i18n# Routing, theme, i18n
│   ├── core/                 # 共通ユーティリティ・定数・エラー型# Shared utilities, constants, error types
│   ├── data/
│   │   ├── api/              # Supabase / 外部API クライアント# Supabase / external API clients
│   │   ├── models/           # エンティティ・DTO# Entities and DTOs
│   │   ├── repositories/     # ドメイン別リポジトリ# Domain repositories
│   │   └── local/            # Isar / SecureStorage
│   ├── domain/               # ユースケース・純ドメインロジック（料金計算等）# Use cases and pure domain logic (fee calculation, etc.)
│   ├── presentation/
│   │   ├── pages/            # 画面 25枚# 25 screens
│   │   ├── widgets/          # 再利用ウィジェット# Reusable widgets
│   │   └── providers/        # Riverpod プロバイダ# Riverpod providers
│   └── services/             # 位置情報 / 通知 / バックグラウンド# Location / notifications / background
├── assets/
└── test/

3.3 バックエンド構成 3.3 Backend composition

バックエンドはサーバーレス（Supabase マネージド）で、専用のアプリケーションサーバーは持ちません。 モバイルクライアントは Cloudflare Workers BFF (/v1/*) 経由で DB アクセスし、重い処理は PostgreSQL RPC に切り出します。

The backend is serverless (Supabase managed), with no dedicated application server. Mobile clients hit the Cloudflare Workers BFF (/v1/*), and heavy logic is pushed into PostgreSQL RPCs.

3.4 データストア構成 3.4 Data store composition

永続化レイヤ Persistence layer

キャッシュ戦略 Caching strategy

3.5 外部サービス連携 3.5 External service integration

3.6 通知インフラ構成 3.6 Notification infrastructure

sequenceDiagram
  participant Admin as Admin Portal
  participant W as Workers BFF
/v1/admin/user-notifications/{id}/send
  participant DB as PostgreSQL (via Hyperdrive)
  participant Q as Queue
parky-fcm-dispatch
  participant C as Queue Consumer
queue/fcm-dispatch.ts
  participant KV as KV parky-cache
  participant FCM
  participant App as Mobile App

  Admin->>W: POST send
  W->>DB: user_push_tokens 取得
  W->>DB: user_notifications status=sending
  W->>Q: enqueue (500 tokens/batch)
  Q->>C: message batch
  C->>KV: OAuth access_token (cache)
  C->>FCM: FCM v1 send (parallel fetch)
  FCM->>App: Push 通知配信
  C->>DB: success_count / failure_count 加算
  App->>DB: user_notifications.read_at を更新
  DB->>App: Realtime で他端末にも反映

• デバイストークン管理：起動時に FCM トークンを取得し、user_push_tokens テーブルに upsert（user_id + device_id ユニーク）
• Device token management: fetch the FCM token at launch and upsert it into the user_push_tokens table (unique on user_id + device_id)
• 送信元：管理者ポータル（マーケ通知）、DB トリガ（料金アラート等システム通知）、スケジューラ（定期通知）
• Senders: the admin portal (marketing notifications), DB triggers (system notifications such as fee alerts), and the scheduler (recurring notifications)
• 配信チャネル：Push（FCM）＋ アプリ内通知（user_notifications テーブル + Realtime）
• Delivery channel: Push (FCM) plus in-app notifications (the user_notifications table + Realtime)
• 開封計測：Push 受信時にローカルで delivered_at、タップで opened_at を記録
• Open-rate measurement: record delivered_at locally on push reception and opened_at on tap

3.7 ログ / 監視基盤 3.7 Logging / monitoring