Documentation
Architecture Overview & Traffic Flow
Architecture overview, scale targets from 100K to 10M users, and request lifecycle.
1. Architecture Overview
Stackhouse is a Rust-based Supabase alternative for enterprise with:
Scale Targets: 100K → 10M
| Metric | 100K Baseline (SMB) | 10M Enterprise 🏢 |
|---|---|---|
| Total users | 100,000 | 10,000,000 |
| Concurrent users | 10,000 | 1,000,000 |
| Peak RPS (API) | 1,000 | 100,000 |
| WebSocket connections | 50,000 | 5,000,000 |
| DB queries/sec | 5,000 | 500,000 |
| Redis cache size | 4–8 GB | 500 GB–2 TB |
| API pods | 13 | 300–1,000 |
| PostgreSQL primaries | 1 | 10–20 (shards) |
| Regions | 1 | 3–5 (active-active) |
| Monthly cost (GCP) | ~$1,295 | ~$85,000–$120,000 |
Architecture Differences by Scale:
- 100K: Single region, single PostgreSQL primary + replicas, Redis Sentinel
- 10M Enterprise 🏢: Multi-region active-active, Citus sharding, Kafka event bus, Istio service mesh
Stackhouse core components:
- HTTP/WS API — Axum (Rust)
- Auth — Argon2 + JWT
- Database — PostgreSQL via
sqlx(no separate custom storage engine — see the current-state note below) - Vector Search — Qdrant (dedicated vector database)
- Realtime — WebSocket + SSE broadcast (in-process
tokio::broadcast, not Redis pub/sub, today) - Storage — S3-compatible bucket system
- AI — RAG pipeline, embeddings, LLM routing
- Edge Functions — JavaScript runtime (embedded Boa engine); router mounted under
/v1/functionsinmain.rs
Current-state note (2026-08-18)
This page is an infrastructure-scaling design; some of it describes target-state components rather than what exists in the codebase today. Stackhouse's actual data layer is PostgreSQL only — there's no separate custom storage engine. Redis, Citus sharding, Kafka, and Istio (below and throughout this section) are scaling targets for larger tiers, not currently wired into the codebase.
High-Level System Diagram
Rendering diagram…
2. Traffic Flow & Request Lifecycle
Rendering diagram…
Total target latency: p50 < 20ms · p95 < 100ms · p99 < 300ms