# mlco2/agentic-footprint architecture

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

- Interactive diagram: https://gitdiagram.com/mlco2/agentic-footprint
- Repository: https://github.com/mlco2/agentic-footprint

## Overview

Agentic Footprint measures and attributes coding-agent environmental impact. The principal workflow runs from agent hooks and energy sampling through a local spool or OTLP receiver, into the Rust watch/control plane for validation, attribution, estimation, and session-level aggregation; CLI reports and the debug console present the results. The graph preserves documented capabilities and stages, but several internal links are based on README-level architecture because their implementation was not sampled.

Main entry points: [`crates/af-cli/src/cmd/watch.rs`](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/watch.rs) (Resident watch), [`crates/af-store/src/lib.rs`](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-store/src/lib.rs) (Event and read store), [`crates/af-cli/src/cmd/ingest.rs`](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/ingest.rs) (Spool ingestion), [`crates/af-cli/src/cmd/estimator_worker.rs`](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/estimator_worker.rs) (Estimator worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection"]
  node_collectors["Agent collectors<br/>[capture-events.ts]"]
  node_sampler["Energy sampler"]
end

subgraph group_ingest["Ingestion"]
  node_spool[("Local JSONL spool<br/>[lib.rs]")]
  node_otlp["OTLP receiver<br/>[server.rs]"]
  node_normalize["Telemetry normalization<br/>[normalize.rs]"]
  node_event_contract["Event validation<br/>[validate.rs]"]
  node_ingest_pass["Spool ingestion<br/>[ingest.rs]"]
  node_store[("Event and read store<br/>[lib.rs]")]
end

subgraph group_analysis["Analysis"]
  node_watch["Resident watch<br/>[watch.rs]"]
  node_attribution["Action attribution<br/>[attribution.rs]"]
  node_correlation["Event correlation<br/>[correlate.rs]"]
  node_estimator["Impact estimation<br/>[__main__.py]"]
  node_estimator_worker["Estimator worker"]
  node_report["Session aggregation<br/>[derived.rs]"]
end

subgraph group_presentation["Presentation"]
  node_cli["CLI results<br/>[report.rs]"]
  node_statusline["Statusline output<br/>[statusline.rs]"]
  node_console_client["Console API client<br/>[afClient.svelte.ts]"]
  node_console_ui["Debug console<br/>[App.svelte]"]
  node_session_store["Session selection"]
end

subgraph group_operations["Operations"]
  node_service["Receiver service<br/>[service.rs]"]
  node_sidecar["Managed Python runtime<br/>[pyenv.rs]"]
end

node_agents(("Coding agents"))
node_user(("Operator"))

node_agents -->|"emit facts"| node_collectors
node_collectors -->|"write events"| node_spool
node_sampler -->|"write samples"| node_spool
node_agents -->|"export telemetry"| node_otlp
node_otlp -->|"normalize payloads"| node_normalize
node_normalize -->|"persist facts"| node_store
node_watch -->|"run receiver"| node_otlp
node_watch -->|"run ingest pass"| node_ingest_pass
node_ingest_pass -->|"tail files"| node_spool
node_ingest_pass -->|"validate events"| node_event_contract
node_ingest_pass -->|"insert facts"| node_store
node_watch -->|"commit updates"| node_store
node_watch -->|"attribute actions"| node_attribution
node_attribution -->|"correlate spans"| node_correlation
node_watch -->|"request estimates"| node_estimator_worker
node_estimator_worker -->|"estimate impacts"| node_estimator
node_estimator_worker -->|"return estimate rows"| node_store
node_watch -->|"rebuild summaries"| node_report
node_store -->|"supply stored facts"| node_report
node_user -->|"request results"| node_cli
node_cli -->|"read session data"| node_store
node_cli -->|"render status"| node_statusline
node_user -->|"inspect receiver"| node_console_ui
node_console_ui -->|"start client"| node_console_client
node_console_client -->|"update sessions"| node_session_store
node_console_client -->|"fetch debug data"| node_watch
node_service -->|"manage receiver"| node_watch
node_watch -->|"supervise runtime"| node_sidecar

click node_collectors "https://github.com/mlco2/agentic-footprint/blob/main/collectors/pi/capture-events.ts"
click node_sampler "https://github.com/mlco2/agentic-footprint/tree/main/python/af_sampler"
click node_spool "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-spool/src/lib.rs"
click node_otlp "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-otlp/src/server.rs"
click node_normalize "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-otlp/src/normalize.rs"
click node_event_contract "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-events/src/validate.rs"
click node_ingest_pass "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/ingest.rs"
click node_store "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-store/src/lib.rs"
click node_watch "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/watch.rs"
click node_attribution "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-core/src/attribution.rs"
click node_correlation "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-core/src/correlate.rs"
click node_estimator "https://github.com/mlco2/agentic-footprint/blob/main/python/af_estimator/__main__.py"
click node_estimator_worker "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/estimator_worker.rs"
click node_report "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-store/src/derived.rs"
click node_cli "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/report.rs"
click node_statusline "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/statusline.rs"
click node_console_client "https://github.com/mlco2/agentic-footprint/blob/main/console/src/lib/client/afClient.svelte.ts"
click node_console_ui "https://github.com/mlco2/agentic-footprint/blob/main/console/src/App.svelte"
click node_session_store "https://github.com/mlco2/agentic-footprint/blob/main/console/src/lib/stores/sessionStore.svelte.ts"
click node_service "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/service.rs"
click node_sidecar "https://github.com/mlco2/agentic-footprint/blob/main/crates/af-sidecar/src/pyenv.rs"

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_collectors,node_sampler toneBlue
class node_spool,node_otlp,node_normalize,node_event_contract,node_ingest_pass,node_store toneAmber
class node_watch,node_attribution,node_correlation,node_estimator,node_estimator_worker,node_report toneMint
class node_cli,node_statusline,node_console_client,node_console_ui,node_session_store toneRose
class node_service,node_sidecar,node_agents,node_user toneIndigo
```

## Components

### Collection

- [Agent collectors](https://github.com/mlco2/agentic-footprint/blob/main/collectors/pi/capture-events.ts): `collectors/pi/capture-events.ts`
- [Energy sampler](https://github.com/mlco2/agentic-footprint/tree/main/python/af_sampler): `python/af_sampler`

### Ingestion

- [Local JSONL spool](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-spool/src/lib.rs): `crates/af-spool/src/lib.rs`
- [OTLP receiver](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-otlp/src/server.rs): `crates/af-otlp/src/server.rs`
- [Telemetry normalization](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-otlp/src/normalize.rs): `crates/af-otlp/src/normalize.rs`
- [Event validation](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-events/src/validate.rs): `crates/af-events/src/validate.rs`
- [Spool ingestion](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/ingest.rs): `crates/af-cli/src/cmd/ingest.rs`
- [Event and read store](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-store/src/lib.rs): `crates/af-store/src/lib.rs`

### Analysis

- [Resident watch](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/watch.rs): `crates/af-cli/src/cmd/watch.rs`
- [Action attribution](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-core/src/attribution.rs): `crates/af-core/src/attribution.rs`
- [Event correlation](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-core/src/correlate.rs): `crates/af-core/src/correlate.rs`
- [Impact estimation](https://github.com/mlco2/agentic-footprint/blob/main/python/af_estimator/__main__.py): `python/af_estimator/__main__.py`
- [Estimator worker](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/estimator_worker.rs): `crates/af-cli/src/cmd/estimator_worker.rs`
- [Session aggregation](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-store/src/derived.rs): `crates/af-store/src/derived.rs`

### Presentation

- [CLI results](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/report.rs): `crates/af-cli/src/cmd/report.rs`
- [Statusline output](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/statusline.rs): `crates/af-cli/src/statusline.rs`
- [Console API client](https://github.com/mlco2/agentic-footprint/blob/main/console/src/lib/client/afClient.svelte.ts): `console/src/lib/client/afClient.svelte.ts`
- [Debug console](https://github.com/mlco2/agentic-footprint/blob/main/console/src/App.svelte): `console/src/App.svelte`
- [Session selection](https://github.com/mlco2/agentic-footprint/blob/main/console/src/lib/stores/sessionStore.svelte.ts): `console/src/lib/stores/sessionStore.svelte.ts`

### Operations

- [Receiver service](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-cli/src/cmd/service.rs): `crates/af-cli/src/cmd/service.rs`
- [Managed Python runtime](https://github.com/mlco2/agentic-footprint/blob/main/crates/af-sidecar/src/pyenv.rs): `crates/af-sidecar/src/pyenv.rs`

### Other components

- **Coding agents**
- **Operator**

## Connections

- Coding agents → Agent collectors: emit facts (evidence: `README.md`)
- Agent collectors → Local JSONL spool: write events (evidence: `README.md`)
- Energy sampler → Local JSONL spool: write samples (evidence: `README.md`)
- Coding agents → OTLP receiver: export telemetry (evidence: `README.md`)
- OTLP receiver → Telemetry normalization: normalize payloads (evidence: `crates/af-otlp/src/server.rs`)
- Telemetry normalization → Event and read store: persist facts (evidence: `README.md`)
- Resident watch → OTLP receiver: run receiver (evidence: `README.md`)
- Resident watch → Spool ingestion: run ingest pass (evidence: `crates/af-cli/src/cmd/ingest.rs`)
- Spool ingestion → Local JSONL spool: tail files (evidence: `crates/af-cli/src/cmd/ingest.rs`)
- Spool ingestion → Event validation: validate events (evidence: `README.md`)
- Spool ingestion → Event and read store: insert facts (evidence: `crates/af-cli/src/cmd/ingest.rs`)
- Resident watch → Event and read store: commit updates
- Resident watch → Action attribution: attribute actions (evidence: `README.md`)
- Action attribution → Event correlation: correlate spans (evidence: `crates/af-core/src/attribution.rs`)
- Resident watch → Estimator worker: request estimates (evidence: `README.md`)
- Estimator worker → Impact estimation: estimate impacts (evidence: `README.md`)
- Estimator worker → Event and read store: return estimate rows (evidence: `crates/af-cli/src/cmd/estimator_worker.rs`)
- Resident watch → Session aggregation: rebuild summaries (evidence: `README.md`)
- Event and read store → Session aggregation: supply stored facts (evidence: `README.md`)
- Operator → CLI results: request results (evidence: `README.md`)
- CLI results → Event and read store: read session data (evidence: `README.md`)
- CLI results → Statusline output: render status (evidence: `README.md`)
- Operator → Debug console: inspect receiver (evidence: `README.md`)
- Debug console → Console API client: start client (evidence: `console/src/App.svelte`)
- Console API client → Session selection: update sessions (evidence: `console/src/lib/client/afClient.svelte.ts`)
- Console API client → Resident watch: fetch debug data (evidence: `README.md`)
- Receiver service → Resident watch: manage receiver (evidence: `README.md`)
- Resident watch → Managed Python runtime: supervise runtime (evidence: `README.md`)
