Platform Architecture and Data Flow

The Go backend follows a layered architecture: handlers (HTTP), services (business logic), and repositories (data access). A single API binary serves all routes.

The application boots in cmd/api/main.go with a deterministic initialization sequence: load config from embedded .env and environment overrides, connect to PostgreSQL with connection pooling, initialize Auth0 JWT validation with JWKS caching, create S3-compatible storage (DigitalOcean Spaces in production, MinIO locally), set up LiveKit and LLM clients, then wire all services and handlers into the Gin router.

The middleware pipeline runs in order: structured logging (zerolog), panic recovery, error mapping (commonerrors to HTTP status codes), and CORS. Route-specific middleware handles JWT validation, M2M secret verification, API key checks, and optional JWT extraction for public endpoints.

PostgreSQL 16 with 15 migrations as of this writing. All tables use UUID primary keys, soft-delete timestamps, and automatic created_at/updated_at triggers.

Indexes enforce soft-delete-aware uniqueness on users.auth0_sub, users.email, and pages.slug. Foreign key cascades ensure child records (themes, configs, documents, threads) are deleted when a page is removed.

React 19 SPA with context-based state management. Auth0 handles authentication; all API calls inject the Bearer token via a shared useApiClient hook.

The provider stack wraps the entire app: BrowserRouter > Auth0ProviderWithNavigate > ToastProvider > UserProvider > OnboardingProvider. Routes are:

State is managed through three React contexts:

• UserContext fetches the authenticated user from GET /v1/me and provides user, loading, error, and refetch.
• DashboardContext loads pages, social links, documents, and agent config. Polls agent config every 3 seconds when generation_status is pending or generating.
• OnboardingContext accumulates multi-step form data and provides a submit() method that sends everything to the backend in a single multipart request.

Real-time voice conversations use LiveKit for WebRTC transport, with a Python agent bridging speech-to-text, the backend chat API, and text-to-speech.

Text chat streams responses via Server-Sent Events. The frontend's useAgentChat hook manages message state and thread continuity.

After onboarding completes, the backend fires an async goroutine that generates personalized agent instructions using an LLM with structured output. This runs in the background while the user is redirected to the dashboard.

The generation lifecycle uses the generation_status field on agent_configs:

The generator uses ByteDance's Eino framework with structured output (JSON schema enforced by the LLM). The meta-prompt mandates six bracketed sections in a fixed order — [IDENTITY], [VOICE], [COVERAGE], [BOUNDARIES], [ENGAGEMENT], [CUSTOM] — and explicitly tells the LLM not to include safety / grounding / refusal rules. Those are appended at runtime by the operating contract layer so they never silently drift between regenerations. Generated instructions are versioned and appended to a JSONB array, allowing the system to track multiple generations over time.

For deep-dive coverage of all three prompt layers, the structured sections, and the regenerate-instructions CLI for triggering regenerations from the command line, see the Agent Prompt Architecture doc.

The API contract is defined in multi-file YAML specs under backend/openapi/v1/, organized by module: auth/, m2m/, pages/, livekit/, public/, onboarding/, and common/ (shared error schemas).

Running bt generate openapi -y from backend/ produces Go types in generated/openapi/v1/views/. These types are the contract between handlers and the outside world. Handlers accept OpenAPI request types, call services with domain types, and convert results back to OpenAPI response types.

The frontend uses Storybook 10 for component development and visual regression testing. Auth0 is mocked at the Storybook level so all components render without a real authentication session.

• Stories live alongside components in frontend/src/stories/.
• Auth0 mock (.storybook/mocks/auth0.ts) provides a fake authenticated user, getAccessTokenSilently stub, and passthrough withAuthenticationRequired.
• Run locally with make run-storybook (port 6006).
• Publish to Chromatic with make storybook-publish or via the GitHub Actions CI pipeline on push to main.
• Accessibility testing via axe-core: cd frontend && npm run test:a11y.

Configuration is split across three .env files, one per workspace. The backend embeds its .env at compile time as a fallback; actual environment variables take precedence.

Every authenticated request flows through a three-step lookup chain that's self-healing: cached user_id claim → Auth0 sub fallback → lazy create. The Auth0 Post-Login Action is an optimization (warms the cache), not a hard dependency.

Token shape

Auth0 issues a JWT with these claims:

• sub — Auth0 user identifier (e.g. google-oauth2|123456789). Always present.
• email, email_verified, name, picture — OIDC profile claims. Always present for Google logins.
• https://ambasdr.com/user_id — Custom claim set by the Post-Login Action after it provisions the user. Present on most logins, absent if the Action's fetch failed.
• https://ambasdr.com/role — Custom claim. Currently always "user".

The JWT middleware (internal/auth) decodes the token, validates against the Auth0 JWKS, and stores the full identity.Identity struct in the gin request context. Every authenticated handler then calls userHandler.resolveUser, which delegates to UserService.EnsureFromIdentity.

UserService.EnsureFromIdentity — the lookup chain

Returns 401 Unauthenticated only when the Identity itself is missing (no JWT, or a JWT with no sub claim). Real DB errors bubble up as 500. Everything else — missing custom claim, stale UUID, never-seen sub — is recovered transparently. The integration tests in backend/tests/integration/user_handler_test.go cover all four paths and the soft-delete refusal case.

Auth0 Post-Login Action

The "Provision Ambasdr User" Action runs on every login. On the fast path it reads the cached ambasdr_user_id from app_metadata and sets the custom claim from cache — no backend call. On the slow path (cache empty) it POSTs to /internal/users/provision with the user's identity, then caches the returned UUID in app_metadata. The endpoint is M2M-authenticated via AUTH0_M2M_SECRET and delegates to the same EnsureFromIdentity — so the Action and the lazy fallback always return identical user records.

If the Action's fetch fails (backend down, network blip, secret mismatch), the Action logs and proceeds with login. The next authenticated request lazy-creates the user on its own. To force a re-provision for testing: make dev-reset-user EMAIL=<email> clears app_metadata.

CORS

Per-environment defaults plus an env-var overlay. cmd/api/main.go calls resolveAllowedOrigins(env, csv):

• Default: ["http://localhost:3000", "http://localhost:3003"] (dev).
• ENVIRONMENT=production: ["https://ambasdr.com"].
• ALLOWED_ORIGINS set: comma-separated list overrides both defaults. Used in staging to add the ngrok URL without recompiling.

Unit-tested in cmd/api/main_test.go — tag unit.