Architecture / System design

Architecture

How Veefore is built, why it is built that way, and where each decision is recorded.

#The shape

textCopy
         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.

#Packages

→ 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

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.

#Also here