> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryardent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How Ardent's split-plane architecture keeps your data safe and your branches fast

Ardent follows a split-plane architecture like databricks where the **control plane** and **data plane** are separated:

* **Control plane:** Operated by Ardent. Handles branch orchestration, replication health monitoring, connection routing, auto-scaling, and policy enforcement. Spans across all deployments.
* **Data plane:** Where your data lives. Includes Ardent's replication pipeline, your read replica, your branches, and more. Can be deployed on your cloud or ours.

Only metadata (schema structure, replication status, branch state) flows from the data plane to the control plane. Your actual data never leaves the data plane.

## How it works

```mermaid actions={false} theme={null}
%%{init: {'themeCSS': ".cluster > rect { min-width: 42rem; }"}}%%
flowchart TB
    subgraph CP["Control plane"]
        direction TB
        ORCH["Branch orchestration"]
        PRXY["Branch proxy"]
        ROUTE["Connection routing"]
        HEALTH["Health and WAL monitoring"]
        POL["Policies and auth"]
    end
    subgraph DP["Data plane"]
        direction LR
        PROD[("Production DB")] -->|logical replication| AR["Ardent Replicator + Kafka"]
        AR --> REP[("Read replica")]
        REP --> B1[("Branch 1")]
        REP --> B2[("Branch 2")]
        REP --> B3[("Branch 3")]
    end
    CP <-->|metadata only| DP
```

### Control plane

Always operated by Ardent. Orchestration, policies, routing, and visibility across every branch and connection.

* **Branch lifecycle:** Create, suspend, delete, and route traffic to the right branch. Connection URLs route through Ardent's proxy. Every session is tied to an account, policies apply per branch, and raw URLs never leak.
* **Replication coordination:** Ardent watches replication health and scales the Kafka layer that backs it, so you never have to size or operate brokers yourself.
* **Connector setup:** When you connect a database, Ardent inspects and validates it, and gives you connector-level settings: the default database name for new branches, and any SQL to run on each new branch.
* **Auth, usage, and billing:** Org access, API keys, and usage tracking. Per-user and per-branch visibility Postgres does not give you out of the box.

### Data plane

Where your data physically lives and where branches are served from. Runs on Ardent's infrastructure (fully managed) or in your own cloud account (managed, your cloud).

* **Ardent Replicator**
  * Takes logical replication from production through a Kafka-backed pipeline into the read replica.
  * Handles DDL in flight using **custom event triggers** that detect DDL on the primary and replay it **in order** on the replica, so schema changes keep streaming without stalls or silent drift.
  * Applies changes in order across failures so retries do not leave gaps or duplicates.
  * Manages WAL and slot pressure so replication does not destabilize the primary.
  * Quarantines, resumes, and recovers broken streams without manual replay scripts.
* **Read replica:** Stays in sync with production; branches are always created from the replica, never from production directly, so branch load never hits your primary.
* **Branches (compute and storage):** Each branch is a full Postgres instance cloned from the replica with **compute that auto-scales with load**. Branches share storage from the same replica through copy-on-write, so scaling to many branches is efficient for both compute and storage.
* **Isolation:** Your data stays inside this boundary. Only metadata crosses to the control plane. This means in **managed, your cloud** mode you can maintain residency of all your data without losing Ardent's ability to manage the service.

You connect your database and open branches. The control plane orchestrates; the data plane runs replication, the replica, and branches.

***

## Deployment options

Ardent orchestrates everything from our control plane. The data plane is the only thing that moves.

|                    | **Fully managed**     | **Managed, your cloud** |
| ------------------ | --------------------- | ----------------------- |
| **Control plane**  | Ardent infrastructure | Ardent infrastructure   |
| **Data plane**     | Ardent infrastructure | Your cloud account      |
| **Data residency** | Ardent's cloud        | Your cloud              |

Both modes are fully managed by Ardent. The difference is where the data plane runs.

**Fully managed.** We host the entire data plane. Connect your database and we handle the Ardent Replicator, Kafka pipeline, read replica, and branch compute.

**Managed, your cloud.** Same managed experience, but the data plane deploys into your own cloud account. Your data never leaves your infrastructure. The control plane still orchestrates everything via API; all replication and branch compute runs inside your network.