Skip to content

Discovery Log

Purpose: capture ongoing findings while learning the codebase.
Rule: anything uncertain goes here (not in "official" docs) until verified. - If it's proven + stable it gets promoted into real docs (Architecture / Flows / Runbooks / ADR).

📊 Documentation Progress Tracking

Last updated: 2026-02-24 @ 6:10 AM PST (by Hadrian)

✅ Completed Files (21)

File Section Commit Status
frontend.md Architecture ff725f5 ✅ Pushed
context.md Architecture ff725f5 ✅ Pushed
containers.md Architecture ff725f5 ✅ Pushed
supabase.md Architecture ff725f5 ✅ Pushed
env-vars.md Overview ff725f5 ✅ Pushed
project-map.md Overview a8645af ✅ Pushed
auth.md Flows 3874e9c ✅ Pushed
billing-stripe.md Flows 4b3dc1c ✅ Pushed
webhooks-stripe.md Flows 6adc589 ✅ Pushed
inventory.md Flows 2eed9b7 ✅ Pushed
orders.md Flows 18bee0d ✅ Pushed
repairs.md Flows e23d36e ✅ Pushed
crm.md Flows 8b57464 ✅ Pushed
design.md Flows 5cefc99 ✅ Pushed
payments.md Flows b0a3b28 ✅ Pushed
api/supabase-tables.md API & Data 8f480f6 ✅ Pushed
api/edge-functions.md API & Data 5ec06c4 ✅ Pushed
api/external-apis.md API & Data a13b004 ✅ Pushed
dev/onboarding.md Developer Guide ff095a5 ✅ Pushed
dev/code-structure.md Developer Guide 946a3ed ✅ Pushed
dev/conventions.md Developer Guide f5b4758 ✅ Pushed

🔄 Current Focus

Next area: Operations (deployment docs & runbooks) + wiring into mkdocs.yml

📋 Remaining Items (~2)

Operations:

  • [ ] Polish deployment docs
  • [ ] Runbooks

Docs plumbing:

  • [ ] Wire all sections into mkdocs.yml
  • [ ] Run mkdocs serve and fix broken links
  • [ ] Final review and PR

📈 Progress

  • Completed: 21/22 files (~95%)
  • Committed: multiple commits pushed to docs-architecture
  • Branch: docs-architecture (off main)

Blockers

  • [ ] Access to Supabase project dashboard (URL + permissions)
  • [ ] Missing env vars: __________ (referenced in: __________)
  • [ ] Cannot run locally because: ____

Inferred (needs verification)

  • Inferred: Auth uses Supabase session persisted via ____

    • Evidence: src/... references supabase.auth...
    • Verify by: running login flow + checking storage/cookies

  • Inferred: Stripe webhook updates payment_history

    • Evidence: supabase/functions/...
    • Verify by: sending test webhook event

  • Inferred: Auth role/tenant resolution uses get_tenant_info_for_user RPC

    • Evidence: AuthProvider calls supabase.rpc('get_tenant_info_for_user', { user_id_param: userId })
    • Verify by: inspecting Supabase SQL function definition and associated tables

  • Inferred: Subscription and feature access are backed by Supabase tables and/or Stripe metadata

    • Evidence: useSubscription, useFeatureAccess, subscription-utils, and auth-utils are used by ProtectedRoute
    • Verify by: tracing those hooks/utilities to Supabase queries and data models

  • Inferred: SPA hosting primarily targets Vercel (based on vercel.json), with Cloudflare Pages as an alternative path

    • Evidence: vercel.json at repo root and Cloudflare deployment docs under docs-site/docs/deployment/cloudflare-pages.md
    • Verify by: checking which platform is currently wired in CI/CD and where production DNS points

Findings (verified)

  • Verified: Supabase Edge Functions use Deno.env.get(...) for server secrets.

    • Evidence: supabase/functions/...

  • Verified: Route structure is centralized in src/App.tsx using React Router v6 with BrowserRouter, Routes, and Route.

    • Evidence: src/App.tsx

  • Verified: Global providers wrap the app in the following order: QueryClientProvider → AuthProvider → ThemeProvider → TooltipProvider → Toaster → AppContent.

    • Evidence: src/App.tsx

  • Verified: vercel.json config rewrites all non-asset routes to index.html and disables caching on index.html, which is standard SPA hosting behavior.

    • Evidence: vercel.json

Questions for owner/team

  • Do we have separate Supabase projects for dev/staging/prod?
  • What is the source of truth for subscription status (Stripe vs DB table)?
  • What is the expected local dev workflow (Supabase CLI or hosted only)?
  • Should owner-level routes always bypass subscription checks, or should some owner tools be testable under a specific plan?
  • Which hosting platform is the current production source of truth: Vercel, Cloudflare Pages, or something else?

Risks / concerns

  • Potential risk: ____
    • Why: ____
    • Where: path/to/file
    • Mitigation idea: ____

Next steps

  • [x] Trace route structure: src/main.* → App.* → router
  • [x] Inventory all env vars (import.meta.env, Deno.env.get) → env-vars.md
  • [x] Document Architecture section (frontend, context, containers, supabase)
  • [x] Document auth flow → flows/auth.md
  • [x] Document billing/stripe flow → flows/billing-stripe.md
  • [x] Document webhooks flow → flows/webhooks-stripe.md
  • [x] Document inventory flow → flows/inventory.md
  • [x] Document orders flow → flows/orders.md
  • [x] Document repairs flow → flows/repairs.md
  • [x] Document CRM & clients flow → flows/crm.md
  • [x] Document design studio & library flow → flows/design.md
  • [x] Document payments, invoices & pay links flow → flows/payments.md
  • [x] Document Supabase tables overview → api/supabase-tables.md
  • [x] Document edge functions overview → api/edge-functions.md
  • [x] Document external APIs overview → api/external-apis.md
  • [x] Add Developer Onboarding guide → dev/onboarding.md
  • [x] Add Code Structure guide → dev/code-structure.md
  • [x] Add Conventions guide → dev/conventions.md
  • [ ] Polish Operations section
  • [ ] Wire all sections into mkdocs.yml
  • [ ] Run mkdocs serve and fix broken links
  • [ ] Final review and PR