Containers¶

This page describes the system using a C4-style container view: the major runtime pieces, how they are deployed, and how they interact.

At a high level, Workbench AI is:

• A single-page application (SPA) built with Vite + React Router
• Backed by Supabase (Postgres, Auth, Storage, Edge Functions)
• Integrated with Stripe for billing and payments
• Deployed as a static app on a hosting platform (Cloudflare Pages or similar) that serves the SPA and proxies to Supabase/Stripe

Container overview¶

flowchart LR
  U[User Browser] --> SPA["Frontend SPA (Vite + React)"]
  SPA --> SBAUTH[Supabase Auth]
  SPA --> SBD[(Supabase Postgres DB)]
  SPA --> SBFX[Supabase Edge Functions]
  SBFX --> ST[Stripe]
  SPA --> ST

  click SPA "../architecture/frontend/" "Frontend architecture and routes"
  click SBAUTH "../architecture/supabase/" "Supabase auth & tenant model"
  click SBD "../architecture/supabase/" "Supabase schema overview"
  click SBFX "../api/edge-functions/" "Edge functions API surface"
  click ST "../flows/billing-stripe/" "Billing & Stripe flows"

Frontend SPA (Vite + React Router)¶

Technology

• React 18 SPA built with Vite
• Routing via React Router v6
• Data fetching with React Query
• Deployed as static assets (HTML, JS, CSS) served from an edge hosting provider

Responsibilities

• Renders all UI for:
  • Marketing/public pages (landing, pricing, terms, etc.)
  • Auth flows (login, signup, callback, clear session)
  • Owner dashboard and management tools
  • Store dashboard (inventory, orders, clients, design studio, repairs, payments)
  • Tools and AI helpers (blog writer, scrap calculator, etc.)
• Manages client-side state:
  • Auth/session context (backed by Supabase auth)
  • Theme (light/dark)
  • React Query caches for data from Supabase/edge functions
• Calls out to Supabase (auth and database), Supabase edge functions, and Stripe checkout endpoints.

Deployment

• Built with vite build into a static bundle.
• Served by a static hosting platform (e.g. Cloudflare Pages or Vercel static hosting).
• vercel.json rewrites all non-asset paths to index.html so React Router can handle routing client-side:

{
  "rewrites": [{"source": "/((?!.*\\..*$).*)", "destination": "/index.html"}],
  "headers": [
    {
      "source": "/index.html",
      "headers": [{"key": "Cache-Control", "value": "no-cache, no-store, must-revalidate"}]
    }
  ]
}

Statefulness

• Stateless from the server’s perspective (static files only).
• Client holds transient state:
  • Supabase session (via Supabase JS client)
  • Cached profile/tenant/role in localStorage
  • React Query cache in memory

Interactions

• Uses Supabase client to:
  • Sign in/out users and manage sessions
  • Query/update tables in Postgres
• Calls Supabase Edge Functions for server-side logic (e.g. webhooks, secure operations).
• Redirects to Stripe for hosted checkout and customer billing flows.
• Receives Stripe completion/cancellation redirects at /checkout/success, /checkout/cancel, /upgrade.

Supabase (Postgres + Auth + Storage + Edge Functions)¶

Technology

• Supabase managed Postgres instance
• Supabase Auth for user accounts and sessions
• Row-Level Security (RLS) on application tables
• Edge Functions (Deno) for server-side logic (including Stripe webhook handling)
• Optional Storage for file assets (if configured in this project)

Responsibilities

• Stores all core application data:
  • Users, profiles, tenants/companies, roles
  • Inventory, orders, clients/CRM data, appointments
  • Subscription state and any derived billing data
  • Audit/history tables as needed
• Enforces data access rules:
  • RLS policies tying rows to tenants/companies
  • Owner vs tenant access
• Exposes server-side endpoints via Edge Functions:
  • Stripe webhooks
  • Any backend operations that must not run from the browser

Deployment

• Managed Supabase project.
• Schema and configuration defined under supabase/ in this repo:
  • supabase/migrations/ – SQL migrations driving Postgres schema
  • supabase/functions/ – Edge Functions deployed to Supabase
  • supabase/config.toml – project/CLI configuration

Statefulness

• Stateful: the central source of truth for all application data.
• Supabase Auth maintains session state and refresh tokens.
• Edge Functions are stateless between invocations but operate on the stateful database.

Interactions

• SPA uses the Supabase JS client (from integrations/supabase) to:
  • Authenticate users
  • Run queries and mutations
• Stripe uses a Supabase Edge Function endpoint as a webhook target.
• Edge Functions use Stripe’s SDKs and Supabase’s DB client to orchestrate payments → DB updates.

Stripe (Billing, Checkout, Webhooks)¶

Technology

• Stripe API and dashboard
• Hosted checkout and billing portal pages
• Webhooks sent to Supabase Edge Functions

Responsibilities

• Manages:
  • Subscription plans (e.g. Professional, Enterprise)
  • Payment methods and invoices
  • One-off payments or usage-based billing (if configured)
• Sends webhooks for:
  • Checkout session completed/canceled
  • Subscription created/updated/canceled
  • Invoice/payment events

Deployment

• Configured via Stripe dashboard (products, prices, webhooks).
• Webhook endpoint(s) point at Supabase Edge Function URLs for this project.

Statefulness

• Stripe is stateful for billing and payment records.
• Application state typically mirrors a subset of this into Supabase tables for faster queries and business logic.

Interactions

• SPA:
  • Initiates checkout or billing portal sessions (via Stripe or a backend function).
  • Redirects the user to Stripe and then back to /checkout/success, /checkout/cancel, or /upgrade.
• Supabase Edge Functions:
  • Receive Stripe webhooks.
  • Validate signatures.
  • Update Supabase tables (subscription status, payment records, etc.).

Hosting (Cloudflare Pages / Vercel)¶

Technology

• Static site hosting platform:
  • Cloudflare Pages, Vercel, or similar
• Edge CDN delivering the compiled SPA assets.

Responsibilities

• Serves index.html, JS, CSS, and static assets from public/.
• Applies a SPA rewrite rule so that any non-asset path (e.g. /clients/appointments) returns index.html and lets React Router handle it.
• Handles environment configuration for the frontend (public env vars), typically via project settings.

Deployment

• Build command: npm run build (Vite).
• Output directory: Vite build output (e.g. dist/, depending on config).
• vercel.json present in the repo suggests Vercel compatibility; cloudflare-pages docs in docs-site/docs/deployment/cloudflare-pages.md describe Cloudflare deployment.

Statefulness

• Hosting platform is stateless; all state lives in the browser (SPA), Supabase, and Stripe.

Interactions

• Receives HTTPS requests from browsers globally.
• Delivers cached static assets.
• Does not terminate API requests itself; Supabase and Stripe endpoints are called directly from the browser or edge functions.