Architecture

System Architecture

Technology stack

Layer	Technology
Framework	TanStack Start v1 (React 19, Vite 7)
Routing	File-based routes under `src/routes/` (auto-generated tree)
Server logic	`createServerFn` from `@tanstack/react-start`
Edge runtime	Cloudflare Workers (workerd, nodejs_compat)
Backend	Lovable Cloud (Supabase: Postgres, Auth, Storage, Edge Functions)
UI primitives	shadcn/ui on Tailwind CSS v4 (tokens in `src/styles.css`)
Client state	TanStack Query in router context
Documentation	Markdown chapters + react-pdf (`/docs`)

Application layers

 ┌──────────────────────────────────────────────────────────┐
 │ Presentation                                             │
 │  • src/routes/*  • src/components/*  • shadcn/ui         │
 ├──────────────────────────────────────────────────────────┤
 │ Application                                              │
 │  • createServerFn (queries, mutations, business rules)   │
 │  • TanStack Query (caching, suspense, revalidation)      │
 │  • Hooks: useTenant, useAccessAuditLog, useInactivityTimer│
 ├──────────────────────────────────────────────────────────┤
 │ Domain / Security                                        │
 │  • src/lib/rbac/roles.ts        (role model)             │
 │  • src/lib/security/*           (LLM guard, encryption)  │
 │  • src/lib/resilience/*         (circuit breaker)        │
 ├──────────────────────────────────────────────────────────┤
 │ Platform                                                 │
 │  • Supabase Postgres (RLS-enforced)                      │
 │  • Supabase Auth (TOTP MFA, AAL2)                        │
 │  • Edge Functions (login-rate-limit, …)                  │
 │  • Cloudflare Workers (SSR, server fn dispatch)          │
 └──────────────────────────────────────────────────────────┘

Runtime topology

                       ┌──────────────────────────┐
                       │      Browser (SPA)       │
                       │  React 19 · TanStack QC  │
                       └──────────┬───────┬───────┘
                                  │       │
            supabase-js (auth/    │       │  fetch /_serverFn/*
            session/realtime)     │       │
                                  │       ▼
                       ┌──────────┴──────────────┐
                       │ Cloudflare Worker (SSR) │
                       │  • TanStack Start route │
                       │  • createServerFn       │
                       │  • attachSupabaseAuth   │
                       └──────────┬──────────────┘
                                  │  PostgREST + RLS as user
                                  ▼
                       ┌─────────────────────────┐
                       │ Supabase Postgres       │
                       │  • RLS on every table   │
                       │  • SECURITY DEFINER fns │
                       └─────────────────────────┘
                                  ▲
                                  │ service-role only
                                  │
                       ┌──────────┴──────────────┐
                       │ Supabase Edge Functions │
                       │  • login-rate-limit     │
                       └─────────────────────────┘

Component map

Concern	Location
Routes	`src/routes/` (file-based; `_authenticated/` for gated subtrees)
App shell, sidebar, role switcher	`src/components/app/`
Access governance UI	`src/components/access-governance-v2/`
Security guards	`src/components/security/` (`InactivityGuard`)
Documentation UI	`src/components/docs/`
Server fn definitions	`src/lib/*/.functions.ts`
Server-only helpers	`src/lib/*/.server.ts` (blocked from client by import guard)
Edge functions	`supabase/functions/*`
SQL migrations	`supabase/migrations/*`

Authenticated request data flow

1. User submits form in /app/* page
2. Component calls a serverFn via useServerFn()
3. attachSupabaseAuth (global functionMiddleware) reads
   supabase.auth.getSession() and adds Authorization: Bearer <jwt>
4. Worker receives RPC, requireSupabaseAuth verifies JWT,
   creates a per-request Supabase client scoped to that user
5. Server fn runs query — Postgres RLS evaluates auth.uid()
6. Append-only audit entry written to access_audit_log
7. Response returned; TanStack Query caches and re-renders

Infrastructure overview

Element	Provider / runtime
Web tier	Cloudflare Workers, regionally distributed
App database	Supabase Postgres (managed)
Object storage	Supabase Storage (when used)
Edge functions	Supabase Edge Runtime (Deno)
DNS / TLS	Managed by Lovable / Cloudflare
Secrets	Lovable Cloud secret store (`SUPABASE_SERVICE_ROLE_KEY`, webhook secrets)

Notes on the documentation runtime

The /docs route is part of the same TanStack Start app — it is not a separate site. Chapters are bundled at build time via import.meta.glob, so the manual ships with the application and is always in sync with the deployed version. PDF export runs in the browser via @react-pdf/renderer.