---
title: Architecture
description: How Veefore is built, why it is built that way, and where each decision is recorded.
label: Overview
---

## The shape

```text
         people, CLI, CI                          agents
                │                                   │
        ┌───────▼────────┐                 ┌────────▼────────┐
        │ Control plane  │                 │     Gateway     │
        │   /v1/*        │                 │  /gateway/v1/*  │
        │                │                 │                 │
        │ management     │                 │ enforcement     │
        └───────┬────────┘                 └────────┬────────┘
                │          ┌──────────┐             │
                └──────────▶ Postgres ◀─────────────┘
                           └─────▲────┘
                                 │
                        ┌────────┴────────┐
                        │ Worker          │
                        │ queues, rollups │
                        └─────────────────┘
```

Two request-serving processes, one worker, one database. The split between the
planes is a security boundary, not a packaging choice:
[Gateway architecture](/architecture/adr/0002-gateway-architecture).

## Packages

| | |
| --- | --- |
| `packages/types` | The shared vocabulary: enums, permissions, policy IR, error codes, event types |
| `packages/common` | Config, logging, redaction, crypto, pagination, resilience, telemetry |
| `packages/db` | The driver, migrations, repositories, the schema catalogue |
| `packages/identity` | Key handling and JWS |
| `packages/policy` | The evaluator, schema, field descriptors, templates, diff, Rego export |
| `services/core` | Every domain service: agents, policy, delegation, risk, approval, credentials, audit, enforcement |
| `apps/control-plane` | The management HTTP surface, plus the worker |
| `gateway` | The enforcement HTTP surface |
| `apps/console` | The browser app |
| `packages/sdk-js`, `packages/sdk-python` | Client SDKs |
| `packages/cli` | The `veefore` command |
| `docs` | This site |

[→ Repository layout](/architecture/repository-layout)

## Design principles

**Prefer structural guarantees to configured ones.** An agent belongs to one
environment, so a staging identity cannot act in production — not because a rule
forbids it, but because the agent is not there. Configuration drifts; structure
does not.

**Order the pipeline so refusals come before side effects.** The credential
broker is stage 10, after everything that can refuse. That is what makes
`BLOCK` mean blocked rather than "blocked, but the secret went out anyway".

**Fail closed, always.** No flag turns an error into an allow.
[→ Fail closed](/secure/fail-closed)

**Make determinism and totality non-negotiable in the evaluator.** The same
input always yields the same output, and no operator can throw. A policy engine
that can throw is not something you put in front of production.

**Refuse rather than clamp.** A delegation exceeding its parent is refused, not
silently narrowed. Silent clamping means the caller believes it has authority it
does not have.

**Generate documentation from the source of truth.** The reference pages are
built from the registries the product itself reads, so they cannot drift.

**Enforce the boundaries in CI.** `scope:audit` fails the build if an
out-of-scope feature appears. `quality:audit` fails it on mock data, hardcoded
metrics, unconditional authorization or fail-open error handling. A principle
without a gate is a preference.

## Decision records

Thirteen ADRs, each with the context, the decision, the alternatives considered
and the consequences accepted.

| | |
| --- | --- |
| [0001](/architecture/adr/0001-scope-boundaries) | Scope boundaries |
| [0002](/architecture/adr/0002-gateway-architecture) | Gateway architecture |
| [0003](/architecture/adr/0003-policy-engine) | Policy engine — a TypeScript IR, not OPA |
| [0004](/architecture/adr/0004-delegation-semantics) | Delegation semantics |
| [0005](/architecture/adr/0005-identity-model) | Identity model |
| [0006](/architecture/adr/0006-passport-format) | Passport format |
| [0007](/architecture/adr/0007-trust-evidence) | Trust evidence |
| [0008](/architecture/adr/0008-credential-broker) | Credential broker |
| [0009](/architecture/adr/0009-mcp-architecture) | MCP architecture |
| [0010](/architecture/adr/0010-a2a-architecture) | A2A architecture |
| [0011](/architecture/adr/0011-tenant-isolation) | Tenant isolation |
| [0012](/architecture/adr/0012-audit-architecture) | Audit architecture |
| [0013](/architecture/adr/0013-deployment-model) | Deployment model |

## Also here

:::cards

:::card Request path | /architecture/request-path
One protected action, from the agent to the downstream.
:::

:::card Data model | /architecture/data-model
Tables, relationships, and where amounts are allowed.
:::

:::card Testing strategy | /architecture/testing-strategy
Seven suites, five smoke tests, two audits, and what each proves.
:::

:::card Changelog | /architecture/changelog
What shipped.
:::

:::