Documentation
Architecture
Understanding the system architecture
Architecture
🏗️ Stackhouse System Architecture
Understanding how Stackhouse works under the hood.
Table of Contents
Correction: earlier versions of this page described a custom in-process LSM-tree storage engine ("Stackhouse-Core": WAL/MemTable/SSTable/compaction files under
src/stackhouse_core/). No such module exists in this codebase — it was aspirational/fictional documentation. Stackhouse stores all relational data in PostgreSQL viasqlx(stackhouse/src/platform/db.rs,StackhouseStore). The diagrams below have been corrected to reflect the actual implementation.
High-Level Architecture
Adjacent services reached over their own APIs, not part of the write/read path above:
- Qdrant (vector search, HTTP)
- boa_engine JS runtime (REST router mounted under
/v1/functionsinmain.rs) - Object storage subsystem (buckets/objects in Postgres, S3-compatible API, CDN, tus resumable uploads)
Component Overview
1. API Layer
Location: stackhouse/src/api/ (handlers.rs, routes.rs, admin.rs, dashboard.rs, graphql.rs, openapi.rs, mcp_server.rs, auto_rest.rs, versioned_api.rs, platform.rs) — not a single api.rs file.
Handles all incoming HTTP/WebSocket requests.
2. Data Storage
Location: stackhouse/src/platform/db.rs (StackhouseStore)
A sqlx::PgPool-backed wrapper providing execute, query, query_simple, insert_returning_id, and simple insert/scan/delete helpers. See Storage Engine for the full breakdown, including the separate Schema-Later Guard (auto schema evolution) and versioned migration service.
3. Data Flow
Write Path
Read Path
Request Processing Flow
HTTP Request Flow
Component Communication
Concurrency Model
Concurrency-relevant components:
- Postgres connection pool:
sqlx::PgPool(default 20 max connections, 3s acquire timeout) - Schema cache:
DashMap(security/guard.rs) - Realtime fan-out:
DashMapoftokio::sync::broadcastchannels, one per subscribed table
Key Design Decisions
1. Why PostgreSQL, Not a Custom Engine
Stackhouse deliberately does not implement its own storage engine. Data durability, MVCC, indexing, and query execution are delegated entirely to PostgreSQL; Stackhouse's own code is the "schema-later" layer on top — automatic ALTER TABLE on new JSON fields, RLS policy management, and the REST/GraphQL/WebSocket surface — rather than a database kernel.
2. Async Architecture
Why Tokio Async?
- High concurrency without threads
- Efficient I/O operations
- Better resource utilization
- Scalable to thousands of connections
Extension Points
Real, verified extension points in the current codebase:
| Extension point | Status |
|---|---|
| Enterprise Connectors | ~89 connectors under stackhouse/src/connectors/ (Slack, Zendesk, Five9, NetSuite, Splunk, ...) — most make real outbound HTTP calls |
| Row-Level Security Policies | Defined per-table via the RLS API (/v1/rls), enforced by security/guard.rs on each request |
| JavaScript Functions | ⚠️ Implemented but not currently reachable — compute/functions.rs implements deploy/invoke via boa_engine and defines create_functions_router(), but that router is never nested into the app in main.rs. Wiring it up (a one-line .nest(...) in main.rs) is a prerequisite for this to work end-to-end. |
There is no StorageEngine/AuthService trait or PolicyEngine type in this codebase — those were aspirational claims in an earlier version of this page, not real extension mechanisms.
Performance Characteristics
No per-layer latency numbers are published here — actual performance is governed by the underlying PostgreSQL deployment and, for vector search, by the external Qdrant deployment, not by fixed constants in Stackhouse's own code. Measure against your own deployment rather than relying on any previously quoted figures on this page.
Next Steps
To dive deeper into specific components:
- Storage Engine - PostgreSQL-backed storage, schema evolution, object storage
- Schema Evolution - Auto-schema magic
- Vector Search - AI features (Qdrant-backed)
- JavaScript Functions - Serverless compute
Continue to Quick Start or back to Index 🚀