Architecture Deep Dive

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

Layer 2: Platform Management

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