Skip to main content

Architecture overview

vastframe has a control plane (the Hub, which decides what should exist) and a data plane (the Edge and the services that serve apps and their data). The console, the CLI, the MCP server and the SDK are all clients of the same Hub API.

Components​

Clients
Browser
People using your apps and the console
Claude / Copilot
Any MCP client
tc
The CLI
Edge
EdgeTLS · sign-in · routing
Router
Routes by host name, serves static sites
edge-auth
Sign-in, access check, signed X-TC-User
Your identity provider
Entra ID · OIDC · WorkOS · email links
/_tc/db/_tc/storage/_tc/intconsole · api · mcp
Control plane
Hubdecides what should exist
hub-api
REST · live status · MCP
hub-worker
Build, deploy, reconcile, Org Sync, cost, lifecycle, cron
Hub DB
Projects, grants, requests, audit
Data plane
Your apps and their dataone set per project
Your app
Static, web or API
Cron & workers
Scheduled and long-running
Data API
PostgREST, row-level security
Storage service
Buckets, quotas, signed URLs
Integration Gateway
Grant checks, credentials, audit
App database
Postgres, one per project
Your systems
Microsoft 365
Excel, SharePoint, mail
Teams
Notifications, approvals
Salesforce
Delegated OAuth
On-prem SQL / ERP
Read-only by default
ComponentWhat it doesNotes
EdgeTerminates TLS for *.apps.<domain>, signs people in, checks access, routes by host name, serves static sites and the /_tc/* endpointsOnly the Edge holds the wildcard certificate
edge-authThe Edge's sign-in service: OIDC code flow with PKCE, email links, the single sign-on cookie, the no-access and archived pagesAsks the Hub whether a person may open a project; caches the answer for 5 seconds
hub-apiREST API for the console and CLI, live status over server-sent events, and the MCP endpointWrites desired state and queues jobs; has no cloud-resource permissions
hub-workerBuilds and deploys, reconciles containers, routes, databases and buckets, runs Org Sync, cost pulls, lifecycle rules and the cron schedulerThe only component that changes infrastructure
Hub DBProjects, deployments, grants, requests, the org mirror, costs, auditSeparate from app databases
Data APIOne PostgREST per project; verifies the user's token and applies row-level securitySame engine as Supabase's REST API
Storage serviceBuckets, ownership rules, quotas, content-type checks, signed URLsHolds the only blob credential
Integration GatewayPass-through to vendor APIs with grant checks, credentials per connection mode, caching, retry and auditHolds the vendor credentials; apps never see them

What happens on a request​

  1. A browser asks for https://q3-variance.apps.contoso.com/.
  2. The Edge drops any X-TC-User header the client sent, then asks edge-auth to verify the request.
  3. With no session, edge-auth redirects to your identity provider and back to one callback at auth.apps.<domain>, then sets an encrypted session cookie on .apps.<domain>, which signs the person in to every app.
  4. edge-auth asks the Hub whether this person may open q3-variance (cached for 5 seconds; the Hub flushes the cache when access changes or a kill switch is pulled).
  5. If allowed, the Edge forwards the request to the app with a fresh X-TC-User token: an ES256 JWT valid for 5 minutes, audience tc:app:q3-variance, carrying the person's id, name, email, department, job title, groups and app roles.
  6. If not allowed, the person sees a page that names the owner to ask. An archived or disabled project shows its own page.

What happens on a data call​

tc.db.from('expenses').select('*') in the browser becomes GET /_tc/db/expenses?select=* on the app's own origin. The Edge authenticates it like any request, strips the cookie and the /_tc/db prefix, and sends it to the project's Data API with Authorization: Bearer <X-TC-User>. PostgREST verifies the token against the Hub's keys, switches to the tc_user role, and Postgres row-level security policies decide which rows come back using helpers like tc.user_id() and tc.has_role('approver'). Storage (/_tc/storage/*) and integrations (/_tc/int/*) follow the same pattern.

What happens on a deploy​

  1. Uploadconsole · CLI · MCPqueued
    The source bundle goes to hub-api, which stores it and creates the deployment. Status streams back live.
  2. Detect and preparehub-workerbuilding
    Detects the runtime, applies db/migrations and creates the buckets declared in tc.json.
  3. Buildhub-workerbuilding
    Builds the container image, or publishes a static site (static sites skip the next step).
  4. Start and checkhub-workerdeploying
    Starts the container and waits for its health check.
  5. Services and integrationshub-worker
    Starts cron and worker services, scans the code for integration use and files access requests for anything not yet granted.
  6. Promotehub-worker → Edgeready
    Routes the production and preview hosts to the new deployment and returns both URLs.

A deploy never fails for lack of an integration permission: the app goes live, and the calls that need approval answer ACCESS_PENDING until someone approves.

Least privilege​

  • The API that people reach (hub-api) has no cloud-resource rights. A bug in request handling can't directly create or delete infrastructure.
  • Only hub-worker changes resources, and on Azure only inside vastframe's managed resource group.
  • On Azure the control plane runs in its own Container Apps environment, separate from the environment where user apps run, so a buggy or malicious app can't reach Hub internals over the network.
  • App code never holds database superuser credentials, blob keys or vendor credentials.
Availability

The topology above runs today on the local stack, where Docker stands in for Azure Container Apps, Azurite for Blob Storage, a local folder and Caddy for DNS and certificates, and a local encrypted store for Key Vault. The Azure drivers (Container Apps, ACR Tasks, Key Vault, Azure DNS, Cost Management, Postgres Flexible Server with Entra authentication) are being built behind the same interfaces. See Deployment options.

Was this page helpful?