Documentation

One control plane. As many proxies as you need.

The shape of DataDam at every scale: one proxy for a single VPC, two for failover, regional fleets for latency or residency, business-unit isolation. The single proxy carries a lot of traffic; multi-proxy is usually a posture question, not a throughput question.

The shape

One control plane. Many proxies. Per-org governance.

The control plane is the policy authoring and audit aggregation layer. Proxies are stateless workers that pull policy and emit telemetry. Adding a proxy is a console operation that takes two minutes.

Rule 1
One control plane. The control plane is org-scoped: policies, contracts, agent keys, sources, kill switches, blueprints, and trust scores live in one Postgres row set per org. Every proxy talks to the same control plane.
Rule 2
Many proxies. Each proxy carries a unique license key, provisioned in the console at /onboard/proxy. Two minutes from "create license" to "first heartbeat." Provisioning a new proxy never edits or invalidates existing proxies.
Rule 3
Per-proxy state stays per-proxy. Source credentials live in each proxy host's secrets layer. Token store (for tokenize mode) lives on each proxy host's Postgres unless you point multiple proxies at one shared DB.
Rule 4
Synced state stays consistent. Every proxy pulls /sync/keys on a 5-minute interval. Org-level policy changes, agent key revocations, and kill switch flips propagate to every proxy automatically.

Topologies

Five shapes you'll actually deploy.

Each topology is the answer to a specific operator question: latency, regulatory boundary, blast radius, uptime contract, organizational separation. Pick the one (or two) that match your posture.

Per-region

When

Latency or regulatory boundary matters. EU customer data must process in EU; US-east agents see lower latency from us-east proxies than from eu-west proxies.

How

One proxy per region. Each proxy targets the same control plane. Agent SDK base URL is region-specific (proxy.us-east.example.com vs proxy.eu-west.example.com). Each proxy holds the source credentials for the data sources in its region.

Tradeoffs

Per-region failover is independent. Per-region telemetry rolls up to the same control plane org. The audit log shows which proxy served each request via the proxy_id column, so you can filter to a region at query time.

Per-environment

When

Prod, staging, and dev share governance config but each environment has its own data sources and its own agents.

How

One proxy per environment. Same org on the control plane (so policy authoring is single-pane) or separate orgs (if you want separate retention windows and separate audit logs).

Tradeoffs

Same org = single source of truth for contracts and policies. Separate orgs = clean separation but you author the same contract three times. We see customers go single-org with environment-specific source aliases (prod-customers vs staging-customers).

Per-business-unit

When

Two BUs run independently but use the same compliance posture (HIPAA blueprint, same trust thresholds, same mask defaults).

How

Separate orgs on the control plane. Each BU operator manages its own proxies, agents, contracts, and audit retention. The console isolates everything via RLS.

Tradeoffs

Operationally clean. The BUs cannot see each other's data. The downside: shared policy authoring requires duplicate work. If you want shared policy plus separate audit logs, consider per-environment within one org instead.

Failover (active-passive)

When

You need 99.95%+ uptime on the data path and your orchestrator does not provide multi-AZ replicas natively.

How

Two proxies behind a load balancer. ALB or NLB, target group with healthcheck on /healthz. Each proxy has the same license key (or two licenses pointing at the same org). Drain one, upgrade, swap.

Tradeoffs

Standard active-passive. Audit rows from both proxies land in the same control plane org and are distinguished by proxy_id. Token store: point both proxies at the same DATADAM_TOKEN_STORE_URL so tokenize remains consistent across the failover.

Per-region active-active

When

You need 99.99%+ uptime and your agents are distributed across regions.

How

Multiple proxies per region behind region-local load balancers. Latency-routing via DNS sends agents to the closest region. Each region has its own token store DB (regional locality of reversible tokens).

Tradeoffs

Hardest to operate; required only for the strictest uptime contracts. The control plane is the single point of failure for sync, but proxies fail open on sync failure (last-good policy continues to apply) so a control plane outage degrades to "no new policy changes" rather than "no governance."

Sharp edges

Things to know before you split the deployment.

The proxy architecture is deliberate; some choices have downstream operational consequences. Naming them here so your platform team knows what to expect.

Source credentials are per-proxy, by design

There is no central credential vault. Each proxy reads its own env vars or secrets-manager values. This is the security stake: a control plane compromise cannot reach your databases because the control plane never holds credentials. The tradeoff: you provision credentials once per proxy. Use your existing secrets-manager workflow (External Secrets Operator, Sealed Secrets, Vault, AWS Secrets Manager) and it scales linearly with proxy count.

Token store is per-proxy unless you share it

Tokenize mode mints reversible tokens stored in YOUR Postgres at DATADAM_TOKEN_STORE_URL. Default: each proxy host has its own token store, so tokens minted by proxy A do not detokenize on proxy B. If you need cross-proxy tokenization (which most multi-proxy customers do), point every proxy at the same shared Postgres for the token store.

Audit rows are per-org, not per-proxy

Every audit row carries the proxy_id and org_id. Queries by org return data from every proxy in that org. Queries by proxy_id narrow to one. The retention cron operates per-org. The SIEM sink is per-org.

Proxy heartbeat lives on the control plane

Every proxy emits a heartbeat on every /sync. The console /onboard/proxy page lists every proxy with its last heartbeat, OCR engine name (Phase 5J), version, and revocation status. A stale proxy (no heartbeat in 10+ minutes) shows an "idle" badge so operators see fleet health at a glance.

Mixed-version fleets are first-class

You can run proxy v0.2.0 and v0.3.0 against the same control plane simultaneously. The control plane sends both proxies the same /sync/keys payload; older proxies ignore fields they do not understand. New features that require new proxy behavior only activate once every proxy is on the supported version. The console flags older proxies via the proxy_outdated banner.

Scale

How much can one proxy handle?

Throughput is rarely the reason customers deploy multiple proxies. Here is the actual scale envelope and what we recommend when you do hit it.

A single proxy comfortably serves hundreds of millions of governed requests per month on a 2-vCPU/4-GB pod.

You usually do not need a second proxy for throughput. The reasons to run multiple proxies are posture: failover, regional latency, regulatory boundary, business-unit isolation, blast-radius minimization.

When throughput does become a concern (very high-concurrency LLM workloads especially), scale vertically first (more CPU and RAM on one pod), then horizontally (multiple proxies behind a load balancer). Both shapes work; vertical is operationally simpler.

Architecture review?

We work through deployment shape with every team that evaluates DataDam before they pick one. Email hello@mydatadam.com and we will schedule a working session with your platform team.