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

# Web Architecture

> How Overlay Web routes, services, schemas, and feature modules fit together.

Overlay is a Next.js app backed by Convex, server-mediated provider adapters, and runtime-configurable auth, billing, storage, model, tool, and telemetry providers.

## Source Of Truth

* `src/app/api/v1/**` is the public backend surface for web, mobile, desktop, and extension clients.
* `src/server/app-api/v1/**` holds the route orchestration behind those Next route wrappers.
* `src/server/**` holds server-only auth, billing, storage, AI, tools, route services, and provider adapters.
* `src/shared/**` holds isomorphic contracts and client-safe helpers.
* `src/features/**` holds web feature containers and feature-local helpers.
* `convex/**` owns durable app state, domain mutations, scheduled work, and Stripe webhook handling.
* `packages/overlay-app-core/**` holds shared cross-surface contracts and UI settings types.
* `packages/overlay-api-client/**` holds typed transport wrappers for `/api/v1/**`.

Clients should not call model providers, billing providers, identity admin APIs, object storage, or Convex directly unless a route explicitly exists for that surface.

## Auth

* Browser auth uses the signed httpOnly `overlay_session` cookie.
* Native/mobile/desktop auth uses supported bearer access tokens against the same `/api/v1/*` backend.
* Internal server-to-server calls use short-lived service auth from `src/server/auth/service-auth.ts`.
* Shared route authentication flows through the API boundary helpers in `src/server/auth/app-api-auth.ts`.

Every sensitive `/api/v1/*` route should reject requests that lack a valid browser session, mobile bearer token, or service auth token.

## App Bootstrap

`GET /api/v1/bootstrap` is the canonical signed-in startup call. It returns user info, entitlements, UI settings, model catalogs, feature flags, navigation destinations, and defaults.

New clients should start from this route and reuse existing API contracts before adding client-specific endpoints.

## Billing

Stripe is the hosted billing provider for subscriptions, top-ups, auto top-up preferences, customer portal sessions, and webhook events. Private deployments can disable billing with runtime config. Convex is the durable entitlement/usage source of truth after webhook processing.

Important code:

* `src/shared/billing/billing-pricing.ts`
* `src/server/billing/billing-runtime.ts`
* `src/server/billing/stripe-billing.ts`
* `src/server/billing/BillingCustomerService.ts`
* `src/server/billing/BillingCheckoutService.ts`
* `src/server/billing/providers/stripe-billing-provider.ts`
* `convex/billing/subscriptions.ts`
* `convex/platform/usage.ts`
* `convex/billing/stripe.ts`
* `convex/billing/stripeSync.ts`

## Storage

Uploaded files and generated assets are stored through server-mediated flows. R2 and S3-compatible object access must remain private and owner-scoped; users should only receive short-lived, validated access.

## Convex

Development commonly uses a separate dev deployment from production. After editing `convex/`, push both deployments:

```bash theme={null}
npm run convex:push:all
```

Do not pass `.env.local` to production Convex deploy commands; that can point deploys at the dev slug.