Architecture · Overview

Five planes. Fourteen services.

A technical walk-through of Veridra's backend: the planes, the services, and how evidence flows between them.

Five control planes, each with a single responsibility and a hardened boundary between it and the others. Any plane can be scaled, upgraded, or restarted without the adjacent planes noticing.

How the planes fit together

Services inside a plane speak over mTLS with SPIFFE/SPIRE-issued identities. Services across planes speak only through narrow, versioned gRPC contracts. No shell, support tool, or operator reaches into a tenant's signing path.

Plane 01 · Ingress

Public edge, WAF, OIDC-backed authentication, tenant routing, request-level rate limiting. Terminates TLS 1.3, then re-originates mTLS inwards. No business logic lives here.

Plane 02 · Governance

System inventory, framework crosswalks, policy-as-code (Rego), and the risk register. Source of truth for what each AI system is, what tier it sits in, and what obligations apply.

Plane 03 · Attestation

The canonicalize → sign → log → pack pipeline. Contains the signer, the KMS client, the Trillian-backed transparency log, witness co-signers, and the evidence-pack builder.

Plane 04 · Observability

Drift detectors, incident ingestion, lineage graphs, and Watch alerts. Consumes signed events from the Attestation plane; never writes back into it.

Plane 05 · Operations

Billing, tenant lifecycle, regional sharding, backup orchestration, key-rotation scheduling. Isolated from tenant data paths; it sees metadata and metering, never decision content.

The fourteen services

Each plane decomposes into services with explicit interfaces. Services have an owner, an SLO, a threat model, and a signed BOM. We keep the list small on purpose, so regulators and security reviewers can hold the whole architecture in their head.

edge-gateway — TLS termination, DDoS shaping, tenant resolution, OIDC federation. Stateless; replicated per region.
govern-api — System inventory CRUD, framework mapping, risk-register writes. Postgres with row-level tenant isolation.
policy-engine — Rego evaluator. Loads versioned policy bundles from Git, caches in-memory, emits signed enforcement records.
signer — The hot path. Accepts canonical payloads, requests KMS signatures over mTLS, returns Ed25519 signatures and receipts. Never persists plaintext keys.
kms-adapter — Unified façade over AWS KMS, Azure Key Vault, GCP KMS, HashiCorp Vault, and PKCS#11 HSMs. Enforces per-tenant key scoping.
log-writer / log-reader — Trillian front-ends. Writer appends leaves and returns inclusion proofs. Reader serves STH lookups, consistency proofs, and range queries.
witness — Signs log heads on a cadence, independent of the primary signer trust root. Sigstore-compatible.
pack-builder — Assembles evidence packs (signed PDF plus ZIP) by pulling from governance, attestation, and observability planes.
watch-detector — Streaming drift, calibration, and policy-violation detection. Writes signed incidents back to the attestation plane.
lineage-graph — Graph store linking models, datasets, policies, decisions, and incidents. Read-only to tenants; populated from signed events only.
tenant-control — Provisioning, residency pinning, sharding. Coordinates with kms-adapter on rotation and BYOK onboarding.
billing-meter — Usage metering on metadata only. Never reads decision payloads.
admin-console — Internal tooling. Break-glass actions require two-person sign-off and are themselves logged as signed events.

How evidence flows

The data flow is linear and one-directional by design. Each arrow is a place where evidence can be verified independently, and no arrow flows backward into a signed record.

SDK in tenant infra canonicalizes the decision (RFC 8785) and calls the signer with an mTLS-authenticated request.
signer requests an Ed25519 signature from kms-adapter, which relays to the tenant-scoped KMS or HSM.
signer hands the signed leaf to log-writer; Trillian returns an inclusion proof and updated signed tree head.
witness co-signs the tree head asynchronously; the co-signature is itself logged.
watch-detector consumes the signed event stream for drift and policy violations, emitting signed incidents.
On request, pack-builder assembles a regulator-admissible bundle from the signed record set; nothing in the bundle originates outside the log.

Design principle

Minimal services, maximal auditability

We deliberately kept the service count small. Every service has a named owner, a published SLO, a threat model, and a signed bill of materials. A regulator or security reviewer should be able to hold the whole architecture in their head — not chase through forty microservices to understand where evidence comes from.

Operator commitment

What Veridra operators cannot do

Veridra operators cannot view the content of your signed decisions, cannot reach into your signing path, and cannot alter records after they are logged. Break-glass actions exist for infrastructure recovery — they require two-person sign-off and are themselves logged as signed events in a separate administrative log.

Where to go next

This overview stays shallow on purpose; each plane has its own page. If you care about how a decision becomes signed proof, start with the evidence pipeline. For the key-custody story, read cryptographic signing. For third-party verifiability, read transparency log.

Request a review →Evidence pipeline →Cryptographic signing →