waste-link 設計ドキュメント

産業廃棄物の マニフェスト管理 を行う B2B SaaS「waste-link」の設計判断と設計図を、 開発者向けにまとめたサイトです。排出業者 (discharger) と処理業者 (collector) の双方を 対象に、案件のやり取り・配車・運搬・計量・マニフェスト発行をデジタル化することを目指しています (対象は約 100 社規模)。

このサイトの一次情報は リポジトリの実コード (supabase/migrations/**・apps/**・ packages/**・.github/workflows/**) です。各 ADR には根拠となるファイルと行番号を併記しています。

---

システム全体像

flowchart LR
  subgraph clients["クライアント"]
    Web["Web<br/>Vite + React<br/>(Cloudflare Pages)"]
    Mobile["Mobile<br/>Expo / React Native<br/>(EAS)"]
  end

  API["API<br/>Hono on Cloudflare Workers<br/>service_role 操作 / 公開 /signup"]

  subgraph supabase["Supabase"]
    DB[("PostgreSQL<br/>+ Row Level Security")]
    Auth["Auth (JWT)<br/>app_metadata に<br/>tenant_id / role"]
    Storage["Storage"]
  end

  Web -->|"anon / authed client (RLS 適用)"| DB
  Mobile -->|"anon / authed client (RLS 適用)"| DB
  Web -->|"VITE_API_URL"| API
  API -->|"service_role (RLS バイパス)"| DB
  Web --> Auth
  Mobile --> Auth

• Web / Mobile は基本的に Supabase クライアントから直接 DB を読み書きし、テナント分離は すべて RLS が担保します (ADR 0002 / ADR 0003)。
• API (Hono on Cloudflare Workers) は、service_role を要する管理操作 (メンバー作成等) と 認証不要の公開 /signup を担当します (ADR 0009)。

---

読み方

• はじめて読む場合は ADR 索引 から、関心のある決定を選んでください。
• ADR は MADR 形式 (Title / Status / Context / Decision / Consequences) で、確定済みの設計判断 を 1 件 1 ファイルで記録します。
• 図 (シーケンス図・状態遷移図・概念モデル・C4) は 図セクション に 集約します (順次追加)。
• 画面に出る 派生項目 (計算で求まる値) の算出式・入力ソース・端数/欠損処理は 画面項目の算出方法 に、実コードの file:line 典拠付きでまとめています。
• より手順寄りの運用ドキュメント (デプロイ・認証運用・オンボーディング) は 設計ドキュメント (既存) セクションを参照してください。
• 複数プロダクトを扱う組織での Linear の使い方 (Team / Project / Initiative / Label / View の使い分け) は Linear 運用ハンドブック にまとめています (組織共通のプロダクトマネジメント運用ルール)。

---

アーキテクチャ決定記録 (ADR)

#	タイトル	主な根拠
0001	モノレポ構成 (pnpm + Turborepo)	pnpm-workspace.yaml / turbo.json
0002	バックエンドに Supabase を採用	supabase/config.toml / migration 0
0003	マルチテナント分離を RLS で実現	migration 1 / 2 / 3
0004	login_id 方式の認証	auth-login-id.ts / migration 32 / 35
0005	ロールモデル (処理業者 / 排出業者)	migration 3 / 27
0006	工場スコープのアクセス制御	migration 33 / 43 / 44 / 46
0007	can_drive 能力フラグ	migration 51 / AuthContext.tsx
0008	配車コースモデル	migration 40–42 / 45
0009	API を Cloudflare Workers (Hono) で構築	apps/api/**
0010	環境分割 (dev / prod 2 プロジェクト)	docs/deployment.md / supabase-deploy.yml
0011	公開オンボーディング (招待コード)	migration 48–50 / signup.ts
0012	日次運行ログと燃料の記録	migration 29 / 47 / 22
0013	「準備中」機能のゲーティング	nav-config.tsx
0014	フロントエンド技術選定	apps/web/package.json / index.css
0015	品質ゲート	ci.yml / CONTRIBUTING.md / biome.json
0016	横乗り (当日ルート単位の同乗者)	migration 57 / dispatch-ride-along.ts
0017	マルチテナント RLS のハードニング	migration 53–56

---

この設計書の閲覧について (メンテナ向け)

• ビルドは mkdocs-material + Mermaid (material 標準サポート)。設定は リポジトリ直下の mkdocs.yml、依存は docs/requirements.txt。
• GitHub Pages では公開しません。 このリポジトリは private ですが、現行プラン (GitHub Team) は「Private Pages (アクセス制御)」に非対応 (Enterprise Cloud 限定) で、 Pages を有効化すると URL を知る誰でも閲覧できる公開状態になってしまいます。設計書 (アーキテクチャ / RLS モデル / スキーマ等) の情報開示を避けるため、公開デプロイは 行いません。.github/workflows/docs.yml は ビルド検証のみ (公開なし) です。
• 閲覧方法:
  • private リポジトリの GitHub 上で docs/**.md を直接閲覧 (Mermaid は github.com 上で レンダリングされます)。
  • ローカルで mkdocs serve (下記)。
  • 将来 Enterprise Cloud へ移行すれば Private Pages 化を再検討できます。

• ローカルプレビュー:

  python3 -m venv .venv
  .venv/bin/pip install -r docs/requirements.txt
  .venv/bin/mkdocs serve    # http://127.0.0.1:8000
  

• 既存の docs/*.md や docs/superpowers/** は壊しません。サイトには mkdocs.yml の nav に列挙したページだけを載せ、内部の作業ドキュメント (docs/superpowers/**) と 検証用 SQL は exclude_docs でサイトから除外しています (ファイルは残ります)。