Architecture

How requests flow through Verdict from actor to decision and audit.

Request flow

  Actor (AI / Human / Bot / Script)
       │
       │  POST /authorize_action
       │  { actor_id, action_type, metadata }
       ▼
  ┌─────────────────────────────────────────────────────────┐
  │  Verdict API                                             │
  │  ┌─────────────┐    ┌──────────────┐    ┌─────────────┐ │
  │  │  Registry   │───►│   Policy     │───►│  Audit Log  │ │
  │  │ (optional)  │    │   Engine     │    │ (hash chain)│ │
  │  └─────────────┘    └──────┬───────┘    └──────┬──────┘ │
  │         │                  │                    │       │
  │         │                  │                    │       │
  │         │         ┌────────┴────────┐           │       │
  │         │         ▼                 ▼           ▼       │
  │         │   APPROVED           ESCALATED    Every       │
  │         │   + PoA (Ed25519)    + request_id  decision   │
  │         │                      → Queue       logged     │
  │         │                      → Webhook                 │
  │         │                                               │
  │         └──► action not in allowed_actions → ESCALATED   │
  └─────────────────────────────────────────────────────────┘
       │
       │  Human: POST /approve_action { request_id, approved }
       │  → Audit updated, escalation_latency_ms returned
       ▼
  Backend (refund/email/CRM API) verifies PoA via POST /poa/verify

Components

Registry (optional): Per-actor allowed_actions. If set, requests for actions not in the list are ESCALATED.
Policy engine: Built-in Python rules or OPA/Rego when OPA_URL is set. Deterministic; no LLM.
Audit log: Append-only, hash-chained. Stored in SQLite or Postgres. Export: CSV, PDF, VC, incident template, AI Action Authorization Report.
Escalation queue: ESCALATED requests wait for human approve/deny. Optional Slack/Teams webhook with approval link.
Proof of Authority: Ed25519 signing of APPROVED decisions; backends verify via /poa/verify.

Environments

Use VERDICT_ENV (development | staging | production) to separate config and to drive status page and strictness. Rate limiting and webhook events are configurable per environment.