Skip to main content
This page maps the Orbit AI application from UI to deployment. It covers the React frontend, Supabase backend and persistence layer, Electron and Capacitor native wrappers, deployment pipelines, the access model, and what is explicitly out of scope for this repository.

​
System overview

The app is a React 18 single-page application built with Vite. It runs in the browser, inside an Electron desktop shell, and as a Capacitor mobile app. All variants share the same UI bundle and talk to the same Supabase project.

​
Frontend

index.html loads src/main.tsx, which detects desktop versus browser runtime, mounts PwaStatus, and dynamically imports src/App.tsx. Vite uses React SWC, an @ alias pointing to src/, and port 8000 (vite.config.ts). App.tsx installs the following providers before routing:
  • Theme
  • Query Client (React Query)
  • Tooltip and toast
  • Auth
  • Workspace
  • Moderation
  • Router
Pages load lazily. The browser uses BrowserRouter; Capacitor native uses HashRouter. Global query defaults retry once and disable focus refetch. Shared layout components, page modules, Radix-based UI primitives, hooks, and service helpers live under src/components, src/pages, src/hooks, and src/lib.

​
Backend and persistence

The generated typed Supabase client is at src/integrations/supabase/client.ts, with generated database types in types.ts. Browser code calls PostgREST tables and RPCs, Realtime, Storage, and Edge Functions. Function source is under supabase/functions/. Shared provider and billing logic lives in supabase/functions/_shared/. Migrations are ordered in supabase/migrations/, with local project settings in supabase/config.toml. Database tables span profiles, chat and history, workspaces, missions, automations and agents, billing and entitlements, support, device and phone, advertising, and admin operations. Treat migration SQL as the source of truth; generated project.sql may not represent the deployed state.

​
Native clients

Electron main and preload source is under electron/. Packaging is configured in root package.json and build scripts. The renderer tests for window.orbitDesktop and delegates storage, updates, and selected local actions across the preload bridge. Review electron/preload.cjs and security tests before changing exposed native methods. Capacitor config points to dist/. The local notifications plugin is installed, but the complete platform permission flow and parity are open verification items. Browser PWA status code is src/components/PwaStatus.tsx.

​
Deployment

  • npm run cloudflare:deploy builds then deploys; cloudflare:check performs a Wrangler dry run after build.
  • npm run supabase:check and supabase:deploy invoke the bootstrap scripts. Confirm target project and secrets before deployment.
  • Electron Builder outputs to release/electron-0.0.25; GitHub is configured as the publisher.
  • Capacitor sync and build scripts are listed under mobile:* in package.json.
Website/ is a distinct Next.js package and is not the root React app. Its deployment is not established in this repository.

​
Boot sequence

The app starts in this order:
1

Shell loads

The browser or native wrapper loads the app shell.
2

Providers register

App.tsx registers the app providers: auth, workspace, moderation, theme, query client, tooltip, and toast.
3

Router selects

The app decides between BrowserRouter and HashRouter, depending on whether it is running in a native environment.
4

Guards enforce access

Route guards enforce authenticated or role-based access before rendering pages.
5

Pages render

Included pages render within AppLayout or route-specific containers.

​
Route guard rules

The route guard logic in src/App.tsx enforces these conditions:
  • Protected access requires a signed-in user.
  • Staff and admin routes require permission resolution before access is granted.
  • MFA challenges are handled before access continues.
Client-side route guards delay rendering while auth and MFA status loads, and admin or staff gates query role permissions. These guards improve UX but are not a security boundary. Authorization is enforced by Supabase Row Level Security (RLS) and by Edge Functions that validate the user JWT or use server-side secrets for privileged operations. Service keys and provider secrets remain server-side only.

​
Representative edge functions

The Supabase edge functions under supabase/functions/ implement server logic for AI generation and chat operations, moderation, billing sessions and Stripe webhooks, platform automation and mission control, voice transcription and voice commands, account deletion and support flows, and image generation and related API behaviors. Representative functions include:

​
Key source files by feature area

​
Known verification gaps

The following items are implemented in source but their live behavior is not confirmed:
  • Live production deployment status must be verified separately.
  • Backend service availability should be checked in the actual environment.
  • Plan catalogs, billing rules, and entitlement enforcement depend on deployed database state and provider setup.
  • Some routes and features are present in source but may be redirecting or not reachable in the current app flow.
  • Native platform permission flow and parity for Capacitor are open verification items.
  • Live screenshot capture for sign-in, chat, history, settings, and privacy screens needs a test tenant with synthetic data.
  • Test tenant requirements for standard, workspace-member, staff, and admin roles, plus MFA states and entitlements, are not yet confirmed.

​
Scope exclusions

The following are outside the scope of this app architecture page:
  • Legacy directories and standalone page modules that have no active route (for example, podcast, phone, extension, shop)
  • The Website/ Next.js package
  • Internal CI/CD pipeline details
  • Infrastructure and runtime environment configuration beyond what is needed for local development and deployment
For the Audience Engine service architecture, see Audience Engine Architecture.