# abhisheksarkar30/claude-lens architecture

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

- Interactive diagram: https://gitdiagram.com/abhisheksarkar30/claude-lens
- Repository: https://github.com/abhisheksarkar30/claude-lens

## Overview

Claude Lens is a local, single-user observability proxy and dashboard for Claude traffic. Its main workflow captures proxied requests and responses, then combines those records with Claude Code JSONL transcripts, quota snapshots, and Admin API reports to show calls, warnings, sessions, costs, and quota. The CLI and dashboard expose inspection and maintenance operations; replay reissues captured traffic through the proxy. The graph follows documented behavior and source-index references; some collector and dashboard internals were not sampled, so uncertain links are omitted.

Main entry points: [`internal/store/store.go`](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/store/store.go) (SQLite event store), [`internal/jsonlogs/jsonlogs.go`](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/jsonlogs/jsonlogs.go) (Transcript tailer), [`internal/consumer/consumer.go`](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/consumer/consumer.go) (Event consumer), [`internal/api/api.go`](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/api/api.go) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and ingest"]
  node_proxy["Traffic proxy<br/>[proxy.go]"]
  node_sink["Capture queue<br/>[sink.go]"]
  node_consumer["Event consumer<br/>[consumer.go]"]
  node_ingest_runner["Collector runner<br/>[ingest.go]"]
  node_jsonlogs["Transcript tailer<br/>[jsonlogs.go]"]
  node_snapshot["Quota snapshot<br/>[snapshot.go]"]
  node_adminrep["Usage and cost reports<br/>[adminrep.go]"]
end

subgraph group_analysis["Analysis and billing"]
  node_parse["Request parsing"]
  node_analyze["Warning rules<br/>[rules.go]"]
  node_sessions["Session grouping<br/>[session.go]"]
  node_pricing["Cost pricing<br/>[pricing.go]"]
  node_quota["Quota calculations<br/>[quota.go]"]
  node_reconcile["Cost reconciliation<br/>[reconcile.go]"]
end

subgraph group_persistence["Persistence"]
  node_store[("SQLite event store<br/>[store.go]")]
end

subgraph group_interfaces["User interfaces"]
  node_clens["Command dispatcher<br/>[main.go]"]
  node_cli_ops["CLI operations"]
  node_api["Dashboard API<br/>[api.go]"]
  node_web["Dashboard UI<br/>[app.js]"]
  node_replay["Request replay<br/>[replay.go]"]
end

node_developer(("Developer"))
node_claude_client(("Claude client"))
node_anthropic["Anthropic API"]
node_transcripts[("Claude transcripts")]
node_snapshot_service["Usage endpoint"]
node_admin_service["Admin API"]

node_developer -->|"runs commands"| node_clens
node_clens -->|"dispatches commands"| node_cli_ops
node_cli_ops -.->|"queries or updates"| node_store
node_claude_client -->|"sends traffic"| node_proxy
node_proxy -->|"forwards requests"| node_anthropic
node_proxy -->|"queues captures"| node_sink
node_sink -->|"drains captures"| node_consumer
node_consumer -->|"writes events"| node_store
node_consumer -->|"extracts usage"| node_parse
node_consumer -->|"computes cost"| node_pricing
node_consumer -->|"runs rules"| node_analyze
node_consumer -->|"resolves sessions"| node_sessions
node_transcripts -->|"provides JSONL"| node_jsonlogs
node_jsonlogs -->|"merges events"| node_store
node_jsonlogs -->|"parses records"| node_parse
node_jsonlogs -.->|"prices events"| node_pricing
node_jsonlogs -.->|"checks events"| node_analyze
node_jsonlogs -.->|"records sessions"| node_sessions
node_clens -->|"runs collectors"| node_ingest_runner
node_ingest_runner -->|"runs tailer"| node_jsonlogs
node_ingest_runner -->|"runs poller"| node_snapshot
node_ingest_runner -->|"runs reports"| node_adminrep
node_snapshot -.->|"fetches utilization"| node_snapshot_service
node_adminrep -->|"fetches reports"| node_admin_service
node_adminrep -->|"writes report rows"| node_store
node_snapshot -->|"writes snapshots"| node_store
node_analyze -->|"inspects usage"| node_parse
node_analyze -->|"creates warnings"| node_store
node_sessions -->|"updates aggregates"| node_store
node_pricing -->|"uses token usage"| node_parse
node_quota -->|"reads usage"| node_store
node_reconcile -->|"compares costs"| node_store
node_developer -->|"views dashboard"| node_api
node_api -->|"reads records"| node_store
node_api -->|"serves assets"| node_web
node_api -->|"reissues replay"| node_proxy
node_api -->|"builds replay"| node_replay
node_replay -->|"loads captured call"| node_store
node_cli_ops -.->|"refreshes collectors"| node_ingest_runner

click node_clens "https://github.com/abhisheksarkar30/claude-lens/blob/main/cmd/clens/main.go"
click node_cli_ops "https://github.com/abhisheksarkar30/claude-lens/tree/main/internal/cli"
click node_proxy "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/proxy/proxy.go"
click node_sink "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/sink/sink.go"
click node_consumer "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/consumer/consumer.go"
click node_ingest_runner "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/ingest/ingest.go"
click node_jsonlogs "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/jsonlogs/jsonlogs.go"
click node_snapshot "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/snapshot/snapshot.go"
click node_adminrep "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/adminrep/adminrep.go"
click node_parse "https://github.com/abhisheksarkar30/claude-lens/tree/main/internal/parse"
click node_analyze "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/analyze/rules.go"
click node_sessions "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/session/session.go"
click node_pricing "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/pricing/pricing.go"
click node_quota "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/quota/quota.go"
click node_reconcile "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/reconcile/reconcile.go"
click node_store "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/store/store.go"
click node_api "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/api/api.go"
click node_web "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/web/app.js"
click node_replay "https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/replay/replay.go"

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_proxy,node_sink,node_consumer,node_ingest_runner,node_jsonlogs,node_snapshot,node_adminrep,node_claude_client toneBlue
class node_parse,node_analyze,node_sessions,node_pricing,node_quota,node_reconcile,node_transcripts toneAmber
class node_store,node_anthropic,node_admin_service toneMint
class node_clens,node_cli_ops,node_api,node_web,node_replay toneRose
class node_developer,node_snapshot_service toneIndigo
```

## Components

### Capture and ingest

- [Traffic proxy](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/proxy/proxy.go): `internal/proxy/proxy.go`
- [Capture queue](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/sink/sink.go): `internal/sink/sink.go`
- [Event consumer](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/consumer/consumer.go): `internal/consumer/consumer.go`
- [Collector runner](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/ingest/ingest.go): `internal/ingest/ingest.go`
- [Transcript tailer](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/jsonlogs/jsonlogs.go): `internal/jsonlogs/jsonlogs.go`
- [Quota snapshot](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/snapshot/snapshot.go): `internal/snapshot/snapshot.go`
- [Usage and cost reports](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/adminrep/adminrep.go): `internal/adminrep/adminrep.go`

### Analysis and billing

- [Request parsing](https://github.com/abhisheksarkar30/claude-lens/tree/main/internal/parse): `internal/parse`
- [Warning rules](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/analyze/rules.go): `internal/analyze/rules.go`
- [Session grouping](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/session/session.go): `internal/session/session.go`
- [Cost pricing](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/pricing/pricing.go): `internal/pricing/pricing.go`
- [Quota calculations](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/quota/quota.go): `internal/quota/quota.go`
- [Cost reconciliation](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/reconcile/reconcile.go): `internal/reconcile/reconcile.go`

### Persistence

- [SQLite event store](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/store/store.go): `internal/store/store.go`

### User interfaces

- [Command dispatcher](https://github.com/abhisheksarkar30/claude-lens/blob/main/cmd/clens/main.go): `cmd/clens/main.go`
- [CLI operations](https://github.com/abhisheksarkar30/claude-lens/tree/main/internal/cli): `internal/cli`
- [Dashboard API](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/api/api.go): `internal/api/api.go`
- [Dashboard UI](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/web/app.js): `internal/web/app.js`
- [Request replay](https://github.com/abhisheksarkar30/claude-lens/blob/main/internal/replay/replay.go): `internal/replay/replay.go`

### Other components

- **Developer**
- **Claude client**
- **Anthropic API**
- **Claude transcripts**
- **Usage endpoint**
- **Admin API**

## Connections

- Developer → Command dispatcher: runs commands (evidence: `README.md`)
- Command dispatcher → CLI operations: dispatches commands (evidence: `cmd/clens/main.go`)
- CLI operations → SQLite event store: queries or updates
- Claude client → Traffic proxy: sends traffic (evidence: `README.md`)
- Traffic proxy → Anthropic API: forwards requests (evidence: `README.md`)
- Traffic proxy → Capture queue: queues captures (evidence: `internal/proxy/proxy.go`)
- Capture queue → Event consumer: drains captures (evidence: `internal/consumer/consumer.go`)
- Event consumer → SQLite event store: writes events (evidence: `internal/consumer/consumer.go`)
- Event consumer → Request parsing: extracts usage (evidence: `internal/consumer/consumer.go`)
- Event consumer → Cost pricing: computes cost (evidence: `internal/consumer/consumer.go`)
- Event consumer → Warning rules: runs rules (evidence: `internal/consumer/consumer.go`)
- Event consumer → Session grouping: resolves sessions (evidence: `internal/consumer/consumer.go`)
- Claude transcripts → Transcript tailer: provides JSONL (evidence: `README.md`)
- Transcript tailer → SQLite event store: merges events (evidence: `internal/jsonlogs/jsonlogs.go`)
- Transcript tailer → Request parsing: parses records (evidence: `internal/jsonlogs/jsonlogs.go`)
- Transcript tailer → Cost pricing: prices events
- Transcript tailer → Warning rules: checks events
- Transcript tailer → Session grouping: records sessions
- Command dispatcher → Collector runner: runs collectors
- Collector runner → Transcript tailer: runs tailer (evidence: `internal/ingest/ingest.go`)
- Collector runner → Quota snapshot: runs poller (evidence: `internal/ingest/ingest.go`)
- Collector runner → Usage and cost reports: runs reports (evidence: `internal/ingest/ingest.go`)
- Quota snapshot → Usage endpoint: fetches utilization
- Usage and cost reports → Admin API: fetches reports (evidence: `internal/adminrep/adminrep.go`)
- Usage and cost reports → SQLite event store: writes report rows (evidence: `internal/adminrep/adminrep.go`)
- Quota snapshot → SQLite event store: writes snapshots (evidence: `internal/snapshot/snapshot.go`)
- Warning rules → Request parsing: inspects usage (evidence: `internal/analyze/rules.go`)
- Warning rules → SQLite event store: creates warnings (evidence: `internal/analyze/rules.go`)
- Session grouping → SQLite event store: updates aggregates (evidence: `internal/session/session.go`)
- Cost pricing → Request parsing: uses token usage (evidence: `internal/pricing/pricing.go`)
- Quota calculations → SQLite event store: reads usage (evidence: `internal/quota/quota.go`)
- Cost reconciliation → SQLite event store: compares costs (evidence: `internal/reconcile/reconcile.go`)
- Developer → Dashboard API: views dashboard (evidence: `README.md`)
- Dashboard API → SQLite event store: reads records (evidence: `internal/api/api.go`)
- Dashboard API → Dashboard UI: serves assets (evidence: `internal/api/api.go`)
- Dashboard API → Traffic proxy: reissues replay (evidence: `internal/api/api.go`)
- Dashboard API → Request replay: builds replay
- Request replay → SQLite event store: loads captured call
- CLI operations → Collector runner: refreshes collectors
