Architecture Overview

For CTOs and senior engineers evaluating this engine for production use.

High-Level Flow

      graph TD
      Integrator[Integrator Backend] -->|HMAC Requests| API[API Edge]
      API --> Core[Core Engine]
      Core --> Storage[Event Storage]
      subgraph Cloud[Clearhold Cloud]
      API
      Core
      Storage
      end
      style Integrator fill:#1e1e2e,stroke:#a5b4fc
      style API fill:#1e1e2e,stroke:#6366f1
      style Core fill:#1e1e2e,stroke:#6366f1
      style Storage fill:#1e1e2e,stroke:#6366f1

Event-Driven Model

Every API call produces events. Events are immutable. State is projected from events.

json 
{
  "event_type": "DISPUTE_RESOLVED",
  "entity_type": "dispute",
  "entity_id": "dsp_abc123",
  "escrow_id": "esc_xyz789",
  "previous_state": "EVIDENCE_LOCKED",
  "new_state": "RESOLVED",
  "actor_id": "int_operator",
  "actor_role": "operator",
  "metadata": {
    "decision": "SPLIT",
    "final_ratio": { "client": 0.4, "contractor": 0.6 }
  },
  "timestamp": "2025-01-15T14:30:00Z"
}

Deterministic Guarantees

Guarantee Implementation
Same input → Same output Pure functions in core, no side effects
Time injection All time values passed as parameters, never Date.now()
Reproducible decisions Decision engine uses fixed weights, all inputs recorded
Audit replay Any decision can be re-calculated from stored inputs

State Machine Enforcement

Invalid state transitions are rejected at the API level. The engine never enters an inconsistent state.

Escrow States

      stateDiagram-v2
      [*] --> CREATED
      CREATED --> FUNDED
      FUNDED --> IN_PROGRESS
      FUNDED --> CANCELLED
      IN_PROGRESS --> DELIVERED
      IN_PROGRESS --> DISPUTED
      DELIVERED --> COMPLETED
      DISPUTED --> RESOLVED
      DISPUTED --> CANCELLED
      RESOLVED --> [*]
      COMPLETED --> [*]
      CANCELLED --> [*]

Dispute States

      stateDiagram-v2
      [*] --> OPEN
      OPEN --> EVIDENCE_LOCKED
      EVIDENCE_LOCKED --> RESOLVED
      RESOLVED --> [*]

What Happens on Dispute

  1. Dispute opened — Escrow transitions to DISPUTED
  2. Evidence window — Both parties submit references (72h default)
  3. Evidence locked — No more submissions accepted
  4. Recommendation generated — Decision engine produces suggestion
  5. Operator decision — Final ratio applied (within ±30% of recommendation)
  6. Webhook dispatched — Integrator notified of resolution

No Hidden Components

  • No UI layer
  • No dashboard
  • No background jobs you don't control
  • No external dependencies you can't audit

The engine is the API. The API is the engine.

Next: Decision Engine →