# codingbrushup2/performance-agent architecture

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

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

## Overview

Performance Agent measures .NET benchmarks, compares baseline and candidate evidence against explicit budgets, and emits deterministic PASS, FAIL, or INCONCLUSIVE results. The CLI also supports run history, calibration, readiness and changed-code hints, reports, a local web UI, and optional advisory AI analysis. The benchmark host and core algorithms are represented from excerpts and the source index; unsampled subsystem internals and some CLI wiring are not inferred.

Main entry points: [`apps/cli/PerformanceAgent.Cli/Program.cs`](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/Program.cs) (CLI commands), [`apps/benchmark-host/PerformanceAgent.BenchmarkHost/Program.cs`](https://github.com/codingbrushup2/performance-agent/blob/main/apps/benchmark-host/PerformanceAgent.BenchmarkHost/Program.cs) (Benchmark host), [`apps/cli/PerformanceAgent.Cli/RegressionCheckService.cs`](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/RegressionCheckService.cs) (Regression check), [`apps/cli/PerformanceAgent.Cli/ProjectRunner.cs`](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/ProjectRunner.cs) (Project runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli_app["CLI commands<br/>[Program.cs]"]
  node_project_run["Project runner<br/>[ProjectRunner.cs]"]
  node_changed_code["Changed-code hints"]
  node_readiness["Experiment readiness"]
  node_workspace[("Workspace state")]
end

subgraph group_measure["Benchmark measurement"]
  node_bench_host["Benchmark host<br/>[Program.cs]"]
  node_bdn_runner["BenchmarkDotNet runner"]
  node_bdn_validator["Benchmark validity"]
end

subgraph group_decision["Evidence and verdicts"]
  node_evidence["Benchmark evidence"]
  node_evidence_io["Evidence JSON"]
  node_check_service["Regression check"]
  node_budget_check["Budget comparison"]
  node_quality["Confidence evaluation"]
  node_verdict["Verdict"]
end

subgraph group_history["History and baselines"]
  node_archive[("Run archive<br/>[FileRunArchive.cs]")]
  node_baseline_store[("Baseline selection")]
  node_calibration["Calibration"]
end

subgraph group_insights["Reports and insights"]
  node_reporting["Report writers<br/>[Reporting]"]
  node_web_ui["Local web UI<br/>[LocalWebUi.cs]"]
  node_analysis_service["Advisory analysis"]
  node_ai_provider["OpenAI provider"]
end

node_developer(("Developer / CI"))

node_developer -->|"runs commands"| node_cli_app
node_cli_app -->|"starts benchmark"| node_project_run
node_project_run -->|"launches process"| node_bench_host
node_bench_host -->|"runs benchmarks"| node_bdn_runner
node_bench_host -->|"validates benchmarks"| node_bdn_validator
node_bdn_runner -->|"produces measurements"| node_evidence
node_bench_host -->|"writes evidence"| node_evidence_io
node_cli_app -->|"reads evidence"| node_evidence_io
node_cli_app -->|"checks regression"| node_check_service
node_check_service -->|"checks budgets"| node_budget_check
node_check_service -->|"evaluates confidence"| node_quality
node_check_service -->|"assigns verdict"| node_verdict
node_cli_app -->|"archives runs"| node_archive
node_cli_app -->|"selects baseline"| node_baseline_store
node_cli_app -->|"calibrates runs"| node_calibration
node_cli_app -->|"finds changed members"| node_changed_code
node_cli_app -->|"checks readiness"| node_readiness
node_cli_app -->|"generates reports"| node_reporting
node_cli_app -->|"serves local UI"| node_web_ui
node_cli_app -->|"resolves state"| node_workspace
node_cli_app -.->|"requests analysis"| node_analysis_service
node_analysis_service -->|"delegates analysis"| node_ai_provider
node_ai_provider -.->|"explains evidence"| node_evidence

click node_cli_app "https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/Program.cs"
click node_project_run "https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/ProjectRunner.cs"
click node_bench_host "https://github.com/codingbrushup2/performance-agent/blob/main/apps/benchmark-host/PerformanceAgent.BenchmarkHost/Program.cs"
click node_bdn_runner "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.BenchmarkDotNet/BenchmarkDotNetRunner.cs"
click node_bdn_validator "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.BenchmarkDotNet/BenchmarkDotNetValidator.cs"
click node_changed_code "https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/GitDiffCandidateService.cs"
click node_readiness "https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/ExperimentReadinessService.cs"
click node_evidence "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Evidence/BenchmarkEvidence.cs"
click node_evidence_io "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Evidence/JsonBenchmarkEvidenceReader.cs"
click node_check_service "https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/RegressionCheckService.cs"
click node_budget_check "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Budgets/PerformanceBudgetChecker.cs"
click node_quality "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Quality/MeanDecisionQualityEvaluator.cs"
click node_verdict "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Verdicts/PerformanceVerdict.cs"
click node_archive "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/History/FileRunArchive.cs"
click node_baseline_store "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/History/FileBaselineStore.cs"
click node_calibration "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Calibration/CalibrationAnalyzer.cs"
click node_reporting "https://github.com/codingbrushup2/performance-agent/tree/main/src/PerformanceAgent.Core/Reporting"
click node_web_ui "https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/LocalWebUi.cs"
click node_analysis_service "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Analysis/PerformanceAnalysisService.cs"
click node_ai_provider "https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.AI/OpenAIPerformanceAnalysisProvider.cs"
click node_workspace "https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/WorkspaceStorage.cs"

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_cli_app,node_project_run,node_changed_code,node_readiness,node_workspace toneBlue
class node_bench_host,node_bdn_runner,node_bdn_validator toneAmber
class node_evidence,node_evidence_io,node_check_service,node_budget_check,node_quality,node_verdict toneMint
class node_archive,node_baseline_store,node_calibration toneRose
class node_reporting,node_web_ui,node_analysis_service,node_ai_provider,node_developer toneIndigo
```

## Components

### CLI workflows

- [CLI commands](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/Program.cs): `apps/cli/PerformanceAgent.Cli/Program.cs`
- [Project runner](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/ProjectRunner.cs): `apps/cli/PerformanceAgent.Cli/ProjectRunner.cs`
- [Changed-code hints](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/GitDiffCandidateService.cs): `apps/cli/PerformanceAgent.Cli/GitDiffCandidateService.cs`
- [Experiment readiness](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/ExperimentReadinessService.cs): `apps/cli/PerformanceAgent.Cli/ExperimentReadinessService.cs`
- [Workspace state](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/WorkspaceStorage.cs): `apps/cli/PerformanceAgent.Cli/WorkspaceStorage.cs`

### Benchmark measurement

- [Benchmark host](https://github.com/codingbrushup2/performance-agent/blob/main/apps/benchmark-host/PerformanceAgent.BenchmarkHost/Program.cs): `apps/benchmark-host/PerformanceAgent.BenchmarkHost/Program.cs`
- [BenchmarkDotNet runner](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.BenchmarkDotNet/BenchmarkDotNetRunner.cs): `src/PerformanceAgent.BenchmarkDotNet/BenchmarkDotNetRunner.cs`
- [Benchmark validity](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.BenchmarkDotNet/BenchmarkDotNetValidator.cs): `src/PerformanceAgent.BenchmarkDotNet/BenchmarkDotNetValidator.cs`

### Evidence and verdicts

- [Benchmark evidence](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Evidence/BenchmarkEvidence.cs): `src/PerformanceAgent.Core/Evidence/BenchmarkEvidence.cs`
- [Evidence JSON](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Evidence/JsonBenchmarkEvidenceReader.cs): `src/PerformanceAgent.Core/Evidence/JsonBenchmarkEvidenceReader.cs`
- [Regression check](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/RegressionCheckService.cs): `apps/cli/PerformanceAgent.Cli/RegressionCheckService.cs`
- [Budget comparison](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Budgets/PerformanceBudgetChecker.cs): `src/PerformanceAgent.Core/Budgets/PerformanceBudgetChecker.cs`
- [Confidence evaluation](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Quality/MeanDecisionQualityEvaluator.cs): `src/PerformanceAgent.Core/Quality/MeanDecisionQualityEvaluator.cs`
- [Verdict](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Verdicts/PerformanceVerdict.cs): `src/PerformanceAgent.Core/Verdicts/PerformanceVerdict.cs`

### History and baselines

- [Run archive](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/History/FileRunArchive.cs): `src/PerformanceAgent.Core/History/FileRunArchive.cs`
- [Baseline selection](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/History/FileBaselineStore.cs): `src/PerformanceAgent.Core/History/FileBaselineStore.cs`
- [Calibration](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Calibration/CalibrationAnalyzer.cs): `src/PerformanceAgent.Core/Calibration/CalibrationAnalyzer.cs`

### Reports and insights

- [Report writers](https://github.com/codingbrushup2/performance-agent/tree/main/src/PerformanceAgent.Core/Reporting): `src/PerformanceAgent.Core/Reporting`
- [Local web UI](https://github.com/codingbrushup2/performance-agent/blob/main/apps/cli/PerformanceAgent.Cli/LocalWebUi.cs): `apps/cli/PerformanceAgent.Cli/LocalWebUi.cs`
- [Advisory analysis](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.Core/Analysis/PerformanceAnalysisService.cs): `src/PerformanceAgent.Core/Analysis/PerformanceAnalysisService.cs`
- [OpenAI provider](https://github.com/codingbrushup2/performance-agent/blob/main/src/PerformanceAgent.AI/OpenAIPerformanceAnalysisProvider.cs): `src/PerformanceAgent.AI/OpenAIPerformanceAnalysisProvider.cs`

### Other components

- **Developer / CI**

## Connections

- Developer / CI → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Project runner: starts benchmark (evidence: `apps/cli/PerformanceAgent.Cli/Program.cs`)
- Project runner → Benchmark host: launches process (evidence: `README.md`)
- Benchmark host → BenchmarkDotNet runner: runs benchmarks (evidence: `apps/benchmark-host/PerformanceAgent.BenchmarkHost/Program.cs`)
- Benchmark host → Benchmark validity: validates benchmarks (evidence: `apps/benchmark-host/PerformanceAgent.BenchmarkHost/Program.cs`)
- BenchmarkDotNet runner → Benchmark evidence: produces measurements (evidence: `apps/benchmark-host/PerformanceAgent.BenchmarkHost/Program.cs`)
- Benchmark host → Evidence JSON: writes evidence (evidence: `apps/benchmark-host/PerformanceAgent.BenchmarkHost/Program.cs`)
- CLI commands → Evidence JSON: reads evidence (evidence: `apps/cli/PerformanceAgent.Cli/Program.cs`)
- CLI commands → Regression check: checks regression (evidence: `apps/cli/PerformanceAgent.Cli/Program.cs`)
- Regression check → Budget comparison: checks budgets (evidence: `apps/cli/PerformanceAgent.Cli/RegressionCheckService.cs`)
- Regression check → Confidence evaluation: evaluates confidence (evidence: `apps/cli/PerformanceAgent.Cli/RegressionCheckService.cs`)
- Regression check → Verdict: assigns verdict (evidence: `apps/cli/PerformanceAgent.Cli/RegressionCheckService.cs`)
- CLI commands → Run archive: archives runs (evidence: `apps/cli/PerformanceAgent.Cli/Program.cs`)
- CLI commands → Baseline selection: selects baseline (evidence: `apps/cli/PerformanceAgent.Cli/Program.cs`)
- CLI commands → Calibration: calibrates runs (evidence: `README.md`)
- CLI commands → Changed-code hints: finds changed members (evidence: `apps/cli/PerformanceAgent.Cli/Program.cs`)
- CLI commands → Experiment readiness: checks readiness (evidence: `apps/cli/PerformanceAgent.Cli/Program.cs`)
- CLI commands → Report writers: generates reports (evidence: `README.md`)
- CLI commands → Local web UI: serves local UI (evidence: `README.md`)
- CLI commands → Workspace state: resolves state (evidence: `apps/cli/PerformanceAgent.Cli/WorkspaceStorage.cs`)
- CLI commands → Advisory analysis: requests analysis
- Advisory analysis → OpenAI provider: delegates analysis (evidence: `src/PerformanceAgent.Core/Analysis/PerformanceAnalysisService.cs`)
- OpenAI provider → Benchmark evidence: explains evidence (evidence: `README.md`)
