Parix architecture

Parix separates what you manage in the product from where TigerBeetle runs. That split is why you use stable Parix database IDs, why every ledger call goes through a gateway, and why create, upgrade, backup, and similar work finish asynchronously.

System at a glance

You and your apps talk only to Parix—the dashboard (control plane) and the versioned API (gateway). TigerBeetle replicas stay private. There is no customer path that connects straight to a replica protocol endpoint.

Control plane

The control plane is the product surface and system of record for account and database lifecycle. It owns:

• sign-in, organizations, membership, roles, and API keys
• the create catalog: plans, providers, regions, sizes, storage options, and prices your organization may use
• durable records for databases, jobs, backups, CDC configuration, and billing
• placement of Developer databases on shared capacity
• long-running work for provisioning, deletion, upgrades, backups, restores, and configuration
• history and notification views where the product exposes them
• storage of backup and import artifacts when those features apply

Use the control plane to create and operate databases, issue credentials, and watch job status. Use the gateway API for TigerBeetle account and transfer traffic. Import is a second create path that stages replica files before provisioning.

Data plane

The data plane is the private environment where TigerBeetle runs for your plan:

• Developer — a logical database on a Parix-operated shared cell (multi-tenant capacity). For learning and prototypes; no production SLA.
• Dedicated / Production — an isolated TigerBeetle deployment. Dedicated covers single-node plans; Production covers multi-replica HA options (for example Production HA and Production 6). Exact topology and features come from the create catalog.

Parix places and operates that infrastructure. You always use the public Parix API and database ID; Parix handles placement and private routing. Available providers and regions come from the create catalog for your organization.

Shared Developer databases

A Developer database is a logical tenant. Many tenants can share one cell; Parix maps each logical database to its own namespace and route.

When you create a Developer database:

1. Parix checks your user, organization, billing, and whether your organization can create Developer databases.
2. It finds healthy shared capacity in the selected pool.
3. It reserves capacity while creation finishes.
4. It activates the logical database and its gateway route.

The public database ID stays stable even if Parix later moves the backing placement. You always call Parix with that ID; you do not configure placement or private routing yourself.

Dedicated and Production databases

Dedicated and Production plans get isolated deployments.

Creation is asynchronous:

1. Parix validates billing and the full catalog selection.
2. It records the database and queues a provisioning job.
3. The job provisions infrastructure until the database is Ready, or shows Error if setup fails.

The dashboard shows states such as Provisioning, Ready, and Error. For automations, poll job and database status fields until work finishes—do not treat a single HTTP success as completion. See Database statuses.

How a ledger request runs

Every TigerBeetle operation follows the same product path:

1. Your client calls a versioned Parix API endpoint with the database ID and a scoped credential.
2. Parix authenticates the request and checks organization, database scope, and read/write permission.
3. Plan quotas and rate limits apply when the plan requires them.
4. Parix resolves the current route for that database (shared cell or dedicated).
5. Private connectivity carries the operation to the data plane.
6. TigerBeetle executes the operation.
7. Parix returns a structured success, per-item write results, or a structured error.

There is no direct-connect product mode. Replica addresses and native protocol endpoints are not a self-service surface on any plan.

Change Data Capture (CDC)

CDC is separate from the interactive query and write path. Where the plan supports it (typically Dedicated and Production), databases can stream change events to destinations you configure.

Product options include managed HTTPS webhooks and, when offered, a direct message-queue destination. Configuration is saved before apply work starts; if apply does not start, a pending configuration can remain visible until you resolve it.

Use webhook or destination history for delivery attempts. Use the CDC configuration and job status as the source of truth for whether apply completed.

Asynchronous workflows

Infrastructure changes are not finished inside a single dashboard click. The product validates and records intent, then runs durable work. That model covers:

• isolated database provisioning and deletion
• size, storage, topology, and parameter changes
• TigerBeetle version upgrades
• CDC apply
• manual and scheduled backups
• in-place restore

An accepted request can mean:

1. Rejected before work is queued — authorization, billing, catalog, validation, or lifecycle checks failed.
2. Queued — work is not finished; treat the database as still in progress.
3. Completed or failed — after provisioning and related steps finish.

Automations should read returned success flags and job or database status, not assume HTTP 200 alone means the infrastructure change is done.

History and retention

Some dashboard history views keep only recent events (for example organization audit, notifications, cluster changes, and CDC webhook history). They can lag primary job state.

Treat the provisioning job, backup job, CDC configuration, or database status as the completion signal. Use history for context after the fact.

Failure boundaries

Architecture shapes what you should expect when something fails:

• a database record can exist even if background work never started
• deletion or teardown can be partial if a workflow stops mid-way
• shared placement can refuse creates when no healthy cell has capacity
• restore may be unavailable even when backups were supported earlier

When you escalate, include database ID, name, organization, plan, provider, region, job or database status, and timestamps.

Security boundary

From a product perspective, this architecture provides:

• authenticated control-plane and database operations
• organization- and database-scoped API keys
• private routing to TigerBeetle (no public replica endpoints)
• shared-namespace isolation or isolated deployments according to plan
• rate and quota enforcement at the gateway

See Security for credential handling and your responsibilities.

Continue with Dashboard tour, Connecting overview, or Database statuses.