# epsilla-cloud/clawtrace architecture

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

- Interactive diagram: https://gitdiagram.com/epsilla-cloud/clawtrace
- Repository: https://github.com/epsilla-cloud/clawtrace

## Overview

ClawTrace captures cost-aware agent execution traces, stores and queries them as a trajectory graph, and presents them for inspection or AI analysis. Its related CostCraft package uses TraceCards to distill agent skills through preserve, prune, and repair patches. The main capture-to-inspection links are documented in the README; implementation excerpts are limited, so uncertain internal service wiring is omitted.

Main entry points: [`packages/clawtrace-ui/src/components/traces/TracesPage.tsx`](https://github.com/epsilla-cloud/clawtrace/blob/main/packages/clawtrace-ui/src/components/traces/TracesPage.tsx) (ClawTrace UI), [`services/clawtrace-backend/app/main.py`](https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-backend/app/main.py) (Backend API), [`services/clawtrace-payment/app`](https://github.com/epsilla-cloud/clawtrace/tree/main/services/clawtrace-payment/app) (Payment service), [`plugins/clawtrace/src/tracker.ts`](https://github.com/epsilla-cloud/clawtrace/blob/main/plugins/clawtrace/src/tracker.ts) (ClawTrace plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and ingest"]
  node_plugin["ClawTrace plugin<br/>[tracker.ts]"]
  node_plugin_sink["Event sink<br/>[event-sink.ts]"]
  node_ingest["Ingest service<br/>[main.py]"]
  node_raw_storage["Raw event storage<br/>[storage.py]"]
end

subgraph group_graph["Graph and analysis"]
  node_backend["Backend API<br/>[main.py]"]
  node_tracy_mcp["Tracy MCP<br/>[tracy_mcp.py]"]
  node_tracy["Tracy analyst<br/>[tracy.py]"]
end

subgraph group_product["User application"]
  node_ui["ClawTrace UI<br/>[TracesPage.tsx]"]
  node_trace_views["Trace views<br/>[TrajectoryPage.tsx]"]
  node_tracy_panel["Tracy chat panel<br/>[TracyPanel.tsx]"]
end

subgraph group_commerce["Accounts and billing"]
  node_billing_api["Billing routes"]
  node_payment["Payment service"]
end

subgraph group_distill["Skill distillation"]
  node_tracecard["TraceCard compiler<br/>[tracecard.py]"]
  node_costcraft["CostCraft refinement<br/>[refine.py]"]
  node_patches["Skill patches"]
end

node_agent(("OpenClaw agent"))
node_object_store[("Cloud object storage")]
node_lakeflow["Databricks Lakeflow"]
node_silver[("Silver tables")]
node_puppygraph["PuppyGraph"]
node_neon[("Neon PostgreSQL")]
node_user(("Agent owner"))
node_stripe["Stripe"]

node_agent -->|"runs hooks"| node_plugin
node_plugin -->|"emits events"| node_plugin_sink
node_plugin_sink -->|"POSTs events"| node_ingest
node_ingest -->|"persists events"| node_raw_storage
node_raw_storage -->|"writes objects"| node_object_store
node_object_store -->|"feeds raw data"| node_lakeflow
node_lakeflow -->|"materializes tables"| node_silver
node_silver -->|"virtualized as graph"| node_puppygraph
node_backend -->|"runs Cypher"| node_puppygraph
node_tracy_mcp -->|"queries graph"| node_puppygraph
node_backend -->|"stores account data"| node_neon
node_user -->|"inspects traces"| node_ui
node_ui -->|"requests trace data"| node_backend
node_ui -->|"renders trajectories"| node_trace_views
node_ui -->|"opens analysis"| node_tracy_panel
node_tracy_panel -->|"sends questions"| node_backend
node_tracy -->|"uses graph tools"| node_tracy_mcp
node_billing_api -->|"requests billing"| node_payment
node_payment -->|"updates credits"| node_neon
node_payment -->|"handles payments"| node_stripe
node_tracecard -->|"supplies trace summaries"| node_costcraft
node_costcraft -->|"produces preserve prune repair"| node_patches

click node_plugin "https://github.com/epsilla-cloud/clawtrace/blob/main/plugins/clawtrace/src/tracker.ts"
click node_plugin_sink "https://github.com/epsilla-cloud/clawtrace/blob/main/plugins/clawtrace/src/event-sink.ts"
click node_ingest "https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-ingest/app/main.py"
click node_raw_storage "https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-ingest/app/storage.py"
click node_backend "https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-backend/app/main.py"
click node_tracy_mcp "https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-backend/app/routers/tracy_mcp.py"
click node_tracy "https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-backend/app/routers/tracy.py"
click node_ui "https://github.com/epsilla-cloud/clawtrace/blob/main/packages/clawtrace-ui/src/components/traces/TracesPage.tsx"
click node_trace_views "https://github.com/epsilla-cloud/clawtrace/blob/main/packages/clawtrace-ui/src/components/traces/TrajectoryPage.tsx"
click node_tracy_panel "https://github.com/epsilla-cloud/clawtrace/blob/main/packages/clawtrace-ui/src/components/tracy/TracyPanel.tsx"
click node_billing_api "https://github.com/epsilla-cloud/clawtrace/tree/main/packages/clawtrace-ui/src/app/api/billing"
click node_payment "https://github.com/epsilla-cloud/clawtrace/tree/main/services/clawtrace-payment/app"
click node_tracecard "https://github.com/epsilla-cloud/clawtrace/blob/main/costcraft/costcraft/tracecard.py"
click node_costcraft "https://github.com/epsilla-cloud/clawtrace/blob/main/costcraft/costcraft/refine.py"
click node_patches "https://github.com/epsilla-cloud/clawtrace/tree/main/costcraft/costcraft/analysts"

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_plugin,node_plugin_sink,node_ingest,node_raw_storage toneBlue
class node_backend,node_tracy_mcp,node_tracy,node_object_store,node_silver,node_neon toneAmber
class node_ui,node_trace_views,node_tracy_panel toneMint
class node_billing_api,node_payment toneRose
class node_tracecard,node_costcraft,node_patches,node_agent,node_lakeflow,node_puppygraph,node_user,node_stripe toneIndigo
```

## Components

### Capture and ingest

- [ClawTrace plugin](https://github.com/epsilla-cloud/clawtrace/blob/main/plugins/clawtrace/src/tracker.ts): `plugins/clawtrace/src/tracker.ts`
- [Event sink](https://github.com/epsilla-cloud/clawtrace/blob/main/plugins/clawtrace/src/event-sink.ts): `plugins/clawtrace/src/event-sink.ts`
- [Ingest service](https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-ingest/app/main.py): `services/clawtrace-ingest/app/main.py`
- [Raw event storage](https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-ingest/app/storage.py): `services/clawtrace-ingest/app/storage.py`

### Graph and analysis

- [Backend API](https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-backend/app/main.py): `services/clawtrace-backend/app/main.py`
- [Tracy MCP](https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-backend/app/routers/tracy_mcp.py): `services/clawtrace-backend/app/routers/tracy_mcp.py`
- [Tracy analyst](https://github.com/epsilla-cloud/clawtrace/blob/main/services/clawtrace-backend/app/routers/tracy.py): `services/clawtrace-backend/app/routers/tracy.py`

### User application

- [ClawTrace UI](https://github.com/epsilla-cloud/clawtrace/blob/main/packages/clawtrace-ui/src/components/traces/TracesPage.tsx): `packages/clawtrace-ui/src/components/traces/TracesPage.tsx`
- [Trace views](https://github.com/epsilla-cloud/clawtrace/blob/main/packages/clawtrace-ui/src/components/traces/TrajectoryPage.tsx): `packages/clawtrace-ui/src/components/traces/TrajectoryPage.tsx`
- [Tracy chat panel](https://github.com/epsilla-cloud/clawtrace/blob/main/packages/clawtrace-ui/src/components/tracy/TracyPanel.tsx): `packages/clawtrace-ui/src/components/tracy/TracyPanel.tsx`

### Accounts and billing

- [Billing routes](https://github.com/epsilla-cloud/clawtrace/tree/main/packages/clawtrace-ui/src/app/api/billing): `packages/clawtrace-ui/src/app/api/billing`
- [Payment service](https://github.com/epsilla-cloud/clawtrace/tree/main/services/clawtrace-payment/app): `services/clawtrace-payment/app`

### Skill distillation

- [TraceCard compiler](https://github.com/epsilla-cloud/clawtrace/blob/main/costcraft/costcraft/tracecard.py): `costcraft/costcraft/tracecard.py`
- [CostCraft refinement](https://github.com/epsilla-cloud/clawtrace/blob/main/costcraft/costcraft/refine.py): `costcraft/costcraft/refine.py`
- [Skill patches](https://github.com/epsilla-cloud/clawtrace/tree/main/costcraft/costcraft/analysts): `costcraft/costcraft/analysts`

### Other components

- **OpenClaw agent**
- **Cloud object storage**
- **Databricks Lakeflow**
- **Silver tables**
- **PuppyGraph**
- **Neon PostgreSQL**
- **Agent owner**
- **Stripe**

## Connections

- OpenClaw agent → ClawTrace plugin: runs hooks
- ClawTrace plugin → Event sink: emits events
- Event sink → Ingest service: POSTs events
- Ingest service → Raw event storage: persists events
- Raw event storage → Cloud object storage: writes objects
- Cloud object storage → Databricks Lakeflow: feeds raw data
- Databricks Lakeflow → Silver tables: materializes tables
- Silver tables → PuppyGraph: virtualized as graph
- Backend API → PuppyGraph: runs Cypher
- Tracy MCP → PuppyGraph: queries graph
- Backend API → Neon PostgreSQL: stores account data
- Agent owner → ClawTrace UI: inspects traces
- ClawTrace UI → Backend API: requests trace data
- ClawTrace UI → Trace views: renders trajectories
- ClawTrace UI → Tracy chat panel: opens analysis
- Tracy chat panel → Backend API: sends questions
- Tracy analyst → Tracy MCP: uses graph tools
- Billing routes → Payment service: requests billing
- Payment service → Neon PostgreSQL: updates credits
- Payment service → Stripe: handles payments
- TraceCard compiler → CostCraft refinement: supplies trace summaries
- CostCraft refinement → Skill patches: produces preserve prune repair