Integration architecture

Updated 13 September 2026. The authoritative hostname and status map is in the Web Platform overview; every fixed HTTP interface is in the Runtime and API Reference.

EXEPERT uses independent public applications around one controlled identity and data plane. The website, AI Lab, and Learning Lab can each render their public shell if an optional dynamic integration is unavailable.

Canonical origin boundary

• exepert.com redirects to www.exepert.com; only the www hostname serves website content.
• app.exepert.com owns the AI Lab, API, active identity authority, CMS, and /docs.
• learn.exepert.com owns learning. www.learn.exepert.com preserves path and query in a 308 redirect to the canonical learning origin.
• auth.exepert.com is a live gateway hostname, but its cutover gate blocks session and mutation traffic. A healthy probe does not make it authoritative.

Cookies, OAuth issuer/audience values, callback URLs, trusted origins, and principal-token resources must move together during any future identity cutover. Do not point one client at the candidate independently.

AI Lab boot and offline boundary

src/main.ts installs diagnostics, initializes the classic WebGL renderer, loads assets, creates the WASM brain, mounts scene/UI controls, and starts the frame loop before optional hosted integrations. Supabase or Typesense absence must not prevent simulation start.

When hosted services are configured, Better Auth state gates observability. When they are unavailable, src/auth/gate.ts preserves the existing offline simulation path. Optional imports catch load failure and degrade without turning it into a boot failure.

Browser and WASM ownership

src/brain.ts wraps pointer/count pairs from rust/brain_sim in typed arrays used by Three.js buffer attributes. Rust World owns mutable state. The unpaused frame path calls World.step_cpu(dt) and renders synchronously with the classic WebGLRenderer.

WASM memory growth replaces the backing buffer. The bridge must detect a new wasm.memory.buffer and rebind views. This is a correctness contract.

Active identity and Supabase data

Better Auth stores identity and sessions in the private authn schema. The same-origin web clients use secure HttpOnly cookies; the native client uses the OAuth Provider flow with PKCE. Session-secret overlap accepts the retained prior secret and re-signs a valid session with the current version.

POST /api/supabase/token authenticates the Better Auth request, resolves the stable EXEPERT principal, and mints a five-minute ES256 token. Supabase validates that token and presents the principal as auth.uid(). Browser-owned data then uses the Data API/Realtime paths protected by cumulative grants and RLS.

Privileged and secret-bearing work moves through the Node CMS or Supabase Edge Functions. Every function must be inspected for its explicit bearer and ownership rules; repository verify_jwt settings alone are not proof of safe authorization.

Website and CMS publication

The landing application displays sign-in and admin UI but does not implement a second account system. Its auth and CMS paths rewrite to app.exepert.com.

CMS drafts, memberships, revisions, source assets, and jobs live in app_private and are available only to the backend role. Publishing writes read-only public projections and immutable public media. A signed internal request revalidates affected Next.js routes. Public website requests read only the projection through the publishable Supabase key.

This separation lets a draft remain private, supports deterministic rollback to an earlier application deployment, and keeps service-role credentials out of the landing bundle.

Brain Learning integration

The Learning Lab ships its lessons, manifests, viewer, MRI examples, and browser worker as a Cloudflare Pages artifact. Guest progress is local and partitioned under a guest key. Account progress code calls the identity bridge and owner scoped Supabase RPC only when IDENTITY_ENABLED=true; production keeps it false.

The optional tutor additionally requires an authenticated member, Turnstile, the private quota RPC, a Cloudflare AI binding, and TUTOR_ENABLED=true. Failure, quota exhaustion, unsupported questions, or invalid citations return authored lesson guidance. No paid provider is chained behind Workers AI.

The Open Brain Kit and static demo are public Hugging Face releases. Medical examples, geometry, licenses, authored parameters, and simulator outputs stay separated in the package. The package does not redistribute restricted data or claim trained human-brain weights.

Main feature flows

Flow	Verified path
Observability	Better Auth session -> short-lived Supabase token -> owner-scoped DAL -> projects/sessions/traces/spans/annotations; Realtime span events feed the live-brain bridge.
Research chat	Bridge bearer token -> model discovery/run-chat Edge Functions -> configured router using server secrets -> persisted session/trace/span -> feedback/affect annotations.
Prompt playground	Browser user token and owner-scoped prompt/version data -> run-playground -> provider stream via Edge secrets -> SSE tokens/done/error.
OTLP ingestion	Trusted exporter shared ingest key -> otlp-receiver -> service-role trace/span writes; this is not a normal browser write path.
Evaluation	Authorized shared ingest key -> run-eval -> deterministic or configured provider evaluator -> span annotations.
Arcade research	Explicit local consent and authenticated owner -> validated retry queue -> ingest Edge Function -> private tables through service-role-only SQL; local opt-out and remote deletion stay distinct.
Search	Optional browser Typesense client -> search-only key and projection; missing configuration produces an unavailable state.
Blog publication	Landing admin UI -> centralized CMS -> private records/media processing -> public projection -> signed Next.js revalidation.
Brain learning	Static lessons/assets -> browser viewer/worker/local progress -> pinned Hugging Face download; identity/tutor requests remain gated.

Build and release integration

At development time, the root app, docs, landing, learning app, and gateway use their own commands and dependency roots. In production:

• scripts/vercel-build.sh builds the root WASM/Vite app and Docusaurus, then scripts/copy-docs-build.mjs merges docs into the exepert dist artifact.
• Vercel builds apps/landing independently with Bun. Its ignored-build check skips releases when that subtree did not change.
• brain-learning-deploy.yml deploys the canonical app and www redirect from one exact reviewed main commit.
• Identity candidate and promotion workflows separately bundle the shared runtime, deploy the Supabase function, and publish the Cloudflare gateway only when their gates pass.

Failure and trust boundaries

• Hosted-service absence is an optional-feature state, not a core visualization or lesson failure.
• External chat, trace, search, Journal, lesson question, and error values are untrusted. Render with safe DOM construction or the established sanitizers.
• Browser route interception does not isolate Playwright's Node global setup from hosted Supabase credentials.
• Repository configuration does not prove deployed state. Validate the exact host/project before a release or mutation.
• Never copy secret values across browser, Edge, docs, BMAD output, tests, or diagnostic boundaries.