アーキテクチャ Architecture

Parky は Cloudflare Workers（Hono 製 BFF）をクライアントと Supabase の間に挟むマルチクライアント構成のサービスです。 クライアント（Flutter / Web）が叩く API エンドポイントは /v1/* の 1 経路に一元化し、 Supabase（PostgreSQL + Auth + Realtime）はバックエンドの中核として利用します。 Supabase Edge Functions は使用せず、すべてのサーバーサイドロジックは Workers に集約します。 画像・PDF などのバイナリアセットは Cloudflare R2 (S3 互換)に格納し、 Supabase は assets テーブルでメタデータと s3_key のみを保持します。

Parky is a multi-client service with Cloudflare Workers (a Hono-based BFF) sitting between clients and Supabase. Clients (Flutter / Web) hit a single unified /v1/* API surface. Supabase (PostgreSQL + Auth + Realtime) remains the core backend. Supabase Edge Functions are not used — all server-side logic is consolidated in Workers. Binary assets (images, PDFs) live in Cloudflare R2 (S3-compatible); Supabase holds only metadata and the s3_key via the assets table.

クライアント接続層の一元化Unified client-facing API layer

クライアントが直接叩く API は Cloudflare Workers の /v1/* の 1 経路のみ。 Supabase Edge Functions は使わず、FCM 配信・LLM 呼び出し・ストア同期・定期ジョブまですべて Workers 内で完結させる。 spec（OpenAPI）も Workers 側 1 枚に統一。

Clients call exactly one public API surface: Cloudflare Workers at /v1/*. Supabase Edge Functions are not used — FCM delivery, LLM calls, store sync, and scheduled jobs all live inside Workers. The OpenAPI spec is authored once, on the Workers side.

システム全体像System context

flowchart LR
  subgraph Clients["Clients"]
    MA["Mobile App
Flutter"]
    WA["Web App
Astro + Islands"]
    AP["Admin Portal
React + Vite"]
  end

  subgraph BFF["BFF (Control Plane)"]
    CFW["Cloudflare Workers
Hono + OpenAPI /v1/*"]
  end

  subgraph Supabase["Supabase (core backend)"]
    AUTH["Auth"]
    DB[("PostgreSQL
66 tables + RLS")]
    RT["Realtime"]
  end

  subgraph Storage["Object storage"]
    WSB["Cloudflare R2
parky bucket"]
  end

  subgraph External["External services"]
    MB["Mapbox"]
    FCM["FCM"]
    STRIPE["Stripe
(planned)"]
    LLM["LLM API
(Claude/Gemini/OpenAI)"]
    STORE["Play/App Store"]
  end

  CRON["CF Cron Triggers"]

  MA -->|"/v1/*"| CFW
  WA -->|"/v1/*"| CFW
  AP -->|"/v1/*"| CFW

  MA -.->|Auth SDK| AUTH
  WA -.->|Auth SDK| AUTH
  AP -.->|Auth SDK| AUTH

  MA -.->|Realtime| RT
  AP -.->|Realtime| RT

  MA -.->|PUT presigned| WSB
  WA -.->|GET public| WSB
  AP -.->|PUT presigned| WSB

  CRON --> CFW

  CFW --> DB
  CFW -->|mint presign| WSB
  CFW --> FCM
  CFW --> LLM
  CFW --> STORE

  WA --> MB
  MA --> MB
  AP --> MB

制御面と データ面の分離Control plane vs data plane

「ロジックと認可（制御面）」は Workers に完全集約し、「大容量バイト列・WebSocket・Auth フロー（データ面）」だけは経路最適化のため Workers を経由させない、という二分割で整理しています。 Storage の例外（presigned URL）は、認可の意味では Workers が門番です（/v1/storage/upload-url で JWT 検証・user_id スコープで URL を発行）。

We split the system into control plane (all business logic, auth, validation — centralized in Workers) and data plane (bulk bytes, WebSockets, auth flows — bypassing Workers for efficiency). Even the Storage exception is gated by Workers: /v1/storage/upload-url validates the JWT and mints a scoped presigned URL.

コンポーネントの役割Component responsibilities

認証フローAuth flow

1. Flutter / Web: supabase-flutter.auth.signIn*()   → JWT 取得
2. Flutter / Web: BFF 呼び出し時 Authorization: Bearer <JWT>
3. Workers: SUPABASE_JWT_SECRET で署名検証         → user_id 抽出
4. Workers: Service Role Key で Supabase Postgres へ接続
            （user_id でスコープされたクエリをコード層で徹底）
5. RLS は二重防御として維持
            （Service Role でも明示的に .eq('user_id', ...) を書く）

契約定義 (OpenAPI)Contract (OpenAPI)

API 契約は parky/packages/api-spec/openapi.yaml（OpenAPI 3.1）を Single Source of Truth として管理し、 Workers 実装は @hono/zod-openapi で spec と連動、TypeScript クライアントは openapi-typescript、 Flutter 向け Dart クライアントは openapi-generator-cli の dart-dio ジェネレータで CI 自動生成します。 破壊的変更は URL バージョニング（/v1/ → /v2/）で吸収し、旧版は最低 180 日のサンセット期間を維持します。

The API contract lives at parky/packages/api-spec/openapi.yaml (OpenAPI 3.1) as the single source of truth. Workers use @hono/zod-openapi to stay in sync with the spec; CI regenerates TypeScript clients via openapi-typescript and Dart clients via openapi-generator-cli (dart-dio). Breaking changes move behind /v2/; prior versions are maintained for at least 180 days.

クライアント別の特徴What each client does differently

• モバイルアプリ（Flutter）: 自動生成 Dart クライアントで /v1/* を呼ぶ。supabase-flutter は Auth と Realtime のみ利用（from() / rpc() / storage の直接利用は Dart analyzer で lint エラー化）。位置情報・プッシュ・カメラのネイティブ機能を活用
• Mobile app (Flutter): Calls /v1/* through the auto-generated Dart client. Uses supabase-flutter only for Auth and Realtime — direct from() / rpc() / storage calls are lint-errored. Uses native GPS, push, camera
• Web版（Astro）: 静的 SSG + Islands。SEO 最重視。検索・地図は島（Island）として JS 化。公開データアクセスは全面 BFF (/v1/*) 経由に移行済み（2026-04-19 時点で supabase.from() 直叩きは 0 件）。ビルド時に API のヘルスチェックを挟んで SSG を焼く
• Web app (Astro): SSG with Islands. SEO-first; search/map hydrate as islands. All public-read paths now go through the BFF (/v1/*) — as of 2026-04-19 there are 0 direct supabase.from() calls. Build-time API health check gates SSG rendering
• 管理者ポータル（React + Vite）: SPA。BFF 移行完了（2026-04-19 時点で BFF クライアント (@parky/bff-client) 経由の呼び出しが 252 箇所、supabase.from() 直叩きは 0 件）。Realtime は直接購読のまま継続（データプレーン例外）。グラスモーフィズムのデザイン
• Admin portal (React + Vite): SPA. BFF migration complete — as of 2026-04-19 there are 252 BFF client (@parky/bff-client) calls and 0 direct supabase.from() calls. Realtime subscriptions stay direct (data-plane exception). Glassmorphism design

移行履歴（完了済）Migration log (completed)

1. Phase 2-A（モバイル先行・完了）: packages/api-spec/ 作成、Workers (api/) 初期化、Flutter は最初から BFF 経由で実装
2. Phase 2-A (mobile first — done): Scaffolded packages/api-spec/, bootstrapped Workers (api/), built Flutter against the BFF from day one
3. Phase 2-B（Web 移行・完了）: @parky/bff-client を新設、web/home は全ページを BFF 経由に、portal/admin も 100% BFF 経由に書き換え完了
4. Phase 2-B (web migration — done): introduced @parky/bff-client; web/home is 100% BFF-backed and portal/admin has been fully rewritten against the BFF
5. Phase 2-C（成熟化・完了）: 2026-04-19 時点で Supabase Edge Functions はすべて Workers に吸収済み（admin-auth → /v1/admin/admins、ai-search → /v1/search/ai、upload-asset → /v1/storage/upload-url、send-push-notification → parky-fcm-dispatch キュー、sync-store-data → parky-store-sync キュー、check-sponsor-proximity → CF Cron Triggers）。Wasabi も廃止し R2 へ完全移行。Supabase 側に残るのは Auth / Realtime / PostgreSQL のみ。ホスティングも全面 Cloudflare Pages 化
6. Phase 2-C (hardening — done): As of 2026-04-19, all Supabase Edge Functions have been absorbed into Workers (admin-auth → /v1/admin/admins, ai-search → /v1/search/ai, upload-asset → /v1/storage/upload-url, send-push-notification → parky-fcm-dispatch queue, sync-store-data → parky-store-sync queue, check-sponsor-proximity → CF Cron Triggers). Wasabi is retired in favor of R2. Supabase retains only Auth / Realtime / PostgreSQL. Hosting fully migrated to Cloudflare Pages