# saravanx41/undolog architecture

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

- Interactive diagram: https://gitdiagram.com/saravanx41/undolog
- Repository: https://github.com/saravanx41/undolog

## Overview

undolog protects agent tool side effects: wrapped calls are classified and recorded in a per-thread append-only ledger, then a freeze and previewable rollback can restore or compensate undoable actions and report what remains. Core is framework-independent; LangGraph is an optional integration. The repository also includes a web UI and a torture/chaos suite that exercises the safety behavior. Edges reflect README statements and indexed source references; unsampled web wiring and some implementation details are left unconnected rather than inferred.

Main entry points: [`packages/core/src/undolog_core/ledger.py`](https://github.com/saravanx41/undolog/blob/main/packages/core/src/undolog_core/ledger.py) (Thread ledger), [`packages/torture/src/undolog_torture/world/__init__.py`](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/world/__init__.py) (Mock services), [`packages/torture/src/undolog_torture/demo.py`](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/demo.py) (Corruption demo), [`packages/torture/src/undolog_torture/chaos.py`](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/chaos.py) (Chaos runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Ledger engine"]
  node_ledger["Thread ledger<br/>[ledger.py]"]
  node_models[("Ledger models<br/>[models.py]")]
  node_errors["Freeze errors<br/>[exceptions.py]"]
  node_registry["Safety registry<br/>[__init__.py]"]
end

subgraph group_integrations["Integrations"]
  node_postgres["Postgres adapter"]
  node_stripe["Stripe adapter<br/>[stripe_adapter.py]"]
  node_langgraph["LangGraph plugin<br/>[adapter.py]"]
end

subgraph group_torture["Torture scenarios"]
  node_demo["Corruption demo<br/>[demo.py]"]
  node_agent["Runaway agent<br/>[agent.py]"]
  node_chaos["Chaos runner<br/>[chaos.py]"]
  node_verify["Invariant verifier<br/>[verify.py]"]
  node_faults["Fault injection<br/>[faults.py]"]
  node_executors["Rollback executors<br/>[executors.py]"]
  node_snapshot["World snapshots<br/>[snapshot.py]"]
  node_world["Mock services<br/>[__init__.py]"]
  node_crm["CRM mock<br/>[crm.py]"]
  node_stripeworld["Stripe mock<br/>[stripe.py]"]
end

subgraph group_web["Web interface"]
  node_api["Thread API<br/>[route.ts]"]
  node_entries["Entries API<br/>[route.ts]"]
  node_preview["Preview API<br/>[route.ts]"]
  node_rollback["Rollback API<br/>[route.ts]"]
  node_threadpage["Thread view<br/>[page.tsx]"]
  node_panel["Rollback panel<br/>[RollbackPanel.tsx]"]
  node_timeline["Timeline row<br/>[TimelineRow.tsx]"]
  node_webdb["Web data layer<br/>[db.ts]"]
end

node_operator(("Operator"))
node_cli["CLI<br/>[cli.py]"]
node_postgresdb[("PostgreSQL")]

node_operator -->|"runs"| node_cli
node_cli -->|"starts demo"| node_demo
node_cli -->|"starts chaos"| node_chaos
node_demo -->|"wraps calls"| node_ledger
node_demo -->|"uses services"| node_world
node_demo -.->|"executes rollback"| node_executors
node_ledger -->|"persists entries"| node_models
node_ledger -->|"classifies tools"| node_registry
node_ledger -->|"raises frozen error"| node_errors
node_ledger -.->|"reads and writes"| node_postgresdb
node_agent -->|"wraps actions"| node_ledger
node_agent -->|"acts on"| node_world
node_world -->|"contains service"| node_crm
node_world -->|"contains service"| node_stripeworld
node_chaos -->|"runs scenario"| node_agent
node_chaos -->|"injects faults"| node_faults
node_chaos -->|"checks results"| node_verify
node_verify -->|"checks ledger"| node_ledger
node_verify -->|"compares state"| node_snapshot
node_snapshot -->|"captures state"| node_world
node_executors -->|"uses services"| node_world
node_langgraph -->|"wraps tools"| node_ledger
node_postgres -->|"captures proofs"| node_models
node_stripe -->|"captures proofs"| node_models
node_operator -->|"views thread"| node_threadpage
node_operator -->|"uses web UI"| node_api
node_operator -.->|"requests entries"| node_entries
node_operator -.->|"requests preview"| node_preview
node_operator -.->|"requests rollback"| node_rollback

click node_cli "https://github.com/saravanx41/undolog/blob/main/undolog/cli.py"
click node_ledger "https://github.com/saravanx41/undolog/blob/main/packages/core/src/undolog_core/ledger.py"
click node_models "https://github.com/saravanx41/undolog/blob/main/packages/core/src/undolog_core/models.py"
click node_errors "https://github.com/saravanx41/undolog/blob/main/packages/core/src/undolog_core/exceptions.py"
click node_registry "https://github.com/saravanx41/undolog/blob/main/packages/core/src/undolog_core/registry/__init__.py"
click node_postgres "https://github.com/saravanx41/undolog/blob/main/packages/adapters/src/undolog_adapters/postgres_adapter.py"
click node_stripe "https://github.com/saravanx41/undolog/blob/main/packages/adapters/src/undolog_adapters/stripe_adapter.py"
click node_langgraph "https://github.com/saravanx41/undolog/blob/main/packages/langgraph/src/undolog_langgraph/adapter.py"
click node_demo "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/demo.py"
click node_agent "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/agent.py"
click node_chaos "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/chaos.py"
click node_verify "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/verify.py"
click node_faults "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/faults.py"
click node_executors "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/executors.py"
click node_snapshot "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/snapshot.py"
click node_world "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/world/__init__.py"
click node_crm "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/world/crm.py"
click node_stripeworld "https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/world/stripe.py"
click node_api "https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/api/threads/route.ts"
click node_entries "https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/api/threads/%5BthreadId%5D/entries/route.ts"
click node_preview "https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/api/threads/%5BthreadId%5D/preview/route.ts"
click node_rollback "https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/api/threads/%5BthreadId%5D/rollback/route.ts"
click node_threadpage "https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/threads/%5BthreadId%5D/page.tsx"
click node_panel "https://github.com/saravanx41/undolog/blob/main/packages/web/src/components/RollbackPanel.tsx"
click node_timeline "https://github.com/saravanx41/undolog/blob/main/packages/web/src/components/TimelineRow.tsx"
click node_webdb "https://github.com/saravanx41/undolog/blob/main/packages/web/src/lib/db.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_ledger,node_models,node_errors,node_registry toneBlue
class node_postgres,node_stripe,node_langgraph,node_postgresdb toneAmber
class node_demo,node_agent,node_chaos,node_verify,node_faults,node_executors,node_snapshot,node_world,node_crm,node_stripeworld toneMint
class node_api,node_entries,node_preview,node_rollback,node_threadpage,node_panel,node_timeline,node_webdb toneRose
class node_operator toneIndigo
class node_cli toneTeal
```

## Components

### Ledger engine

- [Thread ledger](https://github.com/saravanx41/undolog/blob/main/packages/core/src/undolog_core/ledger.py): `packages/core/src/undolog_core/ledger.py`
- [Ledger models](https://github.com/saravanx41/undolog/blob/main/packages/core/src/undolog_core/models.py): `packages/core/src/undolog_core/models.py`
- [Freeze errors](https://github.com/saravanx41/undolog/blob/main/packages/core/src/undolog_core/exceptions.py): `packages/core/src/undolog_core/exceptions.py`
- [Safety registry](https://github.com/saravanx41/undolog/blob/main/packages/core/src/undolog_core/registry/__init__.py): `packages/core/src/undolog_core/registry/__init__.py`

### Integrations

- [Postgres adapter](https://github.com/saravanx41/undolog/blob/main/packages/adapters/src/undolog_adapters/postgres_adapter.py): `packages/adapters/src/undolog_adapters/postgres_adapter.py`
- [Stripe adapter](https://github.com/saravanx41/undolog/blob/main/packages/adapters/src/undolog_adapters/stripe_adapter.py): `packages/adapters/src/undolog_adapters/stripe_adapter.py`
- [LangGraph plugin](https://github.com/saravanx41/undolog/blob/main/packages/langgraph/src/undolog_langgraph/adapter.py): `packages/langgraph/src/undolog_langgraph/adapter.py`

### Torture scenarios

- [Corruption demo](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/demo.py): `packages/torture/src/undolog_torture/demo.py`
- [Runaway agent](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/agent.py): `packages/torture/src/undolog_torture/agent.py`
- [Chaos runner](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/chaos.py): `packages/torture/src/undolog_torture/chaos.py`
- [Invariant verifier](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/verify.py): `packages/torture/src/undolog_torture/verify.py`
- [Fault injection](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/faults.py): `packages/torture/src/undolog_torture/faults.py`
- [Rollback executors](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/executors.py): `packages/torture/src/undolog_torture/executors.py`
- [World snapshots](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/snapshot.py): `packages/torture/src/undolog_torture/snapshot.py`
- [Mock services](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/world/__init__.py): `packages/torture/src/undolog_torture/world/__init__.py`
- [CRM mock](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/world/crm.py): `packages/torture/src/undolog_torture/world/crm.py`
- [Stripe mock](https://github.com/saravanx41/undolog/blob/main/packages/torture/src/undolog_torture/world/stripe.py): `packages/torture/src/undolog_torture/world/stripe.py`

### Web interface

- [Thread API](https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/api/threads/route.ts): `packages/web/src/app/api/threads/route.ts`
- [Entries API](https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/api/threads/%5BthreadId%5D/entries/route.ts): `packages/web/src/app/api/threads/[threadId]/entries/route.ts`
- [Preview API](https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/api/threads/%5BthreadId%5D/preview/route.ts): `packages/web/src/app/api/threads/[threadId]/preview/route.ts`
- [Rollback API](https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/api/threads/%5BthreadId%5D/rollback/route.ts): `packages/web/src/app/api/threads/[threadId]/rollback/route.ts`
- [Thread view](https://github.com/saravanx41/undolog/blob/main/packages/web/src/app/threads/%5BthreadId%5D/page.tsx): `packages/web/src/app/threads/[threadId]/page.tsx`
- [Rollback panel](https://github.com/saravanx41/undolog/blob/main/packages/web/src/components/RollbackPanel.tsx): `packages/web/src/components/RollbackPanel.tsx`
- [Timeline row](https://github.com/saravanx41/undolog/blob/main/packages/web/src/components/TimelineRow.tsx): `packages/web/src/components/TimelineRow.tsx`
- [Web data layer](https://github.com/saravanx41/undolog/blob/main/packages/web/src/lib/db.ts): `packages/web/src/lib/db.ts`

### Other components

- **Operator**
- [CLI](https://github.com/saravanx41/undolog/blob/main/undolog/cli.py): `undolog/cli.py`
- **PostgreSQL**

## Connections

- Operator → CLI: runs (evidence: `undolog/cli.py`)
- CLI → Corruption demo: starts demo (evidence: `undolog/cli.py`)
- CLI → Chaos runner: starts chaos (evidence: `undolog/cli.py`)
- Corruption demo → Thread ledger: wraps calls (evidence: `packages/torture/src/undolog_torture/demo.py`)
- Corruption demo → Mock services: uses services (evidence: `packages/torture/src/undolog_torture/demo.py`)
- Corruption demo → Rollback executors: executes rollback (evidence: `packages/torture/src/undolog_torture/demo.py`)
- Thread ledger → Ledger models: persists entries (evidence: `packages/core/src/undolog_core/ledger.py`)
- Thread ledger → Safety registry: classifies tools (evidence: `packages/core/src/undolog_core/ledger.py`)
- Thread ledger → Freeze errors: raises frozen error (evidence: `packages/core/src/undolog_core/ledger.py`)
- Thread ledger → PostgreSQL: reads and writes (evidence: `README.md`)
- Runaway agent → Thread ledger: wraps actions (evidence: `packages/torture/src/undolog_torture/agent.py`)
- Runaway agent → Mock services: acts on (evidence: `packages/torture/src/undolog_torture/agent.py`)
- Mock services → CRM mock: contains service (evidence: `packages/torture/src/undolog_torture/world/__init__.py`)
- Mock services → Stripe mock: contains service (evidence: `packages/torture/src/undolog_torture/world/__init__.py`)
- Chaos runner → Runaway agent: runs scenario (evidence: `packages/torture/src/undolog_torture/chaos.py`)
- Chaos runner → Fault injection: injects faults (evidence: `packages/torture/src/undolog_torture/chaos.py`)
- Chaos runner → Invariant verifier: checks results (evidence: `packages/torture/src/undolog_torture/chaos.py`)
- Invariant verifier → Thread ledger: checks ledger (evidence: `packages/torture/src/undolog_torture/verify.py`)
- Invariant verifier → World snapshots: compares state (evidence: `packages/torture/src/undolog_torture/verify.py`)
- World snapshots → Mock services: captures state (evidence: `packages/torture/src/undolog_torture/snapshot.py`)
- Rollback executors → Mock services: uses services (evidence: `packages/torture/src/undolog_torture/executors.py`)
- LangGraph plugin → Thread ledger: wraps tools (evidence: `packages/langgraph/src/undolog_langgraph/adapter.py`)
- Postgres adapter → Ledger models: captures proofs (evidence: `packages/adapters/src/undolog_adapters/postgres_adapter.py`)
- Stripe adapter → Ledger models: captures proofs (evidence: `packages/adapters/src/undolog_adapters/stripe_adapter.py`)
- Operator → Thread view: views thread (evidence: `README.md`)
- Operator → Thread API: uses web UI (evidence: `README.md`)
- Operator → Entries API: requests entries
- Operator → Preview API: requests preview
- Operator → Rollback API: requests rollback
