Engineering architecture

VerifAIer is a single deterministic evidence engine with capability layers composed above it. One completed AI operation becomes an Evidence Envelope (carrying a receipt and provenance); every downstream product, compliance, risk, quality, trust, identity, passport, reputation, registry, control center and signals, is derived from that same envelope. No layer re-runs a model, and no layer duplicates another layer's logic.

These docs are written for backend, platform, security and solution architects who need to reason about the runtime precisely. They are organized as lifecycles, schemas, mechanisms, boundaries and interaction surfaces.

flowchart TB
  subgraph CLIENTS["Surfaces"]
    EXT["Sentinel browser extension"]
    DASH["Enterprise dashboard / Control Center"]
    SDKP["Python SDK · VerifAIerClient"]
  end
  subgraph APP["FastAPI application, api/routes.py"]
    AUD["POST /api/v1/audit/conversation"]
    INTEL["/compliance /risk /quality /trust · assess"]
    IDN["/passport/issue · /reputation/assess"]
    REG["/registry/observe · /agents · /control-center/overview"]
    SIG["/signals/export"]
  end
  subgraph CORE["Evidence Engine runtime"]
    ROUTER["ProviderRouter"]
    EE["EvidenceEngine"]
    ENV["EvidenceEnvelope + Receipt + Provenance"]
  end
  subgraph PROV["Provider adapters, providers/"]
    MOCK["mock (always available)"]
    LIVE["gemini · openai · anthropic"]
  end
  subgraph INTELLIGENCE["Intelligence & identity"]
    TR["Trust / Compliance / Risk / Quality"]
    ID2["Identity → Trust Profile → Passport → Reputation"]
    STORE["PersistentAgentRegistry → PersistenceStore"]
  end
  EXT --> AUD
  DASH --> INTEL
  DASH --> IDN
  DASH --> REG
  SDKP --> APP
  AUD --> ROUTER
  ROUTER --> PROV
  ROUTER --> EE --> ENV
  ENV --> AUD
  INTEL --> TR
  IDN --> ID2
  TR --> ID2
  ID2 --> STORE
  REG --> STORE
  ENV --> SIG

What you will learn

Read in order and you will be able to answer five questions about VerifAIer without opening the source.

• What a request doesruntime lifecycle
• How evidence is formedenvelope, receipt, provenance
• Why a result repeatsdeterminism and replay
• Where a layer may not reacharchitectural boundaries
• What a provider can and cannot dorouting and failure

Each page below answers one of those and states what it does not cover. The index is the map, not the starting point.

Design invariants

Five invariants hold across the whole codebase and are enforced by the test suite. They are the fastest way to predict how any component behaves:

• Deterministic. Given the same inputs (plus an injected clock / id factory where relevant), construction and serialization are byte-for-byte identical. Ids for envelopes/receipts/provenance are uuid-based; ids for identity, passport, reputation and signals are content-derived (SHA-256 truncated), so the same agent or operation always resolves to the same id.
• Never raises on the request path. Every provider adapter self-falls-back to a safe payload; the router always yields a result; every engine accepts objects, dicts, partial or malformed input and degrades to a safe unknown/incomplete assessment rather than throwing.
• No secrets, no prompts. Nothing on the evidence path stores or emits an API key or raw prompt/input text. Configuration records key presence only; diagnostics carry safe metadata.
• Additive responses. New capabilities are added as new response fields / new endpoints; existing contracts are preserved byte-for-byte.
• Local-first. The default provider is a deterministic offline mock. Live providers run only when explicitly enabled, keyed and in live mode. Persistence defaults to in-memory.

Complete architecture index

The thirty engineering documents requested for this platform, each linked to its exact location: