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
tc| Component | What it does | Notes |
|---|---|---|
| Edge | Terminates TLS for *.apps.<domain>, signs people in, checks access, routes by host name, serves static sites and the /_tc/* endpoints | Only the Edge holds the wildcard certificate |
| edge-auth | The Edge's sign-in service: OIDC code flow with PKCE, email links, the single sign-on cookie, the no-access and archived pages | Asks the Hub whether a person may open a project; caches the answer for 5 seconds |
| hub-api | REST API for the console and CLI, live status over server-sent events, and the MCP endpoint | Writes desired state and queues jobs; has no cloud-resource permissions |
| hub-worker | Builds and deploys, reconciles containers, routes, databases and buckets, runs Org Sync, cost pulls, lifecycle rules and the cron scheduler | The only component that changes infrastructure |
| Hub DB | Projects, deployments, grants, requests, the org mirror, costs, audit | Separate from app databases |
| Data API | One PostgREST per project; verifies the user's token and applies row-level security | Same engine as Supabase's REST API |
| Storage service | Buckets, ownership rules, quotas, content-type checks, signed URLs | Holds the only blob credential |
| Integration Gateway | Pass-through to vendor APIs with grant checks, credentials per connection mode, caching, retry and audit | Holds the vendor credentials; apps never see them |
What happens on a request
- A browser asks for
https://q3-variance.apps.contoso.com/. - The Edge drops any
X-TC-Userheader the client sent, then asks edge-auth to verify the request. - 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. - 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). - If allowed, the Edge forwards the request to the app with a fresh
X-TC-Usertoken: an ES256 JWT valid for 5 minutes, audiencetc:app:q3-variance, carrying the person's id, name, email, department, job title, groups and app roles. - 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
- Uploadconsole · CLI · MCPqueuedThe source bundle goes to hub-api, which stores it and creates the deployment. Status streams back live.
- Detect and preparehub-workerbuildingDetects the runtime, applies db/migrations and creates the buckets declared in tc.json.
- Buildhub-workerbuildingBuilds the container image, or publishes a static site (static sites skip the next step).
- Start and checkhub-workerdeployingStarts the container and waits for its health check.
- Services and integrationshub-workerStarts cron and worker services, scans the code for integration use and files access requests for anything not yet granted.
- Promotehub-worker → EdgereadyRoutes 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-workerchanges 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.
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.