System Context¶

This page explains who uses Workbench AI, what problems it solves, and which external systems it relies on. Use this as the mental model before diving into containers, flows, or individual modules.

Primary actors¶

Workbench AI is built for retail jewelry businesses.

• Store owners ("owners")
  • Own the account and subscription.
  • Manage companies/tenants, staff user access, and billing.
  • Configure defaults, feature flags, and pricing behavior.

• Staff / in‑store users ("tenants" / standard users)
  • Use the app day‑to‑day on the sales floor or in the back office.
  • Create and manage inventory, orders, repairs, clients, and payments.
  • Use AI‑powered tools to generate content (e.g. blog posts) and documents (e.g. certificates).

• Affiliates / external partners
  • May refer new stores or collaborate with the owner.
  • Managed from owner‑only views (affiliates lists, analytics).

• System administrators (internal team)
  • Maintain infrastructure and configuration.
  • Analyze analytics, troubleshoot issues, and evolve the platform.

These roles are reflected in the code via roles (owner, tenant, admin) and feature flags, surfaced through AuthContext, ProtectedRoute, and feature access hooks.

High‑level capabilities¶

From a business perspective, Workbench AI provides:

• Inventory management

  • Maintain product catalog and stock levels.
  • View, add, and edit items through /inventory routes and related components.

• Orders & work orders

  • Track customer orders and their lifecycle.
  • Manage work orders for repairs or custom pieces.
  • Routes under /orders, including Active, Completed, and Work Orders views.

• Repairs and pricing tools

  • Guided calculators for common jewelry repairs:
    1. Ring sizing up/down
    2. Soldering chain/bracelet
    3. Replacing clasps
    4. Tightening stones, prong rebuilds
    5. Rhodium plating, polish/clean
  • Accessible via /repairs/* and related tools like /repair-pricing.

• Clients & CRM

  • Store customer profiles and history.
  • Manage a simple CRM and appointment calendar.
  • Routes under /clients, /clients/crm, /clients/appointments.

• Design studio & library

  • Nameplate generator and CAD file library.
  • Reference/library of designs and components for repeat use.
  • Routes such as /design/nameplate, /design/cad-library, /library.

• Payments & billing

  • Take payments (invoices, pay links) through /payments routes.
  • Manage subscription/billing for the SaaS itself through /billing and /settings/billing.
  • Stripe is used for subscription billing and checkout.

• AI‑powered helpers

  • Blog post writer and other content tools under /blog-writer and /tools/* routes.
  • These tools help generate marketing content, certificates, and other documents tailored to the jewelry domain.

• Analytics & reporting

  • Dashboards for tracking business performance.
  • Owner analytics under /owner/analytics, overall analytics under /analytics.

These capabilities are implemented as feature areas in the frontend (pages/ + components/) backed by Supabase tables and edge functions.

External systems¶

Workbench AI does not run its own monolithic backend; instead it composes several managed services:

• Supabase

  • Postgres database for all application data (companies, users, inventory, orders, repairs, clients, subscriptions, etc.).
  • Supabase Auth for user accounts and sessions.
  • Row‑Level Security (RLS) policies for multi‑tenant isolation.
  • Edge Functions for server‑side logic, including Stripe webhooks and other sensitive operations.

• Stripe

  • Subscription billing and payments for the SaaS offering.
  • Checkout sessions and customer portal flows.
  • Webhooks powering updates to subscription and billing state in Supabase.

• Hosting platform (Vercel / Cloudflare Pages)

  • Serves the compiled SPA (Vite build output) via a global CDN.
  • Applies a SPA rewrite rule so that all non‑asset routes return index.html, letting React Router handle routing.
  • Injects frontend environment variables (e.g. Supabase URL, public keys) at build time.

• AI providers (inferred)

  • AI‑driven tools (blog writer, certificates, etc.) likely call out to one or more AI APIs.
  • Integration details live under src/integrations/ and related hooks.

Context diagram¶

flowchart LR
  subgraph Store
    O[Store Owner]
    S["Staff / In‑store Users"]
  end

  subgraph Workbench_AI[Workbench AI SPA]
    UI["Frontend SPA (Vite + React)"]
  end

  O --> UI
  S --> UI

  UI --> SBAUTH[Supabase Auth]
  UI --> SBD[(Supabase DB)]
  UI --> SBFX[Supabase Edge Functions]
  SBFX --> ST[Stripe]
  UI --> ST

  subgraph External
    ST[Stripe]
    HOST["Hosting (Vercel / Cloudflare Pages)"]
    AI["AI Provider(s)"]
  end

  HOST --> UI
  UI --> AI

  click UI "../architecture/frontend/" "Frontend architecture and routes"
  click SBAUTH "../architecture/supabase/" "Supabase auth & roles"
  click SBD "../architecture/supabase/" "Supabase schema overview"
  click SBFX "../api/edge-functions/" "Edge functions and webhooks"
  click ST "../flows/billing-stripe/" "Billing & Stripe flows"

At this level:

• Actors (owners, staff) always interact through the SPA.
• The SPA is served by a hosting platform and talks directly to Supabase and Stripe.
• Supabase owns application data and auth; Stripe owns billing data.
• AI providers are used as helpers, not as the primary source of truth.

How to read this in context¶

• Use System Context (this page) to understand the business and external landscape.
• Use Containers to see how the system is broken down into deployable runtimes.
• Use Frontend Architecture to understand how UI, routing, and providers are structured.
• Use Supabase Architecture to understand data, auth, and edge functions.
• Use Flows to see how specific user journeys (auth, billing, inventory, repairs) cross these boundaries.