# tracewick/agent architecture

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

- Interactive diagram: https://gitdiagram.com/tracewick/agent
- Repository: https://github.com/tracewick/agent

## Overview

Tracewick Agent is a long-running Go sidecar that reads PHP spool-v2 files and delivers aggregated profiles to Pyroscope. Its main workflow is configured and started through the CLI, claims and parses spool files, groups compatible profiles, decodes/merges and encodes pprof, pushes to Pyroscope, then acknowledges, releases, rejects, or pauses delivery according to the result. Supporting branches include cardinality control, operational metrics, and delivery limits/policy. Relationships reflect the README and shown imports/calls; several implementation details are unsampled, so uncertain links are omitted.

Main entry points: [`internal/agent/drainer.go`](https://github.com/tracewick/agent/blob/main/internal/agent/drainer.go) (Drain pass), [`internal/cli/cli.go`](https://github.com/tracewick/agent/blob/main/internal/cli/cli.go) (CLI runner), [`internal/spool/source.go`](https://github.com/tracewick/agent/blob/main/internal/spool/source.go) (Spool claims), [`internal/config/config.go`](https://github.com/tracewick/agent/blob/main/internal/config/config.go) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_main["Agent command<br/>[main.go]"]
  node_cli["CLI runner<br/>[cli.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_agent["Polling agent<br/>[agent.go]"]
  node_drainer["Drain pass<br/>[drainer.go]"]
end

subgraph group_spool["Spool and aggregation"]
  node_spoolsource["Spool claims<br/>[source.go]"]
  node_spoolfiles["Spool parsing<br/>[file.go]"]
  node_grouping["Window grouping<br/>[group.go]"]
  node_aggkey["Aggregation keys<br/>[key.go]"]
  node_cardinality["Cardinality gate<br/>[cardinality.go]"]
end

subgraph group_profiles["Profile processing"]
  node_profiledecode["Profile decoding<br/>[compact.go]"]
  node_profilemerge["Profile merging<br/>[merge.go]"]
  node_profileencode["Pprof encoding<br/>[encode.go]"]
end

subgraph group_delivery["Delivery controls"]
  node_pyroclient["Pyroscope client<br/>[client.go]"]
  node_pushwire["Push request encoding<br/>[push.go]"]
  node_policy["Delivery policy<br/>[policy.go]"]
  node_limits["Resource limits<br/>[limits.go]"]
end

subgraph group_ops["Operations"]
  node_metrics["Prometheus metrics<br/>[registry.go]"]
  node_metricserver["Metrics endpoint<br/>[server.go]"]
end

node_writer(("PHP spool writer"))
node_pyroscope(("Pyroscope"))

node_writer -->|"writes files"| node_spoolsource
node_main -->|"runs"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"constructs and runs"| node_agent
node_cli -->|"starts"| node_metricserver
node_agent -->|"drains repeatedly"| node_drainer
node_agent -->|"reads backlog"| node_spoolsource
node_drainer -->|"claims files"| node_spoolsource
node_drainer -->|"parses claims"| node_spoolfiles
node_drainer -->|"groups profiles"| node_grouping
node_drainer -->|"decodes profiles"| node_profiledecode
node_drainer -->|"merges groups"| node_profilemerge
node_drainer -->|"encodes pprof"| node_profileencode
node_drainer -->|"pushes profiles"| node_pyroclient
node_drainer -->|"classifies results"| node_policy
node_drainer -->|"acks or releases"| node_spoolsource
node_pyroclient -->|"encodes request"| node_pushwire
node_pyroclient -->|"posts profiles"| node_pyroscope
node_config -->|"configures spool"| node_spoolsource
node_config -->|"sets limits"| node_limits
node_drainer -->|"enforces budgets"| node_limits
node_grouping -->|"validates keys"| node_aggkey
node_drainer -.->|"limits label keys"| node_cardinality
node_cli -->|"creates registry"| node_metrics
node_metricserver -.->|"serves metrics"| node_metrics

click node_main "https://github.com/tracewick/agent/blob/main/cmd/tracewick-agent/main.go"
click node_cli "https://github.com/tracewick/agent/blob/main/internal/cli/cli.go"
click node_config "https://github.com/tracewick/agent/blob/main/internal/config/config.go"
click node_agent "https://github.com/tracewick/agent/blob/main/internal/agent/agent.go"
click node_drainer "https://github.com/tracewick/agent/blob/main/internal/agent/drainer.go"
click node_spoolsource "https://github.com/tracewick/agent/blob/main/internal/spool/source.go"
click node_spoolfiles "https://github.com/tracewick/agent/blob/main/internal/spool/file.go"
click node_grouping "https://github.com/tracewick/agent/blob/main/internal/aggregate/group.go"
click node_aggkey "https://github.com/tracewick/agent/blob/main/internal/aggregate/key.go"
click node_cardinality "https://github.com/tracewick/agent/blob/main/internal/aggregate/cardinality.go"
click node_profiledecode "https://github.com/tracewick/agent/blob/main/internal/pprof/compact.go"
click node_profilemerge "https://github.com/tracewick/agent/blob/main/internal/pprof/merge.go"
click node_profileencode "https://github.com/tracewick/agent/blob/main/internal/pprof/encode.go"
click node_pyroclient "https://github.com/tracewick/agent/blob/main/internal/pyroscope/client.go"
click node_pushwire "https://github.com/tracewick/agent/blob/main/internal/pyroscope/push.go"
click node_policy "https://github.com/tracewick/agent/blob/main/internal/delivery/policy.go"
click node_limits "https://github.com/tracewick/agent/blob/main/internal/delivery/limits.go"
click node_metrics "https://github.com/tracewick/agent/blob/main/internal/metrics/registry.go"
click node_metricserver "https://github.com/tracewick/agent/blob/main/internal/metrics/server.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_main,node_cli,node_config,node_agent,node_drainer toneBlue
class node_spoolsource,node_spoolfiles,node_grouping,node_aggkey,node_cardinality toneAmber
class node_profiledecode,node_profilemerge,node_profileencode toneMint
class node_pyroclient,node_pushwire,node_policy,node_limits toneRose
class node_metrics,node_metricserver,node_writer,node_pyroscope toneIndigo
```

## Components

### Runtime orchestration

- [Agent command](https://github.com/tracewick/agent/blob/main/cmd/tracewick-agent/main.go): `cmd/tracewick-agent/main.go`
- [CLI runner](https://github.com/tracewick/agent/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [Configuration](https://github.com/tracewick/agent/blob/main/internal/config/config.go): `internal/config/config.go`
- [Polling agent](https://github.com/tracewick/agent/blob/main/internal/agent/agent.go): `internal/agent/agent.go`
- [Drain pass](https://github.com/tracewick/agent/blob/main/internal/agent/drainer.go): `internal/agent/drainer.go`

### Spool and aggregation

- [Spool claims](https://github.com/tracewick/agent/blob/main/internal/spool/source.go): `internal/spool/source.go`
- [Spool parsing](https://github.com/tracewick/agent/blob/main/internal/spool/file.go): `internal/spool/file.go`
- [Window grouping](https://github.com/tracewick/agent/blob/main/internal/aggregate/group.go): `internal/aggregate/group.go`
- [Aggregation keys](https://github.com/tracewick/agent/blob/main/internal/aggregate/key.go): `internal/aggregate/key.go`
- [Cardinality gate](https://github.com/tracewick/agent/blob/main/internal/aggregate/cardinality.go): `internal/aggregate/cardinality.go`

### Profile processing

- [Profile decoding](https://github.com/tracewick/agent/blob/main/internal/pprof/compact.go): `internal/pprof/compact.go`
- [Profile merging](https://github.com/tracewick/agent/blob/main/internal/pprof/merge.go): `internal/pprof/merge.go`
- [Pprof encoding](https://github.com/tracewick/agent/blob/main/internal/pprof/encode.go): `internal/pprof/encode.go`

### Delivery controls

- [Pyroscope client](https://github.com/tracewick/agent/blob/main/internal/pyroscope/client.go): `internal/pyroscope/client.go`
- [Push request encoding](https://github.com/tracewick/agent/blob/main/internal/pyroscope/push.go): `internal/pyroscope/push.go`
- [Delivery policy](https://github.com/tracewick/agent/blob/main/internal/delivery/policy.go): `internal/delivery/policy.go`
- [Resource limits](https://github.com/tracewick/agent/blob/main/internal/delivery/limits.go): `internal/delivery/limits.go`

### Operations

- [Prometheus metrics](https://github.com/tracewick/agent/blob/main/internal/metrics/registry.go): `internal/metrics/registry.go`
- [Metrics endpoint](https://github.com/tracewick/agent/blob/main/internal/metrics/server.go): `internal/metrics/server.go`

### Other components

- **PHP spool writer**
- **Pyroscope**

## Connections

- PHP spool writer → Spool claims: writes files (evidence: `README.md`)
- Agent command → CLI runner: runs (evidence: `cmd/tracewick-agent/main.go`)
- CLI runner → Configuration: loads settings (evidence: `internal/cli/cli.go`)
- CLI runner → Polling agent: constructs and runs (evidence: `internal/cli/cli.go`)
- CLI runner → Metrics endpoint: starts (evidence: `internal/cli/cli.go`)
- Polling agent → Drain pass: drains repeatedly (evidence: `internal/agent/agent.go`)
- Polling agent → Spool claims: reads backlog (evidence: `internal/agent/agent.go`)
- Drain pass → Spool claims: claims files (evidence: `internal/agent/drainer.go`)
- Drain pass → Spool parsing: parses claims (evidence: `internal/agent/drainer.go`)
- Drain pass → Window grouping: groups profiles (evidence: `internal/agent/drainer.go`)
- Drain pass → Profile decoding: decodes profiles (evidence: `internal/agent/drainer.go`)
- Drain pass → Profile merging: merges groups (evidence: `internal/agent/drainer.go`)
- Drain pass → Pprof encoding: encodes pprof (evidence: `internal/agent/drainer.go`)
- Drain pass → Pyroscope client: pushes profiles (evidence: `internal/agent/drainer.go`)
- Drain pass → Delivery policy: classifies results (evidence: `internal/agent/drainer.go`)
- Drain pass → Spool claims: acks or releases (evidence: `README.md`)
- Pyroscope client → Push request encoding: encodes request (evidence: `internal/pyroscope/client.go`)
- Pyroscope client → Pyroscope: posts profiles (evidence: `internal/pyroscope/client.go`)
- Configuration → Spool claims: configures spool (evidence: `internal/config/config.go`)
- Configuration → Resource limits: sets limits (evidence: `internal/config/config.go`)
- Drain pass → Resource limits: enforces budgets (evidence: `internal/agent/drainer.go`)
- Window grouping → Aggregation keys: validates keys (evidence: `internal/aggregate/group.go`)
- Drain pass → Cardinality gate: limits label keys
- CLI runner → Prometheus metrics: creates registry (evidence: `internal/cli/cli.go`)
- Metrics endpoint → Prometheus metrics: serves metrics
