Architecture Overview

Reactor is an AI-first backend platform built as a Rust workspace. One unified HTTP surface exposes identity, data, storage, functions, jobs, sites, gateway, and connect — composed in a single process for small deployments or split into independent services at scale.

Design principles

1. Library composition, not subprocess orchestration — capabilities expose router(state), Config, and migrator(). The server wires them together.
2. One HTTP contract, every topology — SDK and CLI code never branch on deployment grade.
3. Auth in-process by default — InProcessAuthClient eliminates JWT round-trips in the unified binary.
4. One Reactor.toml — single config file fans out to per-capability structs at boot.
5. Postgres-first — every capability shares one database pool (or one database per tenant on shared cluster).

---

Rust workspace

reactor-cloud/
├── crates/
│   ├── reactor-core/           # Shared types, AuthClient trait, TenantCtx
│   ├── reactor-policy/         # Policy engine
│   ├── reactor-cache/          # KV / queue primitives
│   ├── reactor-vault/          # Secrets (embedded + OpenBao)
│   │
│   ├── reactor-auth/           # Identity library
│   ├── reactor-auth-server/    # Standalone auth binary (sizes 5–6)
│   ├── reactor-data/           # Data API library
│   ├── reactor-data-server/    # Standalone data binary (sizes 5–6)
│   ├── reactor-storage/        # Object storage library
│   ├── reactor-storage-server/
│   ├── reactor-functions/      # Serverless functions
│   ├── reactor-functions-server/
│   ├── reactor-jobs/           # Background jobs
│   ├── reactor-jobs-server/
│   ├── reactor-sites/          # Static/SSR hosting
│   ├── reactor-sites-server/
│   ├── reactor-ai/             # LLM gateway
│   ├── reactor-connect/        # Data connectors
│   ├── reactor-analytics/      # Product analytics
│   │
│   ├── reactor-server/         # Unified binary (sizes 1–2)
│   ├── reactor-cloud/          # Control plane library
│   ├── reactor-cloud-server/   # Control plane binary
│   └── reactor-cli/            # Developer CLI
│
└── studio/                     # Reactor Studio (Tauri desktop)

Each capability follows the same library shape:

// Every capability crate exposes:
pub fn router(state: AuthState) -> axum::Router { /* /cap/v1/... */ }
pub fn migrator() -> sqlx::migrate::Migrator { /* schema */ }
pub struct Config { /* ... */ }
pub struct State { /* ... */ }

---

Eight capabilities

Capability	Prefix	Purpose
Identity	/auth/v1/*	Sign-up, login, JWT, OAuth, magic links
Data	/data/v1/*	PostgREST-style API, RLS, realtime subscriptions
Storage	/storage/v1/*	Object storage, signed URLs, multipart upload
Functions	/fn/v1/*	WASM, Bun, and Lambda runtimes
Jobs	/jobs/v1/*	Scheduled and event-driven background work
Sites	/sites/v1/* + domains	Static assets, SSR, ISR
Gateway	/ai/v1/*	LLM routing (OpenRouter, Bedrock, Azure)
Connect	/connect/v1/*	Third-party data sync (Airbyte-style)

Analytics (/analytics/v1/*) extends the platform with product event ingestion.

Capability omission

A capability not listed in Reactor.toml is not mounted. Tauri (size 1) builds can omit Functions and Sites to keep the binary under 30 MB.

---

Unified server binary

reactor-server is the sizes 1–2 deployment artifact. It:

1. Builds shared resources once (PgPool, HTTP client, cache, tracing)
2. Runs migrations across all enabled capabilities
3. Constructs AuthService + InProcessAuthClient
4. Merges capability routers under their prefixes
5. Mounts admin, health, and metrics routes
6. Spawns background tasks (job scheduler, signed-URL janitor, Bun warm pool)
7. Drains all tasks on graceful shutdown

// Composition sketch (crates/reactor-server/src/lib.rs)
pub async fn run(cfg: ReactorConfig) -> anyhow::Result<()> {
    let shared = boot::pool::init(&cfg).await?;
    boot::migrate::run_all(&shared, &cfg).await?;
    let auth   = boot::auth::build(&shared, &cfg).await?;

    let caps   = compose::ServerCapabilities::build(&shared, &auth, &cfg).await?;
    let app    = caps.router()
        .merge(admin::router(&shared, &caps, &cfg))
        .layer(TraceLayer::new_for_http());

    let (shutdown_tx, shutdown_rx) = watch::channel(false);
    caps.spawn_background(shutdown_rx.clone());

    // bind, serve, wait for signal, drain
    Ok(())
}

Boot timeline (size 2)

Target: listening in under 1 second.

Step	~ms	Action
0	0	Parse argv, load Reactor.toml + env
10	10	Init tracing
20	20	Build shared PgPool
40	40	Ping Postgres
50–200	200	Run all capability migrations
200	200	Build AuthService + InProcessAuthClient
250–400	400	Build per-capability state, merge routers
420	420	Mount /_admin/*, /health, /metrics
450–470	470	Spawn background tasks, bind listener

---

HTTP surface

GET  /health                          Composite health check
GET  /metrics                         Prometheus metrics

POST /auth/v1/signup                  Identity
POST /auth/v1/token
GET  /data/v1/{table}                 Data (RLS-enforced)
POST /storage/v1/objects/{bucket}     Storage
POST /fn/v1/{name}                    Functions
POST /jobs/v1/runs                    Jobs
GET  /sites/v1/...                    Sites admin
     *.yourdomain.com                 Sites serve (by Host header)

POST /_admin/deploy                   Admin (CLI contract)
GET  /_admin/doctor
GET  /_admin/logs
POST /_admin/migrate
POST /_admin/shutdown
GET  /_admin/version

GET /health returns 503 if any mounted capability fails its internal health check.

---

Topology mapping

Size 1 — Tauri

reactor-server as embedded library inside Reactor Studio. Binds 127.0.0.1 only. Cargo feature g1-tauri trims heavy adapters.

Size 2 — Single node

reactor-server binary. One process, one Postgres, one filesystem. Caddy/nginx for TLS.

Sizes 5–6 — Own cloud

Per-capability reactor-*-server binaries. Independent scaling. Microservices auth mode with HTTP between capabilities.

C6@fly — Shared cluster

Stateless reactor-shared instances + shared Postgres (tenant DBs) + NATS + Supavisor + OpenBao. Control plane at api.reactor.cloud.

The HTTP surface is byte-identical across sizes 1–6 because every binary mounts the same cap::router(state).

---

Shared resources

Built once in boot::pool and handed to every capability:

pub struct SharedResources {
    pub pg:       sqlx::PgPool,
    pub http:     reqwest::Client,
    pub cache:    Arc<dyn CacheBackend>,
    pub clock:    Arc<dyn Clock>,
    pub shutdown: watch::Receiver<bool>,
}

Capabilities never create their own database pools in the unified binary.

---

Background tasks

Capability	Background work	Shutdown
Jobs	Scheduler poll + worker pool	Drain in-flight runs
Storage	Signed-URL janitor, multipart cleanup	Finish current pass
Functions	Bun warm-pool reaper, deployment reconciler	Destroy idle handles
Auth	Key rotation timer	Finish current rotation
Sites	Bundle GC, certificate renewal	Finish current pass

All tasks subscribe to a shared shutdown channel. Default drain budget: 30 seconds.

---

Cargo features

reactor-server/Cargo.toml

[features]
default = ["g2-full"]
g1-tauri  = ["cap-auth", "cap-data", "cap-storage", "cap-functions/runtime-wasm", "cap-jobs"]
g2-full   = ["cap-auth", "cap-data", "cap-storage", "cap-functions", "cap-jobs", "cap-sites"]

cap-auth      = ["dep:reactor-auth"]
cap-data      = ["dep:reactor-data"]
cap-storage   = ["dep:reactor-storage"]
cap-functions = ["dep:reactor-functions"]
cap-jobs      = ["dep:reactor-jobs"]
cap-sites     = ["dep:reactor-sites"]

Binary size budgets:

• Size 1 (Tauri): ≤ 30 MB stripped
• Size 2 default: ≤ 60 MB stripped

---

Control plane (optional)

reactor-cloud-api is separate from reactor-server. It provisions infrastructure (Fly.io today), manages deployments, domains, secrets, and billing — but self-hosters at sizes 1–6 never need it.

reactor-cli → reactor-cloud-api → FlyProvider → customer reactor-server

See Deployment grades for when to use managed vs self-hosted.

---

Related

• Adapters — swappable backend pattern
• Reactor Studio — desktop developer environment
• Configuration — Reactor.toml reference
• FAQ — common architecture questions