Skip to content

Project Map

This page is the “you are here” map of the repo: what each folder does, where the app starts, and where backend behavior lives (Supabase + Edge Functions + Stripe).

Use this as your starting point before drilling into Architecture, Flows, or API/Data.

Repo layout (high level)

Top-level directories in this repo:

  • src/ – Vite/React SPA frontend
    • Entrypoints: index.html, src/main.tsx, src/App.tsx
    • Routes and screens under src/pages/
    • Shared components under src/components/
    • Global contexts/hooks under src/contexts/, src/hooks/
    • Supabase client integration under src/integrations/
  • supabase/ – Supabase backend definition
    • supabase/config.toml – Supabase project/CLI config
    • supabase/migrations/ – schema + RLS migration scripts
    • supabase/functions/ – edge functions (Stripe, affiliates, nameplate, etc.)
  • nextjs/ – Next.js migration project (App Router)
    • Parallel implementation of the frontend using Next.js
    • Uses NEXT_PUBLIC_SUPABASE_* env vars and its own routing structure
    • See MIGRATION.md for the migration plan

  • public/ – Static assets for the SPA

  • diagnostic-sqls/ – Ad-hoc SQL scripts

    • One-off diagnostics and repair scripts used by maintainers
  • docs-site/ – Documentation site (MkDocs + Material)
    • docs-site/mkdocs.yml – docs configuration and navigation
    • docs-site/docs/ – markdown content (overview, architecture, flows, etc.)
    • docs-site/overrides/ – theme overrides (if used)
    • docs-site/_internal/ – internal notes excluded from built docs
  • docs/ – Additional documentation or notes (if present)
  • supabase/ – (see above) core backend config
  • MIGRATION.md – Vite → Next.js migration manual
  • vercel.json – Vercel SPA rewrite and cache configuration
  • package.json / package-lock.json – Node dependencies and scripts

Where the app actually runs

  • Today, the Vite SPA under src/ is the primary frontend.
  • The Supabase project under supabase/ is the backend (DB + Auth + Edge Functions).
  • The Next.js app under nextjs/ is a migration target and may not yet be live in production.

How to navigate the docs

  • Start here (Project Map) to understand folder layout.
  • Then read Architecture → System Context for the big-picture view.
  • Use Architecture → Containers to see how the system is split across SPA, Supabase, Stripe, and hosting.
  • Use Frontend Architecture to find routes, providers, and feature modules.
  • Use Supabase Architecture to understand schema, auth, RLS, and edge functions.
  • Use Flows to see end-to-end journeys (auth, billing, inventory, orders, repairs, etc.).
  • Use API & Data for table and edge-function details once that section is filled in.

Architecture (click to drill down)

flowchart LR
  U[User Browser] --> FE["Frontend SPA(NEXT.js)"]
  FE --> SBAUTH[Supabase Auth]
  FE --> SBD[(Supabase DB)]
  FE --> SBFX[Supabase Edge Functions]
  SBFX --> ST[Stripe]
  FE --> ST

  subgraph Hosting
    HOST["Hosting (Vercel / Cloudflare Pages)"]
  end

  HOST --> FE

  click FE "../architecture/frontend/" "Frontend architecture and routes"
  click SBAUTH "../architecture/supabase/" "Supabase auth & roles"
  click SBD "../architecture/supabase/" "Supabase schema & RLS"
  click SBFX "../api/edge-functions/" "Edge functions API surface"
  click ST "../flows/billing-stripe/" "Billing & Stripe flows"
  • The browser talks only to the frontend SPA.
  • The SPA uses Supabase JS client for auth and DB, and calls edge functions for secure operations.
  • Stripe is integrated via:
  • Hosted checkout/portal (redirects to /checkout/success, /checkout/cancel, /upgrade).
  • Webhooks handled by supabase/functions/stripe-webhook.
  • Hosting (Vercel/Cloudflare Pages) serves the SPA and provides frontend env vars.

Where to look next