# usertools-ai/usertrust architecture

> Architecture diagram of the GitHub repository usertools-ai/usertrust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/usertools-ai/usertrust
- Repository: https://github.com/usertools-ai/usertrust

## Overview

usertrust is a financial-governance SDK for AI-agent LLM calls: it applies policy and budget controls, meters usage, settles spend, and returns an auditable receipt. Its central flow is a wrapped provider request through governance and a two-phase ledger lifecycle, followed by audit recording. The repository also includes policy and safety controls, external verification and anchoring, integrations, an operator UI, and a tenant server. Some subsystem links are based on README descriptions because their implementation files were not sampled.

Main entry points: [`packages/core/src/govern.ts`](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/govern.ts) (Governed SDK), [`packages/core/src/cli/main.ts`](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/cli/main.ts) (Operator CLI), [`packages/core/src/ledger/engine.ts`](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/ledger/engine.ts) (Two-phase ledger), [`packages/ui/src/server/server.ts`](https://github.com/usertools-ai/usertrust/blob/master/packages/ui/src/server/server.ts) (Dashboard server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Governance runtime"]
  node_sdk["Governed SDK<br/>[govern.ts]"]
  node_policy["Policy engine<br/>[gate.ts]"]
  node_pii["PII detection<br/>[pii.ts]"]
  node_resilience["Provider breakers<br/>[circuit.ts]"]
  node_proxy["Routing proxy<br/>[proxy.ts]"]
  node_patterns["Pattern memory<br/>[patterns.ts]"]
end

subgraph group_accounting["Spend and audit"]
  node_budget["Budget context<br/>[context.ts]"]
  node_ledger["Two-phase ledger<br/>[engine.ts]"]
  node_tbclient["Ledger client<br/>[client.ts]"]
  node_pricing["Usage pricing<br/>[pricing.ts]"]
  node_audit[("Audit chain<br/>[chain.ts]")]
  node_anchor["External anchoring<br/>[anchor.ts]"]
end

subgraph group_interfaces["Integrations and tools"]
  node_acs["Provider adapters<br/>[composite.ts]"]
  node_openclaw["OpenClaw governor<br/>[stream-governor.ts]"]
  node_server["Tenant API<br/>[server.ts]"]
  node_cli["Operator CLI<br/>[main.ts]"]
end

subgraph group_verification["Verification and visibility"]
  node_verify["Receipt verifier<br/>[receipt-verify.ts]"]
  node_ui["Ledger dashboard<br/>[app.tsx]"]
  node_ui_server["Dashboard server<br/>[server.ts]"]
  node_receipt_site["Receipt pages<br/>[route.ts]"]
end

node_developer(("Agent developer"))
node_provider{{"LLM provider"}}
node_tigerbeetle[("TigerBeetle")]

node_developer -->|"wraps client"| node_sdk
node_sdk -->|"checks policy"| node_policy
node_sdk -->|"screens prompts"| node_pii
node_sdk -->|"enforces budget"| node_budget
node_sdk -->|"calls provider"| node_provider
node_sdk -->|"guards requests"| node_resilience
node_sdk -->|"records spend"| node_ledger
node_ledger -->|"creates transfers"| node_tbclient
node_tbclient -->|"submits transfers"| node_tigerbeetle
node_sdk -.->|"prices usage"| node_pricing
node_ledger -.->|"records events"| node_audit
node_sdk -.->|"learns routing"| node_patterns
node_proxy -.->|"uses learned routing"| node_patterns
node_provider -->|"returns response"| node_sdk
node_sdk -->|"returns receipt"| node_developer
node_cli -.->|"verifies chain"| node_audit
node_cli -->|"manages anchors"| node_anchor
node_anchor -.->|"anchors externally"| node_tigerbeetle
node_acs -.->|"adapts provider"| node_sdk
node_openclaw -.->|"governs streams"| node_sdk
node_developer -.->|"sends API requests"| node_server
node_server -->|"authorizes and settles"| node_sdk
node_ui_server -.->|"reads vault"| node_audit
node_ui_server -.->|"serves dashboard data"| node_ui
node_cli -.->|"opens dashboard"| node_ui_server
node_receipt_site -.->|"resolves verification"| node_verify
node_developer -.->|"submits receipt"| node_verify

click node_sdk "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/govern.ts"
click node_policy "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/policy/gate.ts"
click node_pii "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/policy/pii.ts"
click node_resilience "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/resilience/circuit.ts"
click node_proxy "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/proxy.ts"
click node_patterns "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/memory/patterns.ts"
click node_budget "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/budget/context.ts"
click node_ledger "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/ledger/engine.ts"
click node_tbclient "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/ledger/client.ts"
click node_pricing "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/ledger/pricing.ts"
click node_audit "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/audit/chain.ts"
click node_anchor "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/audit/anchor.ts"
click node_acs "https://github.com/usertools-ai/usertrust/blob/master/packages/acs-adapter/src/composite.ts"
click node_openclaw "https://github.com/usertools-ai/usertrust/blob/master/packages/openclaw/src/stream-governor.ts"
click node_server "https://github.com/usertools-ai/usertrust/blob/master/packages/server/src/server.ts"
click node_cli "https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/cli/main.ts"
click node_verify "https://github.com/usertools-ai/usertrust/blob/master/packages/verify/src/receipt-verify.ts"
click node_ui "https://github.com/usertools-ai/usertrust/blob/master/packages/ui/src/app/app.tsx"
click node_ui_server "https://github.com/usertools-ai/usertrust/blob/master/packages/ui/src/server/server.ts"
click node_receipt_site "https://github.com/usertools-ai/usertrust/blob/master/site/app/r/%5BreceiptId%5D/receipt.json/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_policy,node_pii,node_resilience,node_proxy,node_patterns toneBlue
class node_budget,node_ledger,node_tbclient,node_pricing,node_audit,node_anchor,node_tigerbeetle toneAmber
class node_acs,node_openclaw,node_server,node_cli toneMint
class node_verify,node_ui,node_ui_server,node_receipt_site toneRose
class node_developer,node_provider toneIndigo
```

## Components

### Governance runtime

- [Governed SDK](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/govern.ts): `packages/core/src/govern.ts`
- [Policy engine](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/policy/gate.ts): `packages/core/src/policy/gate.ts`
- [PII detection](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/policy/pii.ts): `packages/core/src/policy/pii.ts`
- [Provider breakers](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/resilience/circuit.ts): `packages/core/src/resilience/circuit.ts`
- [Routing proxy](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/proxy.ts): `packages/core/src/proxy.ts`
- [Pattern memory](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/memory/patterns.ts): `packages/core/src/memory/patterns.ts`

### Spend and audit

- [Budget context](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/budget/context.ts): `packages/core/src/budget/context.ts`
- [Two-phase ledger](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/ledger/engine.ts): `packages/core/src/ledger/engine.ts`
- [Ledger client](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/ledger/client.ts): `packages/core/src/ledger/client.ts`
- [Usage pricing](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/ledger/pricing.ts): `packages/core/src/ledger/pricing.ts`
- [Audit chain](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/audit/chain.ts): `packages/core/src/audit/chain.ts`
- [External anchoring](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/audit/anchor.ts): `packages/core/src/audit/anchor.ts`

### Integrations and tools

- [Provider adapters](https://github.com/usertools-ai/usertrust/blob/master/packages/acs-adapter/src/composite.ts): `packages/acs-adapter/src/composite.ts`
- [OpenClaw governor](https://github.com/usertools-ai/usertrust/blob/master/packages/openclaw/src/stream-governor.ts): `packages/openclaw/src/stream-governor.ts`
- [Tenant API](https://github.com/usertools-ai/usertrust/blob/master/packages/server/src/server.ts): `packages/server/src/server.ts`
- [Operator CLI](https://github.com/usertools-ai/usertrust/blob/master/packages/core/src/cli/main.ts): `packages/core/src/cli/main.ts`

### Verification and visibility

- [Receipt verifier](https://github.com/usertools-ai/usertrust/blob/master/packages/verify/src/receipt-verify.ts): `packages/verify/src/receipt-verify.ts`
- [Ledger dashboard](https://github.com/usertools-ai/usertrust/blob/master/packages/ui/src/app/app.tsx): `packages/ui/src/app/app.tsx`
- [Dashboard server](https://github.com/usertools-ai/usertrust/blob/master/packages/ui/src/server/server.ts): `packages/ui/src/server/server.ts`
- [Receipt pages](https://github.com/usertools-ai/usertrust/blob/master/site/app/r/%5BreceiptId%5D/receipt.json/route.ts): `site/app/r/[receiptId]/receipt.json/route.ts`

### Other components

- **Agent developer**
- **LLM provider**
- **TigerBeetle**

## Connections

- Agent developer → Governed SDK: wraps client (evidence: `README.md`)
- Governed SDK → Policy engine: checks policy (evidence: `README.md`)
- Governed SDK → PII detection: screens prompts (evidence: `README.md`)
- Governed SDK → Budget context: enforces budget (evidence: `README.md`)
- Governed SDK → LLM provider: calls provider (evidence: `README.md`)
- Governed SDK → Provider breakers: guards requests (evidence: `README.md`)
- Governed SDK → Two-phase ledger: records spend (evidence: `README.md`)
- Two-phase ledger → Ledger client: creates transfers (evidence: `packages/core/src/ledger/engine.ts`)
- Ledger client → TigerBeetle: submits transfers (evidence: `packages/core/src/ledger/client.ts`)
- Governed SDK → Usage pricing: prices usage
- Two-phase ledger → Audit chain: records events
- Governed SDK → Pattern memory: learns routing (evidence: `README.md`)
- Routing proxy → Pattern memory: uses learned routing (evidence: `README.md`)
- LLM provider → Governed SDK: returns response (evidence: `README.md`)
- Governed SDK → Agent developer: returns receipt (evidence: `README.md`)
- Operator CLI → Audit chain: verifies chain (evidence: `README.md`)
- Operator CLI → External anchoring: manages anchors (evidence: `README.md`)
- External anchoring → TigerBeetle: anchors externally
- Provider adapters → Governed SDK: adapts provider
- OpenClaw governor → Governed SDK: governs streams
- Agent developer → Tenant API: sends API requests
- Tenant API → Governed SDK: authorizes and settles (evidence: `packages/server/src/server.ts`)
- Dashboard server → Audit chain: reads vault (evidence: `packages/ui/src/server/server.ts`)
- Dashboard server → Ledger dashboard: serves dashboard data
- Operator CLI → Dashboard server: opens dashboard
- Receipt pages → Receipt verifier: resolves verification (evidence: `site/app/r/[receiptId]/receipt.json/route.ts`)
- Agent developer → Receipt verifier: submits receipt (evidence: `README.md`)
