Crate-by-crate breakdown of all 23 AltBase crates, the gateway middleware chain, dual-context database design, CDC pipeline, and NATS subject conventions.
Single Binary, 23 Crates
AltBase compiles into a single Rust binary. The codebase is organized as a Cargo workspace with 23 crates, each with a clear responsibility. The atlas-server crate is a thin orchestrator that imports all other crates, builds the Axum router, spawns background workers, and serves dashboard static files. It contains zero business logic.
Crate Dependency Graph
atlas-server (binary entry point)
|
+-- atlas-common (config, errors, telemetry)
+-- atlas-db (pool creation, migrations)
+-- atlas-gateway (API key auth, rate limiting, tenant context)
|
+-- atlas-control-plane (orgs, projects, API keys, provisioning, logs)
+-- atlas-api-engine (REST CRUD, SQL, schema, vector search, advisor)
+-- atlas-auth (signup, login, OAuth, OIDC, SAML, SSO, B2B, RLS)
+-- atlas-storage (buckets, objects, TUS, signed URLs, transforms)
+-- atlas-realtime (WebSocket, CDC, broadcast, presence, cron)
+-- atlas-cdc-fanout (Postgres WAL -> NATS JetStream fan-out)
|
+-- atlas-events (NATS pub/sub, JetStream streams)
+-- atlas-jobs (background job queue, worker)
+-- atlas-search (Tantivy full-text indexing)
+-- atlas-analytics (materialized views)
+-- atlas-billing (Stripe checkout, subscriptions, usage)
|
+-- atlas-integrations (Nango connections, templates, webhooks)
+-- atlas-functions (QuickJS + Wasmtime, deploy, invoke)
+-- atlas-triggers (unified event trigger system)
+-- atlas-workflows (DAG engine, steps, approvals)
|
+-- atlas-vector (embeddings, vector search, RAG, LLM)
+-- atlas-graphql (auto-generated schema, subscriptions)
+-- atlas-mcp (Model Context Protocol server)
Crate-by-Crate Breakdown
Layer 1: Foundation
| Crate | Responsibility | Key Dependencies |
|---|
atlas-common | Config loading (env vars), error types that map to HTTP status codes, structured logging (tracing) | None |
atlas-db | Connection pool creation for both control plane and tenant databases, migration runner | atlas-common |
atlas-gateway | API key authentication middleware, rate limiting middleware, TenantContext injection into request extensions | atlas-common |
| Crate | Responsibility | Key Dependencies |
|---|
atlas-control-plane | Organization CRUD, project CRUD with schema provisioning, API key management (SHA-256 hashing, prefix lookup), request logging, schema refresh, index recommendations | atlas-common, atlas-db |
Layer 3: Core Features
| Crate | Responsibility | Key Dependencies |
|---|
atlas-api-engine | REST CRUD surface under /rest/v1, SQL execution endpoint, schema introspection and caching, query compiler with prepared statements, vector search routing, index advisor | atlas-common, atlas-gateway |
atlas-auth | Email/password auth, magic link, OTP, OAuth 2.0, OIDC, SAML, RLS policy management, SSO (org-level + project-level), customer organizations (B2B), guided setup wizard, JWT signing/rotation | atlas-common, atlas-db, atlas-gateway |
atlas-storage | Bucket CRUD, object upload/download/delete/list, TUS resumable upload protocol, signed URL generation and serving, storage policies, image transforms, cleanup cron | atlas-common, atlas-gateway, atlas-auth |
atlas-realtime | WebSocket endpoint, CDC event delivery to subscribers, broadcast channels, presence tracking, cron job CRUD and execution | atlas-common, atlas-gateway |
atlas-cdc-fanout | Postgres logical replication listener (pgwire), WAL decoding, NATS JetStream publishing | atlas-common, atlas-realtime |
Layer 4: Subsystems
| Crate | Responsibility | Key Dependencies |
|---|
atlas-events | NATS pub/sub helpers, JetStream stream and consumer management | atlas-common |
atlas-jobs | Background job queue backed by NATS JetStream, pull consumer worker, SSRF protection allow-list | atlas-common |
atlas-search | Tantivy-based full-text indexing, CDC-triggered index updates, per-table search endpoints | atlas-common, atlas-gateway |
atlas-analytics | Materialized view definition and background refresh, DashMap cache for hot-path reads | atlas-common |
atlas-billing | Stripe checkout session creation, subscription management, usage tracking, Stripe webhook ingestion | atlas-common |
Layer 5: Automation and AI
| Crate | Responsibility | Key Dependencies |
|---|
atlas-integrations | Nango OAuth connection management, 500+ SaaS connectors, connector templates, inbound/outbound webhooks, circuit breaker, audit logging | atlas-common, atlas-gateway |
atlas-functions | Dual runtime: QuickJS (fast JS with host API) + Wasmtime (sandboxed Wasm), function deploy/invoke, host bindings | atlas-common |
atlas-triggers | Unified trigger system for CDC, auth, storage, and cron events, condition evaluation, dispatcher | atlas-common |
atlas-workflows | DAG workflow engine, 14 step types, approval inbox, NATS-backed step dispatch, SSE run streaming | atlas-common |
atlas-vector | Embedding generation (4 providers), vector backends (pgvector, Redis, Azure Search, Qdrant), hybrid search with RRF, RAG pipeline, LLM answer generation | atlas-common, atlas-gateway |
atlas-graphql | Dynamic GraphQL schema generated from database introspection, queries/mutations/subscriptions, DataLoader batching, schema refresh | atlas-common, atlas-gateway, atlas-api-engine |
atlas-mcp | Model Context Protocol server, auto-generated tools and resources from schema, JSON-RPC transport | atlas-common, atlas-gateway, atlas-api-engine |
Gateway Middleware Chain
Every request to a protected route passes through the gateway middleware pipeline before reaching a feature handler:
HTTP Request
|
v
1. api_key_middleware
- Extract key from Authorization header or ?apikey= query parameter
- SHA-256 hash the key
- Look up hash in the api_keys table
- Resolve: project_id, tier, role, schema_name
- Load auth settings: RSA public key, JWT TTL
- Inject TenantContext into Axum request extensions
|
v
2. rate_limit_middleware
- Read tier from TenantContext
- Redis INCR on rl:{project_id}:{read|write}:{window}
- Compare against tier limits (60/600/6000 per minute)
- Return 429 + Retry-After header if exceeded
|
v
3. Feature Handler
- Extract TenantContext from request extensions
- Begin database transaction
- SET LOCAL search_path TO "proj_{id}"
- Execute business logic
- Commit transaction
- Return response
The TenantContext struct carries the project ID, tier, role, schema name, and auth settings through the entire request lifecycle.
Dual-Context Database Design
Two Databases
| Database | Variable | Contents |
|---|
| Control Plane | ATLAS_CONTROL_PLANE_DATABASE_URL | organizations, platform_users, projects, api_keys, project_auth_settings, org_sso_connections, connector_templates, embedding_configs, knowledge_collections, cron_jobs, event_triggers, request_logs |
| Tenant | ATLAS_TENANT_DATABASE_URL | Per-project schemas containing users, sessions, refresh_tokens, oauth_providers, sso_connections, customer_orgs, rls_policies, storage_buckets, storage_objects, and all user-created tables |
Tenant Isolation
| Tier | Isolation Model | Mechanism |
|---|
| Free | Schema-per-tenant | SET LOCAL search_path TO "proj_{id}" per transaction |
| Paid | Database-per-tenant | Separate PostgreSQL database with dedicated connection pool |
Every SQL query runs inside a transaction that sets the search path, preventing cross-tenant data access at the database level.
CDC Pipeline
The Change Data Capture pipeline flows from PostgreSQL WAL to WebSocket clients:
PostgreSQL WAL (logical replication)
|
v
atlas-cdc-fanout (pgwire listener)
- Decodes WAL entries into structured change events
- Publishes to NATS JetStream
|
v
NATS JetStream (durable stream)
|
+-------+-------+-------+
| | | |
v v v v
WebSocket Search Trigger Auto-embed
delivery indexer evaluator (vector)
Fan-out Consumers
| Consumer | What It Does |
|---|
| Realtime delivery | Pushes change events to subscribed WebSocket clients |
| Search indexer | Updates Tantivy full-text indexes on INSERT/UPDATE/DELETE |
| Trigger evaluator | Checks CDC events against registered trigger conditions |
| Auto-embed | Generates embeddings for configured columns on INSERT/UPDATE |
NATS Subject Naming Conventions
All NATS subjects follow a hierarchical naming scheme:
| Pattern | Purpose |
|---|
atlasdb.events.{project_id}.{event_type} | Application-level events (auth, storage, etc.) |
atlasdb.{project_id}.{environment_id}.{table}.{INSERT|UPDATE|DELETE} | CDC change events per table |
atlasdb.jobs.{project_id} | Background job queue |
atlasdb.workflows.{project_id}.{run_id} | Workflow step dispatch and completion |
atlasdb.triggers.{project_id} | Trigger condition evaluation requests |
Data Flow Patterns
Pattern 1: Synchronous Request/Response
Client -> API Key Middleware -> Rate Limit -> TenantContext -> Handler -> Postgres -> Response
Used by REST CRUD, GraphQL, auth, storage, and MCP tools.
Pattern 2: Fire-and-Forget Event
Handler -> NATS publish (non-blocking) -> Response (immediate)
|
+-> Consumer (background) -> Side effect
Used by auth events, index advisor recording, and storage events.
Pattern 3: Durable Job Queue
API Request -> NATS JetStream (durable) -> Worker (pull consumer) -> Execute -> Callback
Used by background jobs, workflow steps, and integration webhook delivery.
Security Architecture
| Layer | Mechanism |
|---|
| Transport | HTTPS with TLS termination at ingress |
| Authentication | API key (SHA-256 hash, prefix lookup) or JWT (RSA-signed) |
| Authorization | Role-based: Anon, Service, Custom |
| Row-Level Access | Postgres RLS policies evaluated per query |
| Tenant Isolation | Schema-per-tenant with SET LOCAL search_path |
| Data Encryption | AES-256-GCM for secrets at rest, Argon2id for passwords |
| Input Validation | Parameterized queries, identifier validation |
| Rate Limiting | Per-project + per-IP, Redis-backed |
| SSRF Prevention | Allow-list for outbound HTTP in jobs and integrations |
Where to Start Reading Code
| Goal | Entry Point |
|---|
| Server startup | crates/atlas-server/src/main.rs |
| How a route is handled | crates/atlas-{feature}/src/routes.rs |
| Middleware pipeline | crates/atlas-gateway/src/lib.rs |
| CDC pipeline | crates/atlas-cdc-fanout/src/lib.rs |
| Workflow engine | crates/atlas-workflows/src/steps/ |
| Auth flows | crates/atlas-auth/src/routes/auth.rs |