> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Platform Architecture
> How Credible serves governed models reliably, at scale, and under load
Credible is a distributed platform 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.
Manages the resource hierarchy — environments, connections, packages, versions, permissions — and orchestrates indexing and materialization. Reached at `.admin.credibledata.com` and through the [Credible App](https://credibledata.com).
Serves your published models: executes queries, powers agents, and serves data apps. Optimized for low latency and high concurrency at `.data.credibledata.com`.
## The Query Path
Every request — from a person in a workspace, an [MCP agent](/how-to/analyzing/ai-assistants-mcp), or a [REST API](/how-to/integrating/apis) call — follows the same path through the data plane:
```mermaid theme={"languages":{"custom":["/languages/motly.tmGrammar.json","/languages/malloy.tmGrammar.json"]}}
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](/concepts/why-malloy), compiling each request to optimized SQL and executing it against your warehouse through the environment's [managed connection](/how-to/modeling/connect-data).
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](/concepts/governed-platform).
## 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](/how-to/modeling/publishing), 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, and 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](/platform-admin/cli) 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](/how-to/modeling/publishing) manage this lifecycle: a version is promoted only once it's ready, and superseded versions are archived (and their storage reclaimed) automatically.
Indexing and materialization run **asynchronously** after publish — the model serves live queries immediately, and search and materialized tables come online shortly after. Publishing is never blocked waiting on them, and queries always return correct results by falling back to live execution until a materialized table is ready.
## 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 simply 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 platform 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 — `.app`, `.admin`, `.data`, `.mcp`, and `.retrieval` under `credibledata.com`. Every request carries an [Auth0](/how-to/integrating/apis#authentication) 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.
## The Context Engine's Pipelines
Beyond serving queries, the platform builds a searchable understanding of your data to power the AI-assisted workflow end to end. This is the foundation of the [Context Engine](/how-to/analyzing/overview), and 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](/how-to/modeling/ai-modeling) from scratch.
* **After you publish** — package indexing captures the model's sources, dimensions, measures, and views, and optional [dimensional indexing](/how-to/modeling/metadata-tags) makes field *values* searchable — so an agent can match a question to the right entities and values in your data.
Search runs through a dedicated retrieval service, separate from the workers that execute queries, so the two scale independently.
## The Semantic Hub
Because every query — human or agent — routes through the semantic layer, Credible becomes a single point of leverage for control and improvement:
* **Governance and compliance** — one gateway means [access controls](/how-to/modeling/fine-grained-acls) are enforced consistently and every query is logged to an immutable audit trail.
* **Performance and cost** — the platform observes query cost and latency across all consumption and uses it to guide [materialization](/how-to/modeling/persistence) 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
Chat with data in governed workspaces
How models become versioned, served packages
Build on the Admin, Data, and Retrieval APIs
Connect agents to your semantic models