WebHost.Systems Architecture

Purpose: Explain the control plane / data plane split, component responsibilities, and canonical request flows for the WebHost.Systems multi-runtime AI agent deployment platform.

Design Principles

1. Runtime portability -- A single abstraction (RPI) across Cloudflare Workers/DO and AWS Bedrock AgentCore.

2. Tenant isolation -- RLS on every table; no cross-tenant data leakage.

3. Deployment immutability -- Deployments are append-only records; rollback via active pointer.

4. Metered by default -- Every invocation emits authenticated telemetry.

5. TypeScript-first -- End-to-end TypeScript across control plane and data plane.

System Diagram (Text)

                         +------------------+
                         |   Web Dashboard  |
                         | (Vite + React +  |
                         |    Clerk Auth)   |
                         +--------+---------+
                                  |
                         Supabase Auth JWT
                                  |
                  +---------------v----------------+
                  |        CONTROL PLANE            |
                  |   (Supabase: PostgreSQL +       |
                  |    PostgREST + Edge Functions    |
                  |    + Realtime + Vault)           |
                  |                                  |
                  |  +----------+  +-------------+  |
                  |  | Agent    |  | Deployment  |  |
                  |  | CRUD/RPC |  | Orchestrator|  |
                  |  +----------+  +-------------+  |
                  |  +----------+  +-------------+  |
                  |  | Billing  |  | Telemetry   |  |
                  |  | Engine   |  | Ingestion   |  |
                  |  +----------+  +-------------+  |
                  +-----+------------------+--------+
                        |                  |
              +---------v------+   +-------v---------+
              |   DATA PLANE   |   |   DATA PLANE    |
              |  (Cloudflare)  |   |  (AgentCore)    |
              |                |   |                  |
              | Workers + DO   |   | AWS Bedrock      |
              | Edge execution |   | Container runtime|
              | Session via DO |   | Session via SDK  |
              +-------+--------+   +--------+---------+
                      |                      |
                      +--- Telemetry Events -+
                                  |
                         +--------v---------+
                         | metrics_events   |
                         | (PostgreSQL)     |
                         +--------+---------+
                                  |
                         pg_cron aggregation
                                  |
                         +--------v---------+
                         | billing_usage    |
                         +------------------+

Component Responsibilities

Control Plane (Supabase)

Data Plane

Canonical Request Flows

Flow A: Create Agent

UI -> POST /rest/v1/rpc/create_agent (RLS: auth.uid() = user_id)
   -> INSERT into agents (status: created)
   -> Return agent record

Flow B: Deploy Agent

UI -> POST /functions/v1/deploy (Edge Function)
   -> Validate bundle (agent.config.json, entrypoint, size)
   -> INSERT into deployments (status: deploying)
   -> Call RPI adapter: deploy(artifact, config, secrets)
   -> On success: UPDATE deployment status -> active
                  SET agents.active_deployment_id
   -> On failure: UPDATE deployment status -> failed
                  SET error_message

Flow C: Invoke Agent

Client -> POST /functions/v1/invoke/:agentId (Edge Function)
       -> Authenticate (Supabase Auth JWT)
       -> Check plan limits (billing_usage vs tier)
       -> Resolve active deployment + runtime provider
       -> Call RPI adapter: invoke(input, sessionId?, options)
       -> Return normalized response (output, usage, traceId)
       -> Data plane emits telemetry event async

Flow D: Usage Aggregation

Data plane -> POST /functions/v1/metrics/report (HMAC-authenticated)
           -> INSERT into metrics_events
pg_cron    -> Aggregate metrics_events into billing_usage by period
Dashboard  -> SELECT billing_usage WHERE user_id = auth.uid()

Data Model (Key Tables)

All tables enforce RLS: auth.uid() = user_id.

Security Boundaries

• Control plane never executes customer agent code.

• Data plane never has broad access to other tenants' data.

• Secrets flow: Supabase Vault -> provider secret mechanism at deploy time.

• Telemetry is HMAC-signed or JWT-authenticated; unauthenticated events are rejected.

Further Reading

• Skills Reference -- Operational guides

• Master Spec -- Full engineering spec

• RPI Spec -- Provider adapter contracts