Two-Plane Model

HatiData splits its responsibilities across two independent planes: a data plane that runs inside your infrastructure and touches your data directly, and a control plane that handles identity, policy, billing, and orchestration from HatiData-managed infrastructure. This separation is the single most important architectural decision in HatiData — it determines where your data travels, who can access it, and how the system scales.

The Core Idea

Your data never leaves your environment. The proxy that reads and writes your data runs in your VPC, on your hardware, under your network policies. The control plane — which handles authentication, policy evaluation, quota enforcement, and the dashboard — runs in HatiData's infrastructure and communicates with your data plane over encrypted, authenticated channels.

Your VPC / Your Machine
+--------------------------------------------------+
|  Agents (Python, TypeScript, MCP)                |
|       |  SQL over Postgres wire protocol          |
|       v                                          |
|  +------------------------------------------+    |
|  |  Data Plane  (proxy)                     |    |
|  |  ----------------------------------------|    |
|  |  Embedded columnar execution engine      |    |
|  |  Multi-tier cache                        |    |
|  |  Local policy enforcement                |    |
|  |  Snapshot-based storage access           |    |
|  +------------------------------------------+    |
+------------------------+-------------------------+
                         |  mTLS / PrivateLink
                         v
HatiData Cloud
+--------------------------------------------------+
|  Control Plane  (API server)                     |
|  -----------------------------------------------  |
|  JWT + API key + federated auth                  |
|  RBAC / ABAC policy engine                       |
|  Quota management + billing                      |
|  Provisioning + multi-tenancy                    |
|  Dashboard (React)                               |
+--------------------------------------------------+

Data Plane

The data plane is a native binary that listens using the Postgres wire protocol. Agents connect to it exactly as they would connect to any Postgres-compatible database — no special client libraries are required.

What lives in the data plane

Component	Responsibility
Postgres wire protocol listener	Accepts connections from agents and SQL clients
Multi-stage query pipeline	Admission, policy, transpilation, execution, masking, metering
Embedded columnar engine	Runs queries locally against your data
Multi-tier cache	In-memory, local SSD, and object storage layers
Transpilation cache	Keyed on SQL hash, avoids re-parsing identical queries
Local RLS enforcer	Applies row-level filters before query execution
Column masking engine	Redacts or hashes sensitive columns at the result layer
Audit emitter	Writes hash-chained audit records to durable storage

The data plane does not store your credentials, encryption master keys, or billing state. It receives short-lived policy bundles from the control plane and evaluates them locally, so queries continue to run even during brief control plane connectivity interruptions.

Embedded columnar engine

HatiData's query engine runs embedded inside the proxy process — there is no separate database server to manage. This means zero network hops between query parsing and execution, predictable memory footprint, and native columnar performance on analytical workloads.

Control Plane

The control plane is an API server that manages everything outside the hot query path. It handles identity, policy distribution, quota enforcement, provisioning, and the dashboard.

What lives in the control plane

Component	Responsibility
Auth service	JWT issuance, API key validation, federated identity (OIDC/SAML)
Policy engine	RBAC role resolution, ABAC attribute evaluation, policy bundle compilation
Quota manager	Per-agent credit tracking, monthly limits, overage enforcement
Billing service	Subscription management, usage reporting
Provisioner	Spins up data plane infrastructure on new account creation
Dashboard	React UI for query history, usage analytics, policy management
Audit store	Receives and indexes hash-chained audit records from data planes

The control plane never processes your actual query data. It distributes policy bundles, validates tokens, and aggregates metering signals — but query results flow exclusively through the data plane.

Deployment Modes

HatiData supports three deployment topologies depending on your data residency and operational requirements.

Local Mode

The data plane and a lightweight control plane run together on a single machine or within a single container stack. No external network connectivity required. Ideal for development, CI, and air-gapped environments.

localhost
+-- proxy           (data plane)
+-- control plane   (embedded control plane)
+-- query engine    (in-process)

Policy evaluation, metering, and audit still function — they write to local storage rather than HatiData's cloud infrastructure.

Cloud Mode

Your data plane runs in your VPC. The control plane runs in HatiData's managed infrastructure. The two communicate over HTTPS with mutual TLS certificate verification.

This is the recommended topology for production deployments. It provides managed upgrades for the control plane, centralized audit, and cross-team policy management without requiring you to operate additional services.

Enterprise Mode (PrivateLink)

For organizations that require all traffic to stay within private backbone networks, HatiData supports AWS PrivateLink, GCP Private Service Connect, and Azure Private Link. The data plane connects to the control plane without traversing the public internet.

Your VPC
+-- proxy                    (data plane)
+-- VPC Endpoint --------------------------------+
                                                 | Private backbone (no public internet)
HatiData Cloud                                   |
+-- PrivateLink Service <------------------------+
    +-- control plane

See PrivateLink Configuration for setup instructions per cloud provider.

How the Planes Communicate

At startup, the data plane authenticates to the control plane using a provisioning credential and receives an initial policy bundle. This bundle contains compiled RBAC roles, ABAC attribute sets, column masking rules, and quota thresholds.

The data plane polls for policy updates on a configurable interval (default: 30 seconds) and caches the current bundle locally. If connectivity to the control plane is interrupted, the data plane continues serving queries using the last-known policy state for up to a configurable grace period (default: 5 minutes).

Metering signals (query credits consumed, row counts, agent IDs) are batched and shipped to the control plane asynchronously on a 10-second flush cycle. This means brief connectivity interruptions do not affect query throughput.

Audit records are written locally first (durable, hash-chained) and then replicated to the control plane's audit store. The local copy is authoritative — even if replication is delayed, the audit trail is complete on your infrastructure.

Security Boundaries

What crosses the boundary	Direction	Format
Policy bundles	Control -> Data	Signed JSON, verified at data plane
Metering signals	Data -> Control	Batched protobuf over mTLS
Audit replication	Data -> Control	Hash-chained records, tamper-evident
Token validation requests	Data -> Control	JWT introspection (or cached locally)
Query data / results	Never	Stays entirely within data plane

Your query results, intermediate result sets, and cached data never leave the data plane.

Related Concepts

• Query Pipeline — The stages every query takes through the data plane
• Security Model — Authentication, authorization, and encryption across both planes
• PrivateLink Configuration — Private network connectivity for Enterprise deployments
• Quickstart — Running both planes on a single machine
• When to Use HatiData — Managed control plane with your own data plane