Architecture

Credible is a distributed system built so that a single governed model can serve every consumer — reliably, at scale, and without downtime. The design rests on one central separation: the control plane manages your data assets, while the data plane serves queries from them.

This split is deliberate. Administrative work — publishing a version, updating permissions, indexing a connection — never contends with live query traffic, and query serving never waits on administration. Each plane scales and fails independently, so a spike in dashboard load can't slow down publishing, and a busy publish pipeline can't slow down the agent answering a question.

The Query Path

Every request — from a person in a workspace, an MCP agent, or a REST API call — follows the same path through the data plane:

flowchart LR
  Consumer["Workspace / Agent / API"] --> Router["Router (data plane)"]
  Router --> W1["Worker"]
  Router --> W2["Worker"]
  Router --> W3["Worker"]
  W1 --> DB[("Your warehouse")]
  W2 --> DB
  W3 --> DB

1. The router resolves your organization from the request hostname and looks up which workers currently hold the requested package version.
2. It load-balances across the healthy replicas holding that version. If a worker becomes slow or unreachable, the router transparently retries another replica — no request is stranded on a failed node.
3. A worker executes the query. Workers run Malloy, compiling each request to optimized SQL and executing it against your warehouse through the environment's managed connection.

The engine also has storage of its own — the lakehouse tier, a SQL catalog over Parquet on object storage — where it keeps the tables, rollups, and caches it builds from your model (see Performance & Cost). A query that a stored copy covers is served from there; the rest run live against the connected database. Connect data where it already lives; you do not need to bring a warehouse to start.

Credentials never leave the control plane, and consumers never touch the database directly. Every query is proxied, authorized, and logged — the single enforcement point described in Governance.

Built for Availability

Serving many consumers from one model means the serving layer has to stay up through worker failures, deploys, and new releases of your model. Three properties make that possible.

Immutable, versioned packages

When you publish, the package is written to object storage as an immutable, versioned archive. A version is never mutated in place — publishing again creates a new version. This makes serving deterministic (every worker loads byte-identical package contents) and rollback trivial (a previous version is still there, untouched).

N-way worker replication

Each package version is loaded onto multiple workers, not one. The control plane continuously reconciles the fleet: if a worker is lost, it re-replicates the version onto healthy workers to restore the target replica count. The router only routes to workers confirmed to hold the version. You set the replication factor per environment and per package — trading redundancy against footprint — with the --replication flag when creating environments or publishing.

Zero-downtime version promotion

New versions are loaded onto workers before they start serving traffic. The current version keeps answering queries until the new one is fully loaded, then promotion flips the latest pointer atomically — in-flight queries are never interrupted. Consumers track latest by default or pin a specific version. Auto-promote and auto-archive manage this lifecycle: a version is promoted only once it's ready, and superseded versions are archived (and their storage reclaimed) automatically.

Built for Scale

The data plane scales horizontally to meet demand:

• Stateless services — the router, workers, retrieval, MCP, and agent services hold no per-request state, so they scale out by adding replicas. They autoscale automatically with load.
• Multi-zone Kubernetes — services run across availability zones with rolling, disruption-budgeted deploys, so node failures and upgrades don't take the service offline.
• Secured edge — all traffic terminates TLS behind a global load balancer with a web application firewall. Outbound queries to your warehouse originate from stable egress IPs, so you can allowlist Credible without opening your database to the world.

Tenancy and Isolation

Each organization is addressed by its own hostnames — <org>.app, <org>.admin, <org>.data, <org>.mcp, and <org>.retrieval under credibledata.com. Every request carries an Auth0 identity or API key whose organization claim must match, and fine-grained authorization is checked on each call. Retrieval data is partitioned per organization with fail-closed isolation.

For customers with strict residency or isolation requirements, Credible also runs dedicated single-tenant cells — fully isolated deployments (including on a separate cloud), selected transparently by endpoint.

How the Concept Index Is Built

Beyond serving queries, the engine builds the concept index — a searchable understanding of your model and its data that powers the AI-assisted workflow end to end. It runs as background pipelines with the write path isolated from the read path — so indexing load never affects query or search latency.

• Before a model exists — connection indexing profiles your raw data landscape (table and column metadata, schema, and relationships) so agents have the context to help you build a model from scratch.
• After you publish — the engine compresses the model into the concept index: every source, dimension, measure, and view, its #(doc) definition, and — with optional value indexing — the actual values of every #(index) dimension, so an agent matches a question by meaning, not by column name.

Search runs through a dedicated retrieval service, separate from the workers that execute queries, so the two scale independently.

One Gateway

Because every query — human or agent — enters through one gateway and routes through the governed data model, that gateway becomes a single point of control and improvement:

• Governance and compliance — one gateway means access controls are enforced consistently and every query is logged to an immutable audit trail.
• Performance and cost — the engine observes query cost and latency across all consumption and uses it to guide materialization and caching.
• A feedback loop — usage analyzed against the model surfaces coverage gaps, semantic drift between teams, and underused data, so the model evolves with the business instead of decaying.

Next Steps