Skip to content
Aurabase Logo
aurabase

Architecture

How a request travels from your client to Postgres, how organizations and projects are isolated, and how services scale.

Explanation7 min readLevel intermediateRevised on Nov 4, 2026

One backend, eight services#

Aurabase is a Rust monorepo that builds eight Axum services. Each service has its own port and its own /v1/<service>/… routes, and services talk to each other over NATS request/reply. All traffic from your applications goes through one gateway.

A service can restart, crash or be deployed on its own. The gateway tracks the health of each service with a circuit breaker: after 5 failures within 60 seconds, it answers 503 for that service for 30 seconds, then tries it again.

Services and responsibilities#

Each service owns one domain, its own SQL migrations and its own data. Your applications reach them only through the gateway.

ServiceDomainResponsibilities
aura-gatewayAPI gatewayProxy, authentication middleware, rate limiting, circuit breaker
aura-authAuthenticationSign-up, sign-in, OAuth 2.1, TOTP MFA and WebAuthn, sessions, JWKS
aura-dbDatabaseCRUD over PostgREST, versioned migrations, type generation, schema management
aura-realtimeRealtimeWebSocket, SSE, event relay, presence, Postgres change data capture
aura-storageStorageS3-compatible object storage, multipart upload, signed URLs, image transforms
aura-functionsEdge FunctionsWASM and Deno runtimes, cron, asynchronous job queue, dead-letter queue
aura-notificationsNotificationsTransactional email (SMTP), SMS, mobile push, HMAC-signed webhooks
aura-aiAI GatewayLLM inference through one endpoint, embeddings, RAG with pgvector

Isolation by organization and project#

Each organization gets its own PostgreSQL cluster, provisioned with CloudNativePG (CNPG) in a Kubernetes namespace reserved for it. No cluster, namespace or connection pool is shared between two organizations. The cluster's capacity (vCPU, memory, replicas) follows the organization's plan.

Inside that cluster, each project gets its own Postgres database, split into four schemas. Each project has its own connection role, which is a member only of its own roles. Rights on a project's schemas are granted to those roles and never to PUBLIC. The gateway sets the connection search_path from the project in the client's JWT, and application tables are protected by row-level security (RLS).

On the enterprise offer, a project can also get a dedicated CNPG cluster in its own namespace. Isolation then comes from the physical separation of clusters, in addition to permissions.

SchemaOwnerContent
project_{uuid}youYour application tables
project_{uuid}_authaura-authusers, sessions, oauth_accounts, mfa
project_{uuid}_storageaura-storagebuckets, objects, rls_policies
project_{uuid}_platformplatformfunctions, jobs, cron, api_keys, webhooks

Three consequences follow:

  • No cross-tenant access. Two organizations never share a cluster, a namespace or a connection pool.
  • Independent migrations. Each project migrates and rolls back on its own.
  • Plain export. pg_dump --schema='project_*' dumps a project's data, extensions and policies.
Shared schema

The aura_console schema is shared. It holds the projects table and the Studio sessions. No application data goes through it.

From curl to Postgres#

The gateway checks every request before routing it. This is the path of GET /v1/db/{projectId}/devices from a REST client:

request pathtext
1. TLS termination        client → aura-gateway
2. Request ID and tracing request_id and trace_id are attached to the request
3. Rate limit             token bucket, answers 429 when the limit is reached
4. Authentication         JWT decoded and claims checked: sub, project_id, role
5. Circuit breaker        the target service is HEALTHY, so the request goes through
6. Execution              search_path set to the project's schemas, then the query runs under RLS

Each step writes structured logs with tracing, correlated by request_id.

Scaling#

Services are stateless. To add capacity, start another replica of the binary and connect it to NATS. It joins the cluster and serves requests when it is ready. There is no leader election and no distributed coordination.

To go further#