Production architecture

This page covers two audiences. SaaS customers integrating against a hosted Ledgix Vault only need the first section. Enterprise customers self-hosting Vault should read all three.

Integration requirements (SaaS customers)

Most customers do not need Ledgix hosting details. You do need a clean picture of what your own application must have before it can integrate safely.

1. 01

   A Vault URL per environment

   Use the correct Ledgix URL for development, staging, and production. Do not mix API keys across environments.
2. 02

   A tenant API key

   Create the key in the customer dashboard and store it in your own secret-management flow. Ledgix shows the raw key only once.
3. 03

   Outbound HTTPS access

   Your application, worker, or server-side route must be able to reach the Vault URL over TLS.
4. 04

   One protected tool boundary

   Decide whether your first rollout will call the protected service directly after approval or send the token to an optional gateway in front of that service.

Recommended integration shape

Customer responsibilities

• store LEDGIX_VAULT_API_KEY securely in your own environment
• keep LEDGIX_VAULT_URL aligned with the environment you are deploying
• make sure server-side code, workers, and background jobs use the same customer settings
• decide who owns manual review and notification routing before going live

Optional gateway decision

You can start without a gateway if the protected action is simple and your application owns the full execution path. Add a gateway when:

• more than one service can trigger the same sensitive action
• you want the protected service to require a Ledgix token centrally
• you need a clean boundary between approval and execution

Go-live checklist

• The application can reach the Vault URL from every runtime that performs the protected action.
• The correct API key is present in that runtime.
• A policy source has already been uploaded for the first tool you are guarding.
• Reviewers know where pending requests appear and how Slack or email notifications are routed.
• The team has tested at least one approved and one blocked or paused request before production traffic.

Common integration failures

• Wrong Vault URL for the environment.
• Expired, deleted, or misplaced API key.
• Policy content uploaded after the team started testing, which makes early results look inconsistent.
• Threshold and notification settings left at defaults without deciding who handles review.

Runtime architecture (self-hosted enterprise)

A Ledgix production deployment is two services, one TLS ingress, and a backing data plane.

Two-database model

Ledgix deliberately splits control-plane state from tenant state.

• Control plane (Supabase Postgres): memberships, tenant metadata, clients table. clients.tenant_secret_ref points at an AWS Secrets Manager entry — the row itself never contains tenant DB passwords, ledger transport keys, or Confluence tokens.
• Tenant databases (one Postgres per tenant): policies (with pgvector embeddings) and the tenant's ledger. Credentials come from Secrets Manager at runtime.

This split is what makes tenant isolation real. A breach of the control plane does not expose tenant policy content or ledger entries.

A-JWT signing

Approval tokens are signed with Ed25519 (EdDSA). Vault publishes the public key at GET /.well-known/jwks.json.

Claims embedded in every A-JWT:

Merkle ledger and anchoring

Every decision is persisted to the tenant's ledger on DB commit. A background anchor loop sequences accepted events into an append-only Merkle tree, signs the checkpoint, and exports it to S3.

• Durability is synchronous on DB commit.
• Sequencing and anchoring are asynchronous — they run on the VAULT_LEDGER_ANCHOR_BACKFILL_INTERVAL_SECONDS loop (default 30s).
• The anchor bucket must have versioning enabled. Object lock is recommended but not required.

Async clearance queue

POST /request-clearance is queue-backed so slow judge calls cannot block the HTTP path.

• Default: in-memory queue (VAULT_CLEARANCE_ASYNC_WORKERS, VAULT_CLEARANCE_ASYNC_QUEUE_SIZE).
• Production: point VAULT_CLEARANCE_SQS_QUEUE_URL at an SQS FIFO queue. VAULT_CLEARANCE_SQS_FIFO_GROUP_SHARDS controls parallelism across FIFO groups.

Self-hosted configuration reference

Vault reads configuration from environment variables. When AWS_SECRET_NAME is set, Vault pulls the named Secrets Manager bundle on startup and merges it over the environment.

Vault — transport and signing

Vault — data plane

Vault — clearance queue and rate limiting

Vault — ledger anchoring

Vault — judge integration

llm-judge — configuration

Deploy via docker-compose

The reference stack lives in deployments/docker-compose.yml. It launches vault and llm_judge on a private Docker network with Caddy as the TLS ingress.

docker compose --env-file .env.prod up -d --build

.env.prod only needs non-sensitive values — primarily VAULT_AWS_SECRET_NAME, JUDGE_AWS_SECRET_NAME, TENANT_SECRET_PREFIX, and AWS_REGION. Each container fetches its secret bundle from AWS Secrets Manager on startup.

For brownfield enterprise rollouts onto pre-existing infrastructure, follow deployments/EXISTING_INFRA_ENTERPRISE_ROLLOUT.md rather than the Terraform stack in deployments/terraform/ (which is greenfield only).