Diagram gallery

Three views of the same system: what happens in what order, how data flows, and how the components depend on each other.

Sequence diagrams

The canonical end-to-end sequence, an audit that produces evidence, followed by an observe that composes trust, identity and the registry. Both are real request flows in api/routes.py.

sequenceDiagram
  autonumber
  participant C as Client
  participant API as api/routes.py
  participant RT as ProviderRouter
  participant PA as Provider adapter
  participant EE as EvidenceEngine
  participant TE as TrustEngine
  participant IE as IdentityEngine
  participant RG as PersistentAgentRegistry
  C->>API: POST /audit/conversation
  API->>RT: route(task, instructions, input)
  RT->>PA: audit()
  PA-->>RT: ProviderResult (safe)
  RT-->>API: RoutingResult
  API->>EE: build(routed, operation)
  EE-->>API: EvidenceEnvelope (+receipt +provenance)
  API-->>C: audit response (+ envelope/receipt/provenance)
  C->>API: POST /registry/observe {evidence}
  API->>TE: assess(envelope)
  TE-->>API: TrustAssessment
  API->>IE: identify(envelope, trust)
  IE-->>API: AgentIdentity
  API->>RG: register/update identity·profile·passport·reputation
  RG-->>API: AgentRegistryEntry
  API-->>C: registry entry

End-to-end sequence: audit → evidence, then observe → trust → identity → registry. Source: api/routes.py.

Per-capability sequences are on their lifecycle pages: audit, evidence, trust, registry.

Data-flow diagrams

One EvidenceEnvelope is the single source that fans out to every capability. Nothing re-runs a model; each engine reads structural fields from the envelope or from an upstream assessment.

flowchart LR
  EV["EvidenceEnvelope"] --> CO["ComplianceEngine"]
  EV --> RI["RiskEngine"]
  EV --> QU["QualityEngine"]
  CO --> TR["TrustEngine → TrustAssessment"]
  RI --> TR
  QU --> TR
  EV --> ID["IdentityEngine → AgentIdentity"]
  TR --> ID
  ID --> TP["AgentTrustScoreEngine → AgentTrustProfile"]
  TR --> TP
  ID --> PA["PassportEngine → AgentPassport"]
  TP --> PA
  ID --> RE["ReputationEngine → AgentReputation"]
  TP --> RE
  PA --> RE
  ID --> RG["PersistentAgentRegistry"]
  TP --> RG
  PA --> RG
  RE --> RG
  RG --> CC["ControlCenterEngine → overview"]
  EV --> SI["SignalEngine → SignalExport"]
  TR --> SI
  ID --> SI
  RE --> SI

Data-flow: one evidence envelope fans out to every capability. Source: composition in api/routes.py.

Component interaction diagrams

The dependency structure: a thin transport layer over stateless engines, one stateful registry on a swappable store, and the provider layer. The key reuse edge is TrustEngine → {Compliance, Risk, Quality}: trust is a composition, never a re-implementation.

flowchart TB
  subgraph transport["Transport, api/routes.py (thin, no business logic)"]
    H["endpoint handlers"]
  end
  subgraph engines["Stateless engines (module singletons)"]
    direction LR
    ee["EvidenceEngine"]
    ce["ComplianceEngine"]
    re["RiskEngine"]
    qe["QualityEngine"]
    te["TrustEngine"]
    ie["IdentityEngine"]
    pe["PassportEngine"]
    rpe["ReputationEngine"]
    se["SignalEngine"]
    cce["ControlCenterEngine"]
  end
  subgraph stateful["Stateful"]
    reg["PersistentAgentRegistry"]
    st["PersistenceStore (Memory / JSON)"]
  end
  subgraph provider["Provider layer"]
    rt["ProviderRouter"]
    cfg["ProviderConfig (env, presence-only)"]
    ad["adapters: mock / gemini / openai / anthropic"]
  end
  H --> ee & ce & re & qe & te & ie & pe & rpe & se & cce
  te --> ce & re & qe
  H --> rt --> ad
  rt --> cfg
  H --> reg --> st
  cce --> reg

Component interaction, transport → stateless engines → stateful registry; TrustEngine reuses the three sub-engines. Source: src/vailidator/.

How to read dependency direction. Transport depends on engines; engines depend only on the domain objects they compose (and, for trust, on the three sub-engines). No engine depends on transport, and no engine writes to the registry except through the registry's own API, that is the architectural boundary that keeps every capability independently testable.