Data Model
The schema, the tenancy model, and what each migration actually established.
One database, extended for the job
PostgreSQL is the single system of record, with pgvector added for semantic caching and embedding operations. Migrations are numbered and forward-only — the migration history is the schema's real changelog, more reliable than any diagram.
Schema, grouped by what it does
| Area | What it establishes |
|---|---|
| Extensions | pgvector, for similarity search |
| Identity | Organizations, users, authentication |
| Audit | The event trail for security-relevant actions |
| Tenant isolation | RLS policies enforcing per-org boundaries |
| RBAC | Permissions, roles, role assignments, role–permission mappings |
| Access | API keys, BYOK credentials |
| Usage | Per-request records — provider, model, latency, tokens, retries, fallover, HTTP status |
| Policy | Provider config, routing/cache/shadow policy tables, cache entries, experiments |
| Billing | Plans, subscriptions, usage counters, webhook events |
| Catalog | Model catalog, per-org model enablement, provider status, routing modes |
| Plans | The three-tier catalog: Free, Business, Enterprise |
The entities worth knowing by name
- Organization
- The tenant boundary. Owns members, credentials, keys, policies, billing.
- Usage record
- One row per request: provider, model, latency, tokens, retries, whether it failed over, HTTP status.
- Entitlement
- A feature or limit derived from the org's plan. Code checks the entitlement, never the plan name.
- Credential
- An envelope-encrypted BYOK secret, scoped to org + provider + purpose.
- Routing decision
- The router's output: chosen provider, strategy, full ranking, rejected candidates and why, confidence, estimated cost/latency/savings.
The isolation guarantee
Note
Every tenant-scoped table has an RLS policy keyed to the org context set at the start of a transaction, and the app connects as a non-owner role — so isolation can't be bypassed from application code, intentionally or by mistake.
Estimates aren't invoices
Read this before you build a report off these numbers
Estimated savings and estimated cost are modelled counterfactuals — for example, versus the most expensive eligible candidate for that request — meant to explain routing behavior, not to reconcile against a bill. Usage metering that powers the dashboard today is request/estimate-based, not full per-token metering. See Roadmap for where that's headed.
Related