Reference

Architecture

SuperChargeDB is built on a modern serverless cloud platform. A single API service fronts the SQL catalog, vector index, object storage, key-value store, and managed inference, and runs the shared enforcement core on every request.

Components#

Component	Backing service	Role
API service	Serverless runtime	Front door: auth, enforcement, search pipeline.
Catalog	SQL database (SQLite)	Unit rows, FTS5 lexical index, principals, grants, audit log.
Vector planes	Vector index ×4	Dense ANN indexes: text, visual, audio, doc-visual.
Raw store	Object storage	Original source bytes referenced by source_uri.
Manifest	Key-value store	Audit-chain head + small manifests.
Inference	Managed inference	Embeddings + cross-encoder rerank.
Console	Serverless runtime (Next.js)	Web UI + Better Auth sessions in the same catalog.
Landing + docs	Static asset hosting	This marketing + documentation site.

Request lifecycle#

A POST /v1/search flows through the Worker like this:

lifecycle

1. Resolve principal   (bearer token | SSO JWT* | session cookie)
2. Resolve grants      (direct + role grants, expand "*", strip write/admin if read_only)
3. Clamp scope         (requested ∩ allowed  ->  effective_scopes)
4. Embed query         (managed inference: bge-m3)
5. Dense retrieve      (vector index per plane, scope pushdown)
6. Lexical retrieve    (catalog FTS5 BM25, scope-clamped SQL)
7. Fuse                (Reciprocal Rank Fusion)
8. Hydrate + ACL       (catalog lookup; drop hits failing the ACL filter, count them)
9. Rerank              (managed inference cross-encoder over ACL-visible top-N)
10. Trace + audit      (per-stage cost/latency; append hash-chained audit row)

* SSO / Access JWT verification is reserved (roadmap).

Local ↔ production parity#

The same service code runs locally and on the global edge; there is no separate server tier. Service bindings (catalog, vector index, object storage, key-value store, inference) are declared once and resolved identically in both environments.

One enforcement core#

Authentication, grant resolution, scope clamping, ACL filtering, and audit logging live in a single module that every access surface calls. This is what guarantees REST, the console, and future clients cannot drift in what they allow — see the Security model.

Cost model

Inference cost is measured in inference units and estimated at $0.011 / 1,000 units, surfaced per query in the response trace. The guiding principle: retrieve cheaply, spend deliberately.