> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.orbitdev.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Orbit AI App Architecture: Frontend, Backend, and Deployment

> How the Orbit AI app is structured from React frontend through Supabase backend to Cloudflare and Electron deployment. Covers routing, persistence, native wrappers, and access model.

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.

```mermaid theme={"dark"}
flowchart LR
  Browser[Browser / PWA] --> UI[React 18 + Vite UI]
  Electron[Electron renderer + preload] --> UI
  Capacitor[Android / iOS WebView] --> UI
  UI --> Router[React Router + auth/workspace providers]
  Router --> DB[Supabase Auth / PostgREST / Realtime / Storage]
  Router --> Edge[Supabase Edge Functions]
  Edge --> DB
  Edge --> AI[Configured AI providers]
  Edge --> Stripe[Stripe]
  UI --> OS[Electron native bridge]
```

## 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

| Target | Pipeline | Key files |
| - | - | - |
| Browser / PWA | Cloudflare Worker static assets with SPA fallback | `dist/`, `wrangler.jsonc` |
| Desktop | Electron Builder to GitHub releases | `package.json`, `release/electron-0.0.25` |
| Mobile | Capacitor sync and native build | `capacitor.config.ts`, `mobile:*` scripts |
| Supabase | Bootstrap scripts and function deploy | `scripts/supabase-bootstrap.sh`, `supabase/config.toml` |

* `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`.

<Note>
  `Website/` is a distinct Next.js package and is not the root React app. Its deployment is not established in this repository.
</Note>

## Boot sequence

The app starts in this order:

<Steps>
  <Step title="Shell loads">
    The browser or native wrapper loads the app shell.
  </Step>

  <Step title="Providers register">
    `App.tsx` registers the app providers: auth, workspace, moderation, theme, query client, tooltip, and toast.
  </Step>

  <Step title="Router selects">
    The app decides between `BrowserRouter` and `HashRouter`, depending on whether it is running in a native environment.
  </Step>

  <Step title="Guards enforce access">
    Route guards enforce authenticated or role-based access before rendering pages.
  </Step>

  <Step title="Pages render">
    Included pages render within `AppLayout` or route-specific containers.
  </Step>
</Steps>

## 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:

| Function | What it covers |
| - | - |
| `supabase/functions/orbit-chat/` | AI chat generation and message handling |
| `supabase/functions/run-agent/` | Agent execution |
| `supabase/functions/mission-control/` | Mission and workflow control |
| `supabase/functions/stripe-webhook/` | Stripe event handling |
| `supabase/functions/create-payment-session/` | Payment session creation |
| `supabase/functions/create-billing-portal/` | Billing portal sessions |
| `supabase/functions/delete-account/` | Account deletion flow |
| `supabase/functions/generate-image/` | Image generation |

## Key source files by feature area

| Feature area | Key files |
| - | - |
| Routes, guards, providers, startup errors | `src/App.tsx`, `src/main.tsx` |
| Browser config and auth persistence | `src/integrations/supabase/client.ts`, `src/lib/auth.tsx`, `src/lib/mfa.ts` |
| Shared navigation and desktop actions | `src/components/AppLayout.tsx`, `src/components/WorkspaceSwitcher.tsx` |
| Chat and history persistence | `src/pages/Index.tsx`, `src/lib/orbit-chat.ts`, `src/lib/library.ts`, `src/pages/HistoryPage.tsx`, `supabase/functions/orbit-chat/index.ts` |
| Onboarding, settings, privacy, account deletion | `src/pages/OnboardingPage.tsx`, `src/pages/SettingsPage.tsx`, `src/pages/PrivacySettingsPage.tsx`, `supabase/functions/delete-account/index.ts` |
| Workspace, missions, storage | `src/lib/workspace.tsx`, `src/pages/MissionControlPage.tsx`, `supabase/functions/mission-control/index.ts` |
| Payments and providers | `supabase/functions/create-payment-session/index.ts`, `create-billing-portal/index.ts`, `stripe-webhook/index.ts`, `supabase/functions/_shared/billing.ts` |
| Schema and security | `supabase/migrations/`, `supabase/config.toml`, `supabase/tests/database/` |
| Browser, desktop, mobile builds | `package.json`, `vite.config.ts`, `wrangler.jsonc`, `capacitor.config.ts`, `electron/` |

## 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](/engineering/architecture).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.