FourIA Cloud Architecture
On this page
Last updated: Jul 2026 Platform: Cloudflare Workers for Platforms (WFP) Database: Supabase PostgreSQL — PostgREST from the Dispatch Worker, Ecto from the Dashboard (docker-compose for local dev)
Overview
FourIA uses Cloudflare Workers for Platforms (WFP) to provision isolated, per-customer gateways. Each customer receives their own User Worker (deployed as tenant-{slug} in the dispatch namespace) which manages an OpenClaw gateway inside a Sandbox container, with independent bindings (R2, Durable Objects, Analytics Engine).
All tenant traffic enters through a single Dispatch Worker bound to the wildcard domain *.fouria.io. The Dispatch Worker extracts the tenant slug from the subdomain, resolves it against the shared Supabase PostgreSQL database (with a KV cache layer), resolves the user’s role, and dispatches to the appropriate User Worker with role/billing context in headers. No subdomain routing is used in the URL path — each tenant gets its own subdomain.
The FourIA Dashboard runs as a standalone Phoenix app inside a Cloudflare Container at dash.fouria.io (on the fouria.io zone, with a bypass worker route — no worker assigned), backed by the shared Supabase PostgreSQL database. A separate dev instance runs at dev-dash.fouria.io. The Dashboard is a pure control panel — it has no direct dependency on fouria or the Dispatch Worker. Platform data (clients, partners, users, instances, billing) is managed exclusively through the Dashboard.
Architecture principle: lerma and fouria are independent services that share only a data store. No direct HTTP dependencies exist between them.
DNS zones: Tenant traffic is served via *.fouria.io (fouria.io zone). The Dashboard is served via dash.fouria.io and dev-dash.fouria.io on the fouria.io zone through bypass worker routes — these are not handled by *.fouria.io.
TENANT ROUTING — fouria.io zone
────────────────────────────────
*.fouria.io
│
├─ {tenant}.fouria.io ──── (tenant traffic)
│ │
│ ├─ 1. Dispatch Worker (workers/fouria-dispatch/)
│ │ │ slug: extract tenant slug from hostname
│ │ │ cache: check KV (TENANT_INDEX, 60s TTL)
│ │ │ db: fallback query to Supabase (PostgREST)
│ │ │ auth: Cloudflare Access JWT (aud resolved per tenant)
│ │ │ user: resolve user role from client_users
│ │ │ headers: forward X-FourIA-Role, X-FourIA-Metadata
│ │ │ limits: plan-level CPU & subrequest limits
│ │ │
│ │ └─ DISPATCHER.get("tenant-{slug}")
│ │ └─ User Worker: tenant-{slug}
│ │ ├─ Sandbox container (OpenClaw gateway)
│ │ ├─ BACKUP_BUCKET (R2: per-tenant)
│ │ ├─ ANALYTICS (AE: per-tenant metrics)
│ │ └─ Secrets (API keys, gateway token)
│ │
│ └─ ... (unlimited tenants in fouria-tenants namespace)
DASHBOARD — fouria.io zone (bypass worker routes)
────────────────────────────────
dash.fouria.io ──── (production, internal management)
│
└─ FourIA Dashboard (apps/lerma/)
│ runtime: Phoenix app in Cloudflare Container
│ backend: Supabase PostgreSQL (via Ecto/postgrex)
│ db: source of truth for clients, instances, billing
│ api: internal REST API (/api/clients, /api/instances, etc.)
│ ops: CF API client for WFP provisioning
│ domains: dash.fouria.io, dev-dash.fouria.io
dev-dash.fouria.io ──── (development/staging dashboard)
── Shared Platform Services ──
├─ AI Gateway (default; per-tenant gateways are fouria-<slug>)
│ → Unified AI provider routing (shared across tenants)
│ → Native PII filtering — replaces the deprecated Outbound Worker (fouria-outbound)
│
└─ Supabase PostgreSQL (shared, managed)
→ Source of truth: clients, partners, users, instances, plans, billing
→ Accessed via Ecto (Dashboard) and PostgREST (Dispatch Worker)Component Connectivity
End-to-end component map — the control plane (lerma) and the data plane (Dispatch → Tenant → Sandbox) share the same Supabase PostgreSQL source of truth and have no direct HTTP dependency on each other:
┌──────────────────────────────────────────────────────────┐
CONTROL PLANE Supabase (PostgreSQL) DATA PLANE
clients · credit_pools · client_users ·
instances · billing · source of truth
└─────────▲─────────────────────────────────────┬──────────┘
│ │
Ecto / postgrex │ PostgREST (SUPABASE_URL │
(Dashboard) │ + SERVICE_ROLE_KEY) │
│ │
┌───────────────────────┐ ┌────────────────────────────────┐
│ FourIA Dashboard │ │ Dispatch Worker │
│ (apps/lerma) │ │ workers/fouria-dispatch │
│ dash.fouria.io │ │ *.fouria.io · KV · Access JWT │
│ Phoenix + LiveView │ │ role resolution │
│ control plane │ └───────────────┼────────────────┘
└───────────┼───────────┘ │ DISPATCHER.get()
│ CF API (R2 buckets, │ "tenant-{slug}"
│ secrets, dispatch ns) │ + X-FourIA-Role
▼ │ + X-FourIA-Metadata
Cloudflare APIs ▼
(provisioning) ┌────────────────────────────────┐
│ Tenant Worker │
│ (apps/fouria) │
└───────────────┼────────────────┘
│ sandbox container
▼
┌────────────────────────────────┐
│ Sandbox Container │
│ · OpenClaw Gateway │
│ · moltlazy patch │
│ · cf-unified-billing │
└───────────────┼────────────────┘
│ provider calls
▼
┌────────────────────────────────┐
│ Cloudflare AI Gateway │
│ (moltworker) · PII │
└───────────────┼────────────────┘
▼
Upstream LLMs
Shared platform services: Cloudflare R2 (per-tenant backups + release bundles), Analytics Engine (fourai_cost_metrics), and the Cloudflare AI Gateway (default for shared/E2E workers; Lerma provisions a per-tenant fouria-<slug> gateway).
Reserved hosts: The Dispatch Worker at *.fouria.io reserves the following hostnames (they are handled specially and are not valid tenant slugs):
| Reserved hostname | Purpose | Zone |
|---|---|---|
dash.fouria.io | FourIA Dashboard (production) | fouria.io (bypass route) |
dev-dash.fouria.io | FourIA Dashboard (development) | fouria.io (bypass route) |
hooks.fouria.io | Telegram webhook ingress (prod) — excluded from the wildcard Access app | fouria.io |
hooks.dev.fouria.io | Telegram webhook ingress (staging) — excluded from the wildcard Access app | dev.fouria.io |
The Telegram webhook ingress (hooks.*) is a public, Access-bypassed host on which Telegram POSTs updates to /v1/<slug>/<account>. The Dispatch Worker resolves the tenant, applies the freeze policy (tenantRouteGate with isRoot: false, so a frozen/stopped instance is never woken), and forwards to the tenant Worker’s POST /telegram-webhook/:account route — which validates the per-account secret and either forwards to OpenClaw (hot) or buffers on a Cloudflare Queue and wakes the container (cold). See apps/fouria/docs/WORKER-DEVELOPMENT.md §“Telegram Webhook Ingress”.
Project Structure
workers/
├── fouria-dispatch/ # Dispatch Worker
│ ├── src/index.ts # Wildcard dispatch, Supabase lookup, KV cache, cron fan-out
│ ├── src/auth.ts # Cloudflare Access JWT verification
│ ├── src/supabase.ts # PostgREST tenant + user-role resolution
│ ├── wrangler.jsonc # DISPATCHER, TENANT_INDEX (KV), SUPABASE_* secrets
│ ├── package.json
│ └── tsconfig.json
apps/
├── lerma/ # FourIA Dashboard (Elixir/Phoenix, internal only)
│ ├── lib/lerma/
│ │ ├── repo.ex # Ecto repo → Supabase PostgreSQL
│ │ ├── cloudflare/ # CF Workers API client (provisioning)
│ │ ├── provisioning/ # TenantProvisioner orchestrator
│ │ ├── clients/ # Client/user CRUD
│ │ ├── instances/ # Instance lifecycle
│ │ ├── billing/ # Billing context
│ │ └── dashboard/ # Dashboard accounts context
│ ├── lib/lerma_web/
│ │ ├── router.ex # Routes (browser + API)
│ │ ├── plugs/cf_access_auth.ex # Cloudflare Access auth plug
│ │ └── live/ # LiveView pages
│ ├── Dockerfile # Container image (Phoenix app)
│ └── priv/repo/migrations/ # Supabase schema (Ecto migrations)
│
└── fouria/ # User Worker template
├── src/index.ts # OpenClaw gateway proxy, auth, metrics
├── src/auth/ # JWT verification, RBAC
├── src/gateway/ # Sandbox container management
├── src/routes/ # API routes, admin UI, OTel forwarding
├── wrangler.jsonc # 3 environments: local, staging, production
├── Dockerfile # OpenClaw container image
└── ...
Key Components
1. Dispatch Worker (workers/fouria-dispatch/)
The entry point for all platform tenant traffic at *.fouria.io. Extracts the tenant slug from the subdomain, resolves it via KV cache (60s TTL) with Supabase (PostgREST) fallback, validates Cloudflare Access JWT per-tenant, and dispatches to the correct User Worker.
Note: The Dispatch Worker only handles tenant routing on the
*.fouria.iozone. Dashboard traffic atdash.fouria.ioanddev-dash.fouria.iois served on the fouria.io zone via bypass worker routes — the Dispatch Worker does not intercept these hostnames.
Request Flow:
- Request arrives at
{tenant}.fouria.io - Dispatch Worker extracts tenant slug from hostname (e.g.,
tenant-arua.fouria.io→tenant-arua) - Checks KV cache (
TENANT_INDEX) keyed byslug:{tenant}(60s TTL) - On cache miss, queries Supabase via PostgREST (service-role key):
clients—id,slug,billing_plan,status- plus
credit_pools(credits used/max), validatedclient_users(seat count), andinstances(instance id/status)
- Requires a valid Cloudflare Access JWT; production validates that the token’s
audresolves to the requesting tenant - Dispatches to User Worker (
tenant-{slug}) viaDISPATCHER.get()with plan-level CPU/subrequest limits - Forwards
X-FourIA-RoleandX-FourIA-Metadataheaders to the User Worker
Responsibilities:
- Extract tenant slug from wildcard subdomain hostname
- KV cache (TENANT_INDEX, 60s TTL) for tenant routing — warm reads, Supabase fallback
- Direct Supabase queries (PostgREST via
SUPABASE_URL+ service-role key) — no dashboard HTTP API dependency - Per-tenant Cloudflare Access JWT verification (token
audresolved to the tenant) - Apply per-plan CPU and subrequest limits
- Fan-out a periodic
backupcontrol action to all non-frozen tenants (cron: every 15 min production / hourly staging); each tenant skips an instance that is not currently running (non-wakingisRuntimeActive()check), so idle containers are never woken - Invalidate tenant cache via internal endpoint (
/_invalidate/:slug)
Bindings:
| Name | Type | Purpose |
|---|---|---|
DISPATCHER | dispatch_namespace | fouria-tenants namespace |
SUPABASE_URL | secret_text | Supabase project URL (PostgREST endpoint) |
SUPABASE_SERVICE_ROLE_KEY | secret_text | Service-role key (bypasses RLS for reads) |
TENANT_INDEX | kv_namespace | Tenant slug → entry cache (60s TTL) |
PLATFORM_DOMAIN | plain_text | fouria.io |
Staging uses
STAGING_SUPABASE_URL/STAGING_SUPABASE_SERVICE_ROLE_KEYwhen present, falling back to the production credentials.
Auth model: Per-instance. Every tenant environment hostname has its own Cloudflare Access application and group ({slug}.fouria.io for production, {slug}-dev.fouria.io for dev). In production the token’s aud must resolve to the requested hostname — Paso4 ROOT operators are exempt (they may hold the platform wildcard *.fouria.io AUD or the shared Paso4 Root Users group) — and Dispatch resolves a client role only when the user is validated and linked to that exact instances.id. Staging continues to require the Paso4 platform audience (ROOT).
Routing gate: After authentication, Dispatch checks the resolved tenant’s operational state (tenantRouteGate). The production environment is gated on clients.status (active/production/error); the dev environment is gated on the instance status instead, so a running (or health-error) dev instance behind a still-draft client is routable. A frozen/stopped instance returns 503 for non-ROOT callers, but a ROOT operator is exempt so they can always revive it. Health state is never a routing gate — tenant containers are loaded lazily, so a probe miss is not an outage.
Invitation flow: Lerma stores new client users as invited with only a SHA-256 token hash and a seven-day expiry. The emailed link lets the recipient accept or reject the invitation. Invitation emails are delivered by a supervised background task (Lerma.Invitations) after the user row is committed, so a slow or failing SMTP relay never holds a database connection or blocks the dashboard; the delivery outcome is broadcast over PubSub and surfaced as a toast plus a per-user badge. Acceptance records a structured Cloudflare Access identity reference, changes the user to validated, and syncs their email only into the groups for accepted instance assignments. invited and rejected users are excluded from both Access groups and Dispatch role resolution. Existing Access applications are reconciled to a group-only allow policy during provisioning and user synchronization; everyone is never retained. Because invitees are not platform operators, the /invitations/* path is deliberately kept outside Cloudflare Access: the dashboard Access application is complemented by a path-scoped bypass application (apps/lerma/iac/tf/access.tf), plus a companion bypass for the page’s static assets (/assets/*, /images/*, /favicon.ico) so the stylesheet, JS, logo, and favicon load without an Access login, and the page is served by a plain controller rather than a LiveView so accepting or rejecting never depends on the Access-protected /live socket.
2. User Workers (apps/fouria/)
Each customer gets their own User Worker deployed to the fouria-tenants dispatch namespace. These are instantiated from the same codebase but with per-customer bindings.
User Workers receive tenant context and user identity from the Dispatch Worker via HTTP headers (X-FourIA-Role, X-FourIA-Metadata). They never access the platform database directly — all user/tenant resolution is handled by the Dispatch Worker before the request reaches the User Worker.
Per-Customer Bindings (provisioned by FourIA Dashboard):
| Binding | Type | Example |
|---|---|---|
Sandbox | durable_object_namespace | Per-tenant Sandbox class |
BACKUP_BUCKET | r2_bucket | fouria-backup-arua |
ANALYTICS | analytics_engine | fouria_metrics_arua |
BROWSER | browser | Shared remote browser |
MOLTBOT_GATEWAY_TOKEN | secret_text | Auto-generated per tenant |
OTEL_SHARED_SECRET | secret_text | Auto-generated per tenant (sandbox OTLP bridge bearer) |
CLOUDFLARE_AI_GATEWAY_API_KEY | secret_text | Platform AI credential from Lerma |
CLOUDFLARE_API_TOKEN | secret_text | REST transport alias of the platform AI credential |
CF_AI_GATEWAY_GATEWAY_ID | plain_text | Per-tenant fouria-<slug> (Lerma); "default" is the Worker-config fallback |
CF_ACCESS_AUD | plain_text | Per-tenant AUD tag |
All platform data access goes through the Dispatch Worker (Supabase PostgREST) and Dashboard (Supabase + Ecto). User Workers never access the platform database directly — they receive billing context via X-FourIA-Metadata and role via X-FourIA-Role, both set by the Dispatch Worker.
3. FourIA Dashboard (apps/lerma/)
Internal management application for Paso4 managers only. Runs as a standalone Phoenix app inside a Cloudflare Container (Durable Object PHOENIX_CONTAINER) at dash.fouria.io (on the fouria.io zone, with a bypass worker route). A separate dev instance is served at dev-dash.fouria.io.
The Dashboard is a pure control panel — it has no direct dependency on fouria or the Dispatch Worker. It manages platform data (clients, partners, users, instances, billing) through its Supabase backend and interacts with Cloudflare APIs for provisioning.
Database architecture:
| Environment | Backend | Database |
|---|---|---|
| dev/test | Ecto (PostgreSQL) | DATABASE_URL (Docker compose) |
| production | Ecto (PostgreSQL) | DATABASE_URL (managed Supabase) |
In production, the Dashboard connects to Supabase PostgreSQL via postgrex using the DATABASE_URL environment variable (direct PostgreSQL wire protocol).
Communication model: The Dashboard communicates with Supabase PostgreSQL via Ecto — no public HTTP API is needed for platform data. Cloudflare API calls (WFP provisioning, R2 management, secrets) use a CF API client with admin-level credentials.
Client documentation (read-only): the client profile embeds a source tree and live preview for the client’s proposal folder (global leads bucket, <slug>/) and its tenant docs (customers/<slug>/docs/ in each instance’s BACKUP_BUCKET). Lerma lists and reads those objects directly through the Cloudflare R2 REST API with its own API token; it never calls the tenant Worker and never handles R2 S3 credentials. Reads are lazy: opening the client profile only renders a Load documentation placeholder, and the first R2 request happens when the operator clicks it (the page is never blocked by documentation loading). Binary assets stream through the Access-protected /dashboard/clients/:id/docs/raw/:source route. This does not introduce an HTTP dependency on fouria.
Authorization model: Two role levels control API access:
| Role | Scope | Capabilities |
|---|---|---|
| PASO4 root | Global | Full CRUD on all entities, create Partner roots |
| Partner root | Partner-scoped | CRUD limited to associated clients and their data |
Users
Management of FourIA user entities (logical users linked to a Cloudflare Zero Trust Access identity and role).
GET /user → List all users (paginated)
GET /user/:user_id → Get single user details
PASO4 root & Partner root (scoped):
POST /user → Create a user entity (linked to Zero Trust Access ID + role)
Partners
A partner entity represents an organization that can own multiple clients, each with one instance of the service.
GET /partner/:partner_id/style → Get partner custom branding (views, logos)
PUT /partner/:partner_id/style → Update partner custom branding
PASO4 root only:
GET /partner → List all partners (paginated)
GET /partner/:id → Get partner details
POST /partner → Create a new partner
PUT /partner/:id → Update partner
DELETE /partner/:id → Delete partner
Clients
Client entities belong to a partner and each has one associated instance. A client can also be internal (no partner association).
PASO4 root & Partner root (scoped):
GET /client → List all clients (paginated, scoped by role)
GET /client/:client_id → Get client details from Supabase
POST /client/new → Create a new client
PUT /client/update → Update client information
PASO4 root only:
GET /client/:client_id/partner → Get associated partner (null if internal client)
Instances
Each client has exactly one instance (User Worker deployed via WFP dispatch namespace).
PASO4 root & Partner root (scoped):
POST /client/instance/create → Create a new instance via WFP binding
(limited to 1 per client)
PUT /client/instance/:instance_id/worker-plan/:plan_type → Manually change instance worker plan
GET /client/instance/:instance_id/health → Instance health status
Health endpoint returns instance observability data via Worker bindings:
| Check | Source | Description |
|---|---|---|
| Gateway status | Sandbox DO / process probe | Whether the OpenClaw gateway process is running (up/down) |
| Container heartbeat | Analytics Engine (container-active) | Most recent heartbeat timestamp |
| OTel health | (to be defined) | Additional health signals exposed via OpenTelemetry integration |
The OTel integration will be extended to surface further instance state metrics (memory pressure, CPU throttle, R2 mount status, WebSocket connectivity). These signals will be defined during OTEL implementation.
Client Users
Manages email-verified invitations and instance-scoped Cloudflare Zero Trust Access assignments. User responses include status, validated_at, cf_access_identity, and instance_ids.
PASO4 root & Partner root (scoped):
GET /api/clients/:client_id/users → List invited, validated, and rejected users
POST /api/clients/:client_id/users → Create an invitation for selected instance_ids (email sent asynchronously)
PUT /api/clients/:client_id/users/:id → Update name or role
DELETE /api/clients/:client_id/users/:id → Remove a user and revoke assigned access
Invite recipient (public — served outside Cloudflare Access):
GET /invitations/:token → Review an invitation
POST /invitations/:token/accept → Accept the invitation
POST /invitations/:token/reject → Reject the invitation
Analytics
Cost and usage analytics drawn from Cloudflare Analytics Engine. See cost-observability.md for the full event schema and example queries.
PASO4 root & Partner root (scoped):
GET /analytics/global → Executive summary dashboard
PASO4 root: segmented by partners
Partner root: filtered to partner's clients only
Analytics Engine dataset: fourai_cost_metrics — written by User Workers via the ANALYTICS binding. The dashboard fetches aggregated queries from this dataset to render cost breakdowns, container uptime, R2 bandwidth, and WebSocket session metrics.
Provisioning Flow (for a new customer):
1. POST /partner → Create Partner (if not internal)
2. PUT /partner/:id/style → Configure partner branding
3. POST /client/new → Create Client (slug, plan, partner_id)
4. POST /client/instance/create → Provision User Worker via WFP:
a. Create R2: "fouria-backup-{slug}" (via CF API)
b. Auto-generate gateway token
c. Deploy User Worker to dispatch namespace (via WFP API)
→ multipart upload: worker bundle + binding metadata
d. Set secrets (via WFP secrets API): MOLTBOT_GATEWAY_TOKEN, CDP_SECRET, R2 keys, etc.
e. Set tags: customer_id:{id}, plan:{plan}, env:production
f. Set CF_ACCESS_AUD: Cloudflare Access audience tag (per-tenant JWT auth)
5. POST /user → Create user entities for Zero Trust Access identities
6. POST /client/:client_id/user/:user_id → Link users to client with roles
7. Invalidate dispatch cache: GET /_invalidate/{slug} on Dispatch Worker
Environments
Environment Matrix
| Name | Domain | Database | Dispatch Namespace | AI Gateway |
|---|---|---|---|---|
| local | localhost | Supabase (docker-compose) | N/A (test pool) | Direct API keys |
| staging | fouria.io | Supabase (managed) | fouria-tenants-staging | Shared (moltworker) |
| production | fouria.io | Supabase (managed) | fouria-tenants | Shared (moltworker) |
Staging vs Production
Staging shares the AI Gateway with production (same gateway ID) but has its own Supabase database and dispatch namespace. This allows feature testing with real provider models without risk of touching production data.
Secret Strategy:
- Instance secrets (
MOLTBOT_GATEWAY_TOKEN, derivedCDP_SECRET,BACKUP_ENCRYPTION_KEY, per-instanceOTEL_SHARED_SECRET, R2 credentials,CF_ACCESS_AUD) are deployed assecret_textbindings by the Lerma provisioner. - Platform credentials (AI Gateway key, platform Access AUD) are shared and copied from Lerma’s environment; a tenant never receives the platform Stripe secret.
- Per-client credentials (
OPENCODE_API_KEY) are minted per client byLerma.Opencodeand bound only to that client’s dev instances. - Dynamic secrets (channel tokens, OAuth) are F4E1-encrypted R2 objects, managed by the end user through the integrations dashboard.
AI Gateway Reuse (Gateway Pool)
Cloudflare limits AI Gateways to 10 (Free) / 20 (Paid) per account. To avoid exhausting this quota with one gateway per tenant environment, lerma manages a reusable AI Gateway pool (DB table ai_gateways, dashboard at /dashboard/ai-gateways, API under /api/ai-gateways).
How selection works
At provisioning time (TenantProvisioner → :ai_gateway step → Lerma.AiGateways.resolve/3):
- Explicit override — an operator-provided
ai_gateway_id/ai_gateway_pool_id(or the binding of an existing error-state instance being re-provisioned) wins. - Least-loaded pooled gateway — the enabled pool entry whose
environmentmatches (or is unrestricted) and that still has capacity (used < max_instances), sorted by fewest bound instances.
Tenants never create their own gateway. If no pool entry has capacity, provisioning fails with no_ai_gateway_capacity.
Shared pool gateways are never deleted by the provisioner — the tenant only stores ai_gateway_id + ai_gateway_pool_id on its instance record and binds its worker to that gateway.
Manual distribution control
Each pool entry has a max_instances ceiling — the maximum number of tenant instances that may bind it. An operator edits max_instances per gateway (dashboard edit form or PUT /api/ai-gateways/:id) to steer where new tenants land based on usage, e.g. route high-usage customers onto a dedicated-capacity gateway and everyone else onto a shared pool.
Tenants can be rebalanced at any time by reassigning an instance to another gateway (POST /api/instances/:id/assign-gateway, or the “Change AI Gateway” action on /dashboard/instances/:id). This re-deploys the worker so its CF_AI_GATEWAY_GATEWAY_ID binding points at the new gateway.
What it creates per tenant
| Resource | Dedicated (legacy) | Pooled (reuse) |
|---|---|---|
| Cloudflare AI Gateway | 1 per environment, fouria-{slug}[-dev] | 0 — reuses an existing pool gateway |
ai_gateways row | 0 | 1 (shared across many tenants) |
Instance ai_gateway_id / ai_gateway_pool_id | ai_gateway_id set | both set |
Routing & DNS
DNS Configuration
# Tenant routing — fouria.io zone
Type: A
Name: *.fouria.io
Target: Dispatch Worker (Cloudflare-managed)
Proxied: Yes
# Dashboard — fouria.io zone (bypass worker routes — no worker assigned)
Type: CNAME (or Worker route)
Name: dash.fouria.io
Target: FourIA Dashboard (Cloudflare-managed)
Proxied: Yes
Type: CNAME (or Worker route)
Name: dev-dash.fouria.io
Target: FourIA Dashboard dev (Cloudflare-managed)
Proxied: YesSubdomain-Based Routing (Dispatch Worker)
The Dispatch Worker is bound to the wildcard *.fouria.io route. The tenant is identified by the subdomain, not by the URL path:
| Subdomain | Purpose | Auth |
|---|---|---|
{tenant}.fouria.io | Tenant traffic → User Worker | Cloudflare Access JWT (aud resolved to tenant) |
dash.fouria.io | Internal management → Dashboard (fouria.io zone, bypass) | Cloudflare Access JWT (PASO4/Partner root) |
dev-dash.fouria.io | Dev dashboard (fouria.io zone, bypass) | Cloudflare Access JWT (dev audience) |
The Dispatch Worker only handles subdomains of *.fouria.io. Dashboard hostnames on fouria.io are bypassed — they are not dispatched by the Dispatch Worker via wildcard matching.
// Dispatch Worker routing pattern (tenant traffic only)
const slug = extractSlug(hostname, PLATFORM_DOMAIN);
// tenant-a.fouria.io → "tenant-a"
// Step: resolveTenant(slug) → DISPATCHER.get(workerName).fetch()Supabase Lookup + KV Cache
Request flow:
Browser → {tenant}.fouria.io
→ Dispatch Worker extracts slug from hostname
→ Check KV cache (TENANT_INDEX, key: slug:{tenant})
├─ HIT (60s TTL) → dispatch with cached worker name + plan limits
└─ MISS → query Supabase via PostgREST (service-role key):
clients: id, slug, billing_plan, status
credit_pools: lifetime_consumed, lifetime_purchased
client_users: seat count for the client
instances: status (frozen/stopped guard)
→ Resolve user role (production, non-platform aud):
client_users: role WHERE client_id = ? AND email = ?
→ Cache result in KV (60s TTL)
→ Forward X-FourIA-Role + X-FourIA-Metadata headers
→ DISPATCHER.get(tenant-{slug}) → User Worker
Data Architecture
Shared Supabase PostgreSQL Database
Both the Dispatch Worker and the Dashboard access the same Supabase PostgreSQL database. The Dashboard owns the schema (Ecto migrations), while the Dispatch Worker reads from it at runtime via the PostgREST API (SUPABASE_URL + service-role key).
Tables used by Dispatch Worker (read-only):
| Table | Purpose |
|---|---|
clients | id, slug, billing_plan, status — tenant identity + plan |
credit_pools | lifetime_consumed, lifetime_purchased — credit usage for dispatch |
client_users | Validated seat count + RBAC role (ADMIN, BASE_USER) |
client_user_instances | User-to-instance access assignment; a dev instance also admits a client-level ADMIN without one |
instances | id, status — scope users and reject frozen/stopped instances |
Tables used by Dashboard (read/write):
| Table | Purpose |
|---|---|
clients | Tenant organizations |
client_users | Tenant invitations, verified identity, status, and role |
client_user_instances | Accepted user-to-instance access assignments |
instances | Cloudflare Worker containers per tenant |
dashboard_users | Platform administrators (ROOT role) |
client_subdivisions | Per-tenant agent namespaces |
client_user_subdivisions | User-to-subdivision membership |
invoices | Billing periods per tenant |
invoice_line_items | Individual billing line items |
analytics_events | OTLP-style analytics event storage |
billing_plan_templates | Global, reusable billing plan definitions |
billing_plan_template_actions | Priced actions of a global plan (semantic Fouria action_type + match rule) |
billing_plans | Per-client instantiated plan (cloned from a template) |
billing_plan_actions | Per-client priced actions |
credit_pools | Client credit balance / lifetime consumption |
credit_packages | Purchasable/autobuy credit packages |
Billable actions: Fouria emits semantic action types (
telegram_query,queue_reevaluation,signal_analysis,email_draft,review_analysis, plus 0-creditmunicipal_ingest/daily_digest/sheet_sync/dashboard_view/catalog_housekeeping). The OpenClaw span name travels asspan_name;trigger_type(message|automation) is the cost-analytics axis. Billing is success-only, one action per business unit (action_key) and per trace (email_draft/review_analysissuppresstelegram_query). Credits always come from the plan — the emitted value is advisory.
Billing-plan prerequisite: a client only consumes billable credits while its
statusisproduction. In the production Lerma deployment, a client without an assigned billing plan stays indraftand cannot provision a production instance ({:error, :billing_plan_required}).
All inter-service data access goes through Supabase (PostgREST for the Dispatch Worker, Ecto for the Dashboard) plus a KV cache layer. The FourIA platform API is not exposed publicly — tenant routing is resolved by the Dispatch Worker, metrics are written directly to Analytics Engine, and the Dashboard reads/writes platform data through its Supabase backend.
User Resolution Flow
User Workers receive role and billing context from the Dispatch Worker via HTTP headers:
| Header | Source | Purpose |
|---|---|---|
X-FourIA-Role | Dispatch Worker | User’s role within the tenant (ROOT, ADMIN, BASE_USER) |
X-FourIA-Metadata | Dispatch Worker | base64-encoded plan/billing metadata (plan, seats, credits, etc.) |
The Dispatch Worker resolves user identity by querying client_users and dashboard_users tables during request routing. User Workers read these headers in their resolveCustomerRole middleware — they never make external API calls for user resolution.
Dev-instance role resolution: role normally resolves from a validated client_users row assigned to the requested instance (client_user_instances). On a client’s dev instance the Dispatch Worker adds a fallback: when no per-instance assignment exists, a validated client-level ADMIN is admitted (admins are the ones developing there) and forwarded as ADMIN. BASE_USERs still require an explicit dev-instance assignment, and ROOT operators are unaffected.
PII Filtering (Cloudflare AI Gateway)
PII filtering for all AI provider traffic is handled natively by Cloudflare AI Gateway. No separate outbound worker or Presidio container is required.
User Worker → fetch() → AI Gateway (native PII filtering) → AI provider → response returned
The previously planned Outbound Worker + Presidio pipeline has been replaced by Cloudflare AI Gateway’s built-in PII filtering capabilities.
OTel & Metrics Flow
All telemetry is written directly to Cloudflare Analytics Engine via the ANALYTICS binding — no HTTP API involved:
OpenClaw Gateway (container) → generates OTel metrics
→ POST http://otel.internal/v1/metrics (sandbox bridge; User Worker receives)
→ User Worker parses and accepts metrics (status: 200)
→ Metrics are written to ANALYTICS.writeDataPoint() for AI queries, container activity, etc.
The sandbox otel.internal bridge accepts JSON OTLP payloads and acknowledges receipt. Actual cost/usage metrics are tracked independently through separate event types in the ANALYTICS binding (see src/metrics.ts).
Worker diagnostics push (Observability destinations)
Platform diagnostics use the opposite direction: Cloudflare pushes exported Workers Logs and Workers Traces to Lerma, so the ingest load scales with real traffic instead of with the number of provisioned tenants.
Tenant / ops Worker
→ observability.logs.destinations ["lerma-worker-logs"] (staging)
["lerma-worker-logs-prod"] (production)
→ observability.traces.destinations ["lerma-worker-traces"] (staging)
["lerma-worker-traces-prod"] (production)
│ (Cloudflare Observability → Destinations, OTLP/HTTP JSON, at-least-once)
▼
Lerma POST /api/ingest/otel/v1/logs
POST /api/ingest/otel/v1/traces
│ Authorization: Bearer $OTEL_INGEST_TOKEN (constant-time compare)
│ Lerma.Observability.Otlp — allowlist filter (drops message text,
│ stacks, URLs/queries, user agents, request/response bodies)
▼
Postgres observability_events (unique dedupe_key → idempotent replay)
│ 90-day retention (Observability.Pruner)
▼
GET /api/analytics/v1/uptime/:script_name?window=24h
Instance dashboard → Worker telemetry widget (uptime/failure ratios)
Both destinations are account-level and referenced by name in apps/fouria/wrangler.jsonc and in the WFP upload metadata emitted by Lerma.Cloudflare.Observability.worker_metadata/0 (so freshly provisioned tenants inherit them). Because Lerma is the destination of record, tenant workers set persist: false and head-sample aggressively. Uptime statistics are derived from pushed invocation root spans only — no probing is added, and no events observed (including under sampling) renders as unknown, never as downtime.
This stream does not replace Lerma.Provisioning.HealthMonitor (still the source of instances.status/clients.status) or the billing pipeline (Analytics Engine billable rows + BillingReconcile). Destination telemetry is never used to mint or correct credits.
Instance job history
Operational jobs are tracked separately from pushed worker telemetry, because they are lerma-side work rather than worker invocations:
Freeze / verified checkpoint ──► Lerma.Cloudflare.Containers.stop|checkpoint
│ (snapshot job id, duration, outcome)
Non-passive health poll ──────────► Lerma.Instances.JobObserver
(provisioning, manual start/restart) │ (boot + restoreProgress fields)
▼
Postgres instance_job_events (instance-scoped: backup_create | restore | gateway_start)
│
▼
Instance dashboard → Job activity timeline + Worker telemetry ▸ Job performance
Rows are written only for the instance the job belongs to; there is no fleet
rollup. Recording is best-effort and never changes a job’s outcome, and the
history reads never probe a tenant. restore / gateway_start come from the
boot record the tenant Worker already exposes on GET /api/health while it is
booting; backup_create comes from the control-plane response of the freeze or
checkpoint. Scheduled snapshots taken by the Dispatch cron are not observed by
lerma and therefore do not appear in this table.
Security Model
| Layer | Mechanism |
|---|---|
| DNS | Cloudflare proxied (orange cloud) |
| Auth | Cloudflare Zero Trust Access — per-tenant JWT (aud resolved to tenant) |
| Routing | Tenant isolation via WFP dispatch namespace |
| Data | Per-customer R2 buckets (no cross-tenant access) |
| Platform | Supabase PostgreSQL — service-role PostgREST (Dispatch) + Ecto (Dashboard) |
| Dashboard | Supabase (shared) — internal HTTP API, not publicly exposed |
| Egress | Cloudflare AI Gateway — native PII filtering, only approved hosts |
| PII | Cloudflare AI Gateway native PII filtering (replaces Presidio anonymization) |
| Secrets | WFP secrets API (no secrets stored in dashboard DB) |
| Cache invalidation | Internal endpoint /_invalidate/:slug (bearer-token protected; Worker fails closed without INTERNAL_DISPATCH_INVALIDATE_TOKEN) |
Plan Limits (infrastructure-level, not client billing)
Note: These are internal infrastructure limits mapped to Cloudflare resource allocations per deployment. They are NOT client-facing billing tiers. v1.0-beta uses a single flat-fee plan with credit-based billing. Tiered infrastructure limits exist in code for future multi-plan support.
| Tier | CPU (ms) | Subrequests | Container | R2 Storage |
|---|---|---|---|---|
| Free | 10,000 | 10 | lite | 2 GB |
| Basic | 30,000 | 50 | standard-1 | 8 GB |
| Pro | 50,000 | 100 | standard-2 | 12 GB |
| Enterprise | 90,000 | 1,000 | standard-3+ | Custom |
Glossary
| Term | Definition |
|---|---|
| WFP | Cloudflare Workers for Platforms |
| Dispatch Namespace | Container holding all User Workers |
| User Worker | Per-customer Worker (tenant-{slug}) |
| Dispatch Worker | Routing + auth layer (fouria-dispatch) |
| Outbound Worker | (Deprecated) Egress + PII layer (fouria-outbound) — replaced by CF AI Gateway |
| Partner | Organization owning multiple clients |
| Client | A customer with one instance of the service |
| Instance | A deployed User Worker + Sandbox container |
| PASO4 root | Global platform admin role |
| Partner root | Partner-scoped admin role |
| Presidio | (Deprecated) Microsoft PII detection/anonymization service |
| FourIA Dashboard | Internal management app (Phoenix in Cloudflare Container) |
| KV Cache (TENANT_INDEX) | KV namespace caching tenant slug → entry (60s TTL) |
| Supabase | Managed PostgreSQL + PostgREST API — shared source of truth |
| SUPABASE_URL | Secret — Supabase project URL used by the Dispatch Worker (PostgREST) |
| SUPABASE_SERVICE_ROLE_KEY | Secret — service-role key that bypasses RLS for tenant lookup |
| ANALYTICS | Analytics Engine binding (fourai_cost_metrics) |