Skip to main content
New to Powabase? Start with Platform overview and Auth & Connection for the basics, then return here for the infrastructure details.

​
Control Plane vs Data Plane

The platform uses a two-tier architecture. A single shared Control Plane manages organizations, projects, users, and authentication. It provisions a Data Plane for each project, with its own Postgres database, auth service, Storage API, Realtime and AI service. On Powabase Cloud, a few pieces are shared across projects rather than per project: the API gateway, the S3 bucket behind Storage, and the Redis the AI workers use as their task queue.
Architecture diagram: Browser → Next.js Frontend → Control Plane API for management; runtime requests go Browser → Kong gateway (shared across projects on Cloud, routing by hostname) → Per-Project Stack (GoTrue Auth, PostgREST, Project Service, Postgres with pgvector, Storage, Realtime). The control plane provisions and manages projects but is not in the data-plane path for runtime traffic.

Two tiers: a shared control plane for management, and per-project data planes for runtime traffic

​
Per-Project Isolation

Each project gets its own infrastructure stack in its own Kubernetes namespace (project-{ref}). One project’s data, users, and configuration are separate from another’s; projects can’t see each other’s databases, files, or API keys. Isolation is enforced at three layers:
  • Compute: each project runs its own Postgres StatefulSet (defaults: 400m CPU, 1Gi memory, 10Gi gp3 storage, overridable per project), its own GoTrue auth pod, its own Storage and Realtime pods, and its own Project Service worker.
  • Network: a project-isolation NetworkPolicy on the namespace allows ingress only from shared-services (where Kong and PgBouncer live) and control-plane (the management tier). Cross-project pod-to-pod traffic is blocked.
  • Storage: all projects share one S3 bucket. Each project’s Storage API is configured with its own prefix (projects/<ref>/) and only reads and writes object paths under it. That boundary is enforced by the Storage API (application layer), not by a separate bucket or separate IAM credentials. Your Storage buckets (storage.buckets) are rows in your project’s own database, so bucket names and policies are per project.

​
API Authentication

Every API request requires two headers: an apikey header and a Bearer token in the Authorization header. Server-side calls set both to the same key; a browser sends the Anon key as apikey and the signed-in user’s access token as the Bearer token. Powabase ships two keys per project, both surfaced in the Studio’s Connect modal. The Service Role (Secret) Key gives full access and bypasses Row Level Security, so use it for server-side calls only. The Anon (Publishable) Key respects RLS policies and is safe to embed in browsers and mobile clients. On the AI surface (/api/*), only the conversation routes accept a signed-in user’s token; the rest need the Service Role key. See Which key for which route.
Never expose the Service Role keyThe Service Role (Secret) Key bypasses all Row Level Security policies. Only use it in server-side code. For client-side applications, use the Anon (Publishable) Key with appropriate RLS policies. The Connect modal also exposes JWT Secret and Database URL; both must stay server-side.
Both keys live in the Connect modal in the Studio. Click the Connect button in your project header (or append ?showConnect=true to any project URL) to copy the Project URL, Anon (Publishable) Key, Service Role (Secret) Key, JWT Secret, Database URL, and pre-built Postgres connection strings.

​
Request Routing

When you make an API call to your project URL (<ref>.p.powabase.ai), the request hits the Kong gateway directly; the control plane is not in the data-plane path. On Powabase Cloud, one shared Kong deployment (kong-projects, in the shared-services namespace) serves every project: it matches the project hostname and routes /api/* paths to the Project Service (AI features), /auth/v1/* to GoTrue (authentication), /rest/v1/* to PostgREST (direct database access), /storage/v1/* to the Storage API, and /realtime/v1/* to the Realtime service. The wildcard ALB ingress that fronts every project sits in front of Kong with an idle timeout of 900 seconds, long enough that agent and workflow SSE streams (which can run for minutes) won’t get cut by an intermediary. CORS is permissive by default at the Kong layer (origins: ["*"], credentials: true), so browsers can call any project URL directly with the Anon (Publishable) Key without you wiring up an allowlist. If you need a narrower posture for compliance, the gateway config is customizable on self-hosted deployments.

​
Database Schemas

Each project database has four user-visible schemas. The ai schema is managed by the platform and stores all AI-related data. The public schema is yours to use for application data. The auth and storage schemas are managed by GoTrue and the Storage API respectively. PostgREST is configured to expose public, storage, and graphql_public schemas. The ai schema is backend-only: it isn’t exposed through PostgREST, and only the project service (using the service role) reads and writes it. Reach AI resources through the typed /api/* endpoints.

​
Next Steps

Auth & Connection

Open the Connect modal, pick the right key, and make your first request.

Sources & Extraction

Learn how document ingestion works.

Database Access

Query your project database via PostgREST.