# Architecture

> How tenants, applications, the connect plane and the edge plane fit together, sharing one database over HTTP, and why the TLS hot path never waits on billing.

Source: https://docs.customdomain.ai/docs/concepts/architecture

## Tenants and applications

Every object belongs to a **tenant**. A tenant holds **members** (with roles),
**applications**, API keys, connections, webhooks, and billing. An
**application** is one product surface: connections and widget tokens are minted
against an application, and its `client_secret` is what your server exchanges for
[widget JWTs](/docs/authentication/widget-tokens).

## The two planes

* **Connect plane** (the control-plane): the `/v1` REST API, the six
  [ways to connect](/docs/connect-flow/overview#the-four-rails), the propagation
  poller, quotas/metering, webhooks, and the OAuth and one-click setup machinery.
* **Edge plane**: on-demand TLS termination + reverse proxy, gated by an
  internal `ask` call to the control-plane.

Only the control-plane talks to the Postgres database. The edge has no database
access: it scales independently and talks to the control-plane only over HTTP.

A production deployment also runs the console (the web app), this
documentation site, the MCP server for AI agents, a Caddy reverse proxy in front
of the public hostnames, and a status monitor. The domain-connection logic
(connect, templates, sell, monitor, webhooks, billing) runs as libraries inside
the control-plane process, not as separate services.

## The edge hot path

`POST /internal/ask` (shared-secret auth via `X-Edge-Auth` / `EDGE_ASK_SECRET`)
is the call that gates certificate issuance. It answers `{ approved }` from a
lookup of the connection for the host, with no billing logic, so the TLS
handshake never blocks on business logic. A host is approved iff a connection for
it exists and is `live` or `propagating`, it has not been removed, and its record
set includes an edge `CNAME`/`ALIAS` or the platform's `A` records (otherwise the
reason is `no_edge_record`). The edge then issues the certificate on demand
during the handshake. Quota and metering are enforced only on the control-plane
write path, never here.

The edge makes three other internal calls with the same shared secret:
`POST /internal/cert-status` (certificate state), `GET /internal/removed-hosts`
(hosts to stop serving and stop renewing) and `POST /internal/traffic` (request
counts).

See [Connections](/docs/concepts/connections) for the lifecycle.