Architecture
How a request travels from your client to Postgres, how organizations and projects are isolated, and how services scale.
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.
| Service | Domain | Responsibilities |
|---|---|---|
aura-gateway | API gateway | Proxy, authentication middleware, rate limiting, circuit breaker |
aura-auth | Authentication | Sign-up, sign-in, OAuth 2.1, TOTP MFA and WebAuthn, sessions, JWKS |
aura-db | Database | CRUD over PostgREST, versioned migrations, type generation, schema management |
aura-realtime | Realtime | WebSocket, SSE, event relay, presence, Postgres change data capture |
aura-storage | Storage | S3-compatible object storage, multipart upload, signed URLs, image transforms |
aura-functions | Edge Functions | WASM and Deno runtimes, cron, asynchronous job queue, dead-letter queue |
aura-notifications | Notifications | Transactional email (SMTP), SMS, mobile push, HMAC-signed webhooks |
aura-ai | AI Gateway | LLM 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.
| Schema | Owner | Content |
|---|---|---|
project_{uuid} | you | Your application tables |
project_{uuid}_auth | aura-auth | users, sessions, oauth_accounts, mfa |
project_{uuid}_storage | aura-storage | buckets, objects, rls_policies |
project_{uuid}_platform | platform | functions, 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.
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:
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#
- Database
Postgres, schemas, migrations, RLS, TypeScript type generation
- Auth
OAuth, MFA, session lifecycle, RBAC
- Realtime
WebSocket, SSE, presence, Postgres changes
- Storage
S3-compatible buckets, transforms, signed URLs
- Edge Functions
WASM and Deno runtimes, cron, dead-letter queue
- Conventions
Naming of schemas, columns and RLS policies