アーキテクチャ 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.

プロダクトスコープProduct scope

Parky は 「駐車場検索ポータル + 情報メディア + オーナー掲載 + 外部送客」を中核に据えたサービスです。 駐車場予約機能 / 駐車場決済機能は実装対象外（2026-04-26 確定）。 資金決済法・媒介行為リスクの低減と、SEO・メディア型ビジネスへの集約、競合（Akippa / 特P / B-Times）との差別化を 「予約以外の軸」で取る方針のため、以降のドキュメントでも 予約フロー / Stripe / GMV / テイクレート 等は登場しません。

Parky's product core is parking discovery + information media + owner listings + outbound referral. Parking reservation and parking payment are explicitly out of scope (decided 2026-04-26). We intentionally compete on search UX, content depth, and owner experience instead of GMV / take-rate, so booking flows, Stripe billing, and reservation-side concepts do not appear in this documentation.

クライアント接続層の一元化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"]
    OP["Owner Portal
React + Vite"]
    MP["Marketing 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
5 schemas / 128 base tables + 12 views")]
    RT["Realtime"]
  end

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

  subgraph External["External services"]
    MB["Mapbox"]
    FCM["FCM"]
    LLM["LLM API
(Claude/Gemini/OpenAI)"]
    STORE["Play/App Store"]
    SENTRY["Sentry
Issues / Performance"]
  end

  CRON["CF Cron Triggers"]

  MA -->|"/v1/*"| CFW
  WA -->|"/v1/*"| CFW
  AP -->|"/v1/admin/*"| CFW
  OP -->|"/v1/owner/*"| CFW
  MP -->|"/v1/marketing/*"| CFW

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

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

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

  CRON --> CFW

  CFW --> DB
  CFW -->|mint presign| WSB
  CFW --> FCM
  CFW --> LLM
  CFW --> STORE
  CFW -->|"capture (5xx/unhandled)"| SENTRY

  MA -.->|"capture (Dart)"| SENTRY
  WA -.->|"capture (Astro/Island)"| SENTRY
  AP -.->|"capture (React)"| SENTRY
  OP -.->|"capture (React)"| SENTRY
  MP -.->|"capture (React)"| SENTRY

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

  %% クリック時はハンドラ（app.js の initInteractiveArchitecture）で
  %% 関連シェイプをハイライト表示する。ページ遷移はしない。

制御面と データ面の分離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

DB schema 構成DB schema layout

Supabase Postgres は用途別に 5 schema に分離（2026-04-21 reorg）。新規テーブル作成時は必ず schema を判定し、 CREATE TABLE <schema>.<table> で明示する。admin / marketing / analytics は anon / authenticated 不可 （schema レベルで REVOKE）、アプリから触るには必ず BFF 経由。

Supabase Postgres is split into 5 schemas by purpose (reorg 2026-04-21). Every new table must explicitly target a schema with CREATE TABLE <schema>.<table>. admin / marketing / analytics deny anon / authenticated at the schema level — clients can only reach them through the BFF.

さらに RPC 専用の bff_only schema（ADR-0012: client 直叩き禁止、SECURITY DEFINER）と pg_cron ジョブ管理用の infra schema が併存する。auth_helpers は Supabase Auth との JWT 解決ユーティリティ専用。

Two more schemas live alongside the five: bff_only (RPC-only / SECURITY DEFINER, no client GRANT — see ADR-0012) and infra (pg_cron job tracking). auth_helpers houses Supabase Auth JWT resolution utilities.

詳細・テーブル一覧は データモデル、列挙値の codes マスター方針は 共通規約 を参照。 DB 関数 (RPC) は default で bff_only schema 配置、client は BFF endpoint 経由でしか叩けない（4 層防御 L1〜L4）。

See Data model for the full table list and Conventions for the codes master policy. DB functions (RPCs) default to the bff_only schema — clients reach them only via BFF endpoints (a 4-layer L1–L4 defense).

Cron スロット（Cloudflare Cron Triggers）Cron slots (Cloudflare Cron Triggers)

api/wrangler.admin.toml の [triggers] crons で配線（マルチ Worker は ADR-0010）。現状 6 スロット稼働。ハンドラは api/src/cron/、cron 式の SSoT は api/src/cron-constants.ts の CRON_JOBS、実行分岐は api/src/app-core.ts の dispatchScheduled()。

Wired in api/wrangler.admin.toml under [triggers] crons (multi-worker split per ADR-0010). Currently 6 slots are active. Handlers live under api/src/cron/, the cron-expression SSoT is the CRON_JOBS constant in api/src/cron-constants.ts, and dispatch happens in dispatchScheduled() in api/src/app-core.ts.

近接検知（スポンサー付近の通知）はモバイル側のネイティブジオフェンスで行うため、サーバー側 cron では扱わない。 Google Places 取込は PLACES_WEEKLY cron（毎週土曜 17:00 UTC）と POST /v1/admin/places/import/all の両ルートで parky-places-refresh queue を駆動する。

Sponsor proximity detection runs on-device via native geofences, so no cron slot covers it. Google Places import is driven by both the PLACES_WEEKLY cron (Sat 17:00 UTC) and the manual POST /v1/admin/places/import/all trigger — both feed the parky-places-refresh queue.

Queue 構成（Cloudflare Queues）Queue topology (Cloudflare Queues)

チャネル別 API マウントChannels and route mounts

Workers は単一 API サーフェス（/v1/*）の中で、クライアント種別ごとにサブツリーを切り、認可ミドルウェアで型安全に分離しています。

Under the single /v1/* surface, Workers carve out per-client subtrees and isolate each with its own authorization middleware.

ミドルウェア順序: requestId → cachePublicRead → cors → [routes] → errorHandler。エラーは {error: {code, message, request_id}} で統一、Zod バリデーション失敗は 422 を返す。詳細は エラーカタログ。

Middleware order: requestId → cachePublicRead → cors → [routes] → errorHandler. Errors come back as {error: {code, message, request_id}}; Zod failures return 422. See the error catalog.

Worker 分割と route の対応Worker split and route mapping

単一 /v1/* サーフェスはチャネル別の Worker（wrangler.public.toml / wrangler.admin.toml / wrangler.marketing.toml）にデプロイされ、CPU 上限 / 障害ドメイン / 機密境界を分離する（ADR-0010）。binding ID の SSoT は wrangler.shared-bindings.toml。2026-05-11 に store-sync 専用 Worker (skeleton) は削除済、queue consumer は admin Worker に集約。

The single /v1/* surface is deployed across channel-specific Workers (wrangler.public.toml / wrangler.admin.toml / wrangler.marketing.toml) to isolate CPU limits, blast radius, and secret boundaries (ADR-0010). Binding-ID SSoT lives in wrangler.shared-bindings.toml. The dedicated store-sync Worker skeleton was removed on 2026-05-11; its queue consumer now runs inside the admin Worker.

flowchart LR
  subgraph Hosts["Public hostnames"]
    HPUB["api.parky.co.jp"]
    HADM["admin-api.parky.co.jp"]
    HMKT["marketing-api.parky.co.jp"]
  end

  subgraph Workers["Cloudflare Workers"]
    WPUB["parky-api-public
wrangler.public.toml"]
    WADM["parky-api-admin
wrangler.admin.toml
+ all crons (6 slots)
+ all queue consumers
(store-sync / FCM / Places / X_AI)"]
    WMKT["parky-api-marketing
wrangler.marketing.toml"]
  end

  HPUB --> WPUB
  HADM --> WADM
  HMKT --> WMKT

  WPUB -->|/v1/parking-lots, /v1/articles, /v1/me/*, /v1/search/*, ...| ROUTES1[end-user routes]
  WADM -->|/v1/admin/*| ROUTES2[admin routes]
  WMKT -->|/v1/marketing/*| ROUTES3[marketing routes]

  WADM -.->|consumes parky-store-sync, parky-fcm-dispatch ...| Q[(Cloudflare Queues)]

認証フロー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.

Mobile → BFF は ViewEnvelope 契約Mobile → BFF uses the ViewEnvelope contract

モバイルアプリ（Flutter）が Mobile BFF の View Endpoint（/v1/views/*）を叩くと、 画面描画に必要な情報が ViewEnvelope という統一エンベロープで返ります。Parky は Server-Driven UI Level 3（Data + Validation + Navigation + UI Config）を採用しており、 UI コンポーネント構造はサーバー配信しない（そこは Flutter の責任）。 サーバーが担うのは data（ドメインデータ）／ui_config（文言・feature flag・theme hint）／ navigation（次画面 Hint）／validation（サーバー駆動ルール）／ states（error / empty / skeleton 指示）／fallback_behavior（オフライン / 認証エラー / バージョン不整合の振る舞い）／ meta（server_time / cache_key / min_app_version / sunset_date）。 クライアントは全 /v1/* 呼び出しで X-App-Version ヘッダーを必ず送信し、BFF が meta.min_app_version と突き合わせて force_update / degrade / ignore を画面単位で指示する。

When the Flutter mobile app hits a Mobile BFF View endpoint (/v1/views/*), the response is wrapped in the unified ViewEnvelope. Parky runs on Server-Driven UI Level 3 (Data + Validation + Navigation + UI Config); UI component structure is never shipped from the server — that stays with Flutter. The server owns data (domain data), ui_config (messages, feature flags, theme hint), navigation (next-screen hints), validation (server-driven rules), states (error / empty / skeleton directives), fallback_behavior (offline / auth error / version mismatch behavior), and meta (server_time / cache_key / min_app_version / sunset_date). The client must send X-App-Version on every /v1/* call, and the BFF compares it with meta.min_app_version to pick force_update / degrade / ignore per screen.

クライアント別の特徴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, and camera
• Web 版（Astro）: 静的 SSG + Islands。SEO 最重視。検索・地図は島（Island）として JS 化。公開データアクセスは @parky/bff-client 経由で /v1/* を呼ぶ。ビルド時に API のヘルスチェックを挟んで SSG を焼く
• Web app (Astro): SSG with Islands, SEO-first; search and map hydrate as islands. Public reads go through @parky/bff-client against /v1/*. A build-time API health check gates SSG rendering
• 管理者ポータル（React + Vite）: SPA。データアクセスは @parky/bff-client 経由で /v1/admin/* を呼ぶ。Realtime は直接購読（データプレーン例外）。グラスモーフィズムのデザイン
• Admin portal (React + Vite): SPA. Data access goes through @parky/bff-client against /v1/admin/*. Realtime subscriptions stay direct as a data-plane exception. Glassmorphism design
• オーナーポータル（React + Vite）: SPA。駐車場オーナー向けのセルフサービス画面（13 画面）。Supabase Auth（メール + PW、招待トークン経由で新規作成）で認証し、BFF の /v1/owner/* を requireOwner 経由で呼ぶ。デプロイは Cloudflare Pages（dev-owner.parky.co.jp）
• Owner portal (React + Vite): SPA — 13 self-service screens for parking owners. Supabase Auth (email + password, onboarded via invitation tokens) gates access; the BFF path is /v1/owner/* behind requireOwner. Deployed to Cloudflare Pages (dev-owner.parky.co.jp)
• マーケティングポータル（React + Vite）: SPA。SNS（X / Instagram）運用・ニュースレター配信・キャンペーン管理・アナリティクス・コンテンツ管理を担う。admins テーブル + marketing:* 権限で認可。OAuth リフレッシュトークンは Supabase Vault（pgcrypto）で暗号化保管。デプロイは Cloudflare Pages（dev-marketing.parky.co.jp）
• Marketing portal (React + Vite): SPA. Owns SNS ops (X / Instagram), newsletter delivery, campaigns, analytics, and content. Authorized via the admins table + marketing:* permissions. OAuth refresh tokens are encrypted in Supabase Vault (pgcrypto). Deployed to Cloudflare Pages (dev-marketing.parky.co.jp)

監視・観測性 (Sentry + Logpush)Monitoring & observability (Sentry + Logpush)

Parky の観測性は Cloudflare Workers Logs (Logpush → R2) と Sentry の役割分担で構成しています。

Observability is split between Cloudflare Workers Logs (Logpush → R2) and Sentry.

BFF (Workers) では api/src/lib/sentry.ts が toucan-js をラップし、middleware/error-handler.ts が 5xx と未処理例外を capture。app-core.ts で初期化します。 PII 保護: request body / cookies / クライアント IP は redact。許可ヘッダーは user-agent / x-app-version / x-request-id / accept-language のみ送信します（api/src/lib/sentry.ts L52–60）。 各クライアントは Mobile (sentry_flutter) / Web (@sentry/astro) / Admin・Owner・Marketing Portal (@sentry/react) の SDK で連携。詳細は ops / sentry-setup、Logpush との段階展開は ops / sentry-logpush-rollout、役割分担の運用詳細は ops / logging を参照。

On the BFF (Workers), api/src/lib/sentry.ts wraps toucan-js, and middleware/error-handler.ts captures 5xx + unhandled exceptions. Initialization happens in app-core.ts. PII protection: request body, cookies, and client IP are redacted. Only user-agent / x-app-version / x-request-id / accept-language headers are forwarded (api/src/lib/sentry.ts L52–60). Clients wire their own SDKs: Mobile (sentry_flutter) / Web (@sentry/astro) / Admin · Owner · Marketing Portal (@sentry/react). See ops / sentry-setup, ops / sentry-logpush-rollout, and ops / logging.

BFF 内部コード構造BFF internal code structure

Parky の BFF（parky/api/）は 4 層構造（bff / core / data / schema） + shared / app で構成する。 トップレベルを層で切り、各層の内部は層に自然な軸でさらに分割する。 単一 Cloudflare Workers デプロイのモジュラーモノリスで、層間通信は関数呼び出し。

The BFF (parky/api/) is organised as a 4-layer structure (bff / core / data / schema) + shared / app. The top level is layered; each layer is subdivided by an axis natural to that layer. A single-deploy modular monolith on Cloudflare Workers; inter-layer communication is by function calls.

層とその責務Layers and responsibilities

依存方向（ESLint で機械強制）Dependency direction (enforced by ESLint)

flowchart TD
  BFF[bff/] --> CORE[core/]
  BFF --> SV[schema/view/]
  BFF --> SD[schema/domain/]
  CORE --> DATA[data/]
  CORE --> SD
  CORE --> SR[schema/row/]
  DATA --> SR
  DATA --> SHARED[shared/]
  CORE --> SHARED
  BFF --> SHARED
        

• bff → core → data が正方向。逆参照は禁止
• Forward flow is bff → core → data; reverse imports are forbidden
• schema/view は bff 専用（core / data は import 禁止）
• schema/view belongs to bff only — core / data cannot import it
• schema/row は data 専用（core / bff は import 禁止）
• schema/row belongs to data only — core / bff cannot import it
• 単純な read-only CRUD は core 省略可（bff → data 直呼び）。ロジック出現時に core 追加
• Pure read-only CRUD may skip core (bff → data direct); add core once business logic appears

data 層の実装方針 (postgres.js + raw SQL hybrid)data layer (postgres.js + raw SQL hybrid)

data 層の永続化は postgres.js（lib/db.ts）+ raw SQL タグ付きテンプレート + Supabase 自動生成型（schema/row/ = Supabase が list_tables から生成した DB 列型）の hybrid 構成です。 Drizzle 等の TypeScript ORM は採用しない（2026-04-27 確定）。

The data layer combines postgres.js (lib/db.ts) + raw SQL tagged templates + Supabase-generated row types (schema/row/, generated from list_tables). No TypeScript ORM (Drizzle and friends are explicitly off the table) — finalized 2026-04-27.

• 接続: lib/db.ts の postgres(env.HYPERDRIVE.connectionString, ...)。Hyperdrive がプーリング＋グローバルキャッシュを担う
• Connection: postgres(env.HYPERDRIVE.connectionString, ...) in lib/db.ts. Hyperdrive provides pooling + global cache
• クエリ: タグ付きテンプレート sql`SELECT ... FROM public.parking_lots WHERE id = ${id}` で SQL injection 安全＋型推論
• Queries use tagged templates — sql`SELECT ... FROM public.parking_lots WHERE id = ${id}` — for injection safety and inference
• 列型は schema/row/（Supabase MCP で再生成可能）。data 層が schema/row → schema/domain の変換を担う
• Column types live in schema/row/ (regenerated via Supabase MCP). data handles row → domain translation
• SELECT * 禁止 lint と callRpc 型推論ヘルパで保守漏れを防止（[Phase 1+2+3 完了](https://...) で残違反 0）
• A SELECT * ESLint gate and a callRpc type-inference helper guard against drift (Phase 1+2+3 closed all violations)
• 重トランザクション・行レベルロックが必要なロジックは PG 関数 (bff_only.*) として DB 内に実装し、data 層から callRpc 経由で呼ぶ
• Heavy transactional logic / row-level locking lives as PG functions (bff_only.*) and is invoked from data via callRpc

Multi-channel BFFMulti-channel BFF

同じ core 機能を異なる client（mobile / admin / owner / marketing）で提供する時は、 bff/<channel>/ を並置する。ビジネスルールは core に一元化され、 channel ごとに異なる View Model だけが bff に出る。

To expose the same core capability to different clients (mobile / admin / owner / marketing), place bff/<channel>/ folders side-by-side. Business rules stay centralized in core; only channel-specific View Models live in bff.