# aspnet/benchmarks architecture

> Architecture diagram of the GitHub repository aspnet/benchmarks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aspnet/benchmarks
- Repository: https://github.com/aspnet/benchmarks

## Overview

##### Project type and purpose
- This is a performance-benchmarking toolset for ASP.NET Core, driven by Microsoft Crank, with many pre-built web app scenarios, network streaming tests, and database benchmarks.
- It is not a single full-stack application but rather a container-orchestrated benchmark harness.

##### File structure
- build/azurepipeline-*.yml & .github/workflows: CI definitions for building images and running benchmarks on Azure or GitHub Actions
- docker/: Dockerfiles & configs for proxies (Envoy, HAProxy, Nginx), databases (Postgres, MySQL, MongoDB, SQL Server, Redis), service-bus controller
- scenarios/: YAML scenario definitions consumed by Crank
- scripts/: helper scripts for pipelines or load tests
- src/Benchmarks: the core web harness (Controllers, Middleware, EF Core, Dapper, raw SQL)
- src/BenchmarksApps, src/System.Net.Benchmarks, src/TcpClient, src/WebsocketClient, etc.: individual micro-apps and clients for each scenario

##### README
- Confirms use of Microsoft Crank as orchestrator
- Scenarios are defined in scenarios/ and referenced in app-specific YAML files
- CI pipelines invoke these scenarios as part of continuous benchmarking

##### Main components and interactions
a. Build & CI layer
– GitHub Actions / Azure Pipelines (build/ & .github/workflows/)
– Produce Docker images for:
- Benchmark harness (src/Benchmarks)
- BenchmarkApps (various feature-specific web apps)
- Proxies & Databases (docker/)
- System.Net streaming servers & clients
– Push images to a container registry or keep locally
b. Orchestration layer
– Microsoft Crank CLI (invoked via scripts or CI jobs)
– Reads scenario definitions (.yml in scenarios/ and src/**/benchmarks.yml)
– Decides which containers to launch and their interconnections
c. Runtime / Docker layer
– Docker daemon (single host or multiple hosts)
– Containers by role:
- Clients (HttpClient, GRPC, System.Net streaming, WebsocketClient, TcpClient)
- Load-balancers & proxies (Envoy, HAProxy, Nginx)
- Servers (Kestrel-hosted ASP.NET apps from BenchmarksApps, System.Net servers, service-bus controller)
- Databases (Postgres, MySQL, MongoDB, SQL Server, Redis)
– All containers attached to a common network overlay
d. Metrics & results
– Crank collects performance counters, latencies, throughput
– Aggregates results into CSV, JSON, or publishes to Azure storage/Grafana

##### Architectural patterns and design principles
- Containerized micro-services: each test app or database runs in its own container
- Scenario-driven orchestration: YAML defines client-server-db topologies
- Separation of concerns: build pipelines vs runtime orchestration vs metrics collection
- Reusability: common Benchmark harness, shared Directory.Build.props / targets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Layer
    subgraph "CI/CD Layer"
        direction TB
        AzurePipelines["Azure Pipelines"]:::ci
        GitHubActions["GitHub Actions"]:::ci
        Registry["Image Registry"]:::ci
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Crank["Microsoft Crank CLI / scripts"]:::orch
        Scenarios["scenarios/*.yml"]:::orch
    end

    %% Runtime / Docker Host
    subgraph "Runtime / Docker Host"
        direction TB
        DockerDaemon["Docker Daemon"]:::runtime

        subgraph "Containers"
            direction TB

            subgraph "Load Generators"
                direction TB
                HttpClient["HttpClient"]:::client
                TcpClient["TcpClient"]:::client
                WSClient["WebSocketClient"]:::client
            end

            subgraph "Proxies"
                direction TB
                Envoy["Envoy"]:::proxy
                Nginx["Nginx"]:::proxy
                HAProxy["HAProxy"]:::proxy
            end

            subgraph "Servers"
                direction TB
                BenchHarness["Benchmark Harness"]:::server
                BenchApps["Benchmark Apps"]:::server
                NetBench["System.Net Benchmarks"]:::server
            end

            subgraph "Databases"
                direction TB
                Postgres["PostgreSQL"]:::db
                MySQL["MySQL"]:::db
                MongoDB["MongoDB"]:::db
                SQLServer["SQL Server"]:::db
                Redis["Redis"]:::db
                SBController["Service-Bus Controller"]:::db
            end
        end
    end

    %% Metrics
    MetricsSink["Metrics Sink (Azure Blob / Grafana)"]:::metrics

    %% Connections
    AzurePipelines -->|"build images"| Registry
    GitHubActions -->|"build images"| Registry
    Registry -->|"images available"| Crank
    Crank -->|"reads scenarios"| Scenarios
    Crank -->|"launch instructions"| DockerDaemon
    DockerDaemon -->|"runs containers"| HttpClient
    DockerDaemon --> HttpClient
    HttpClient -->|"requests"| Envoy
    Envoy -->|"forwards"| BenchHarness
    BenchHarness -->|"DB queries"| Postgres
    TcpClient -->|"requests"| HAProxy
    HAProxy -->|"forwards"| BenchApps
    BenchApps -->|"DB queries"| MySQL
    WSClient -->|"requests"| Nginx
    Nginx -->|"forwards"| NetBench
    NetBench -->|"DB queries"| MongoDB
    BenchHarness -->|"service bus calls"| SBController
    BenchApps -->|"cache ops"| Redis
    BenchHarness -->|"DB queries"| SQLServer

    HttpClient -->|"metrics⇢"| Crank
    TcpClient -->|"metrics⇢"| Crank
    WSClient -->|"metrics⇢"| Crank
    Envoy -->|"metrics⇢"| Crank
    HAProxy -->|"metrics⇢"| Crank
    Nginx -->|"metrics⇢"| Crank
    BenchHarness -->|"metrics⇢"| Crank
    BenchApps -->|"metrics⇢"| Crank
    NetBench -->|"metrics⇢"| Crank
    Postgres -->|"metrics⇢"| Crank
    MySQL -->|"metrics⇢"| Crank
    MongoDB -->|"metrics⇢"| Crank
    SQLServer -->|"metrics⇢"| Crank
    Redis -->|"metrics⇢"| Crank
    SBController -->|"metrics⇢"| Crank

    Crank -->|"outputs results"| MetricsSink

    %% Click Events
    click AzurePipelines "https://github.com/aspnet/benchmarks/tree/main/build/"
    click GitHubActions "https://github.com/aspnet/benchmarks/blob/main/.github/workflows/build.yml"
    click Crank "https://github.com/aspnet/benchmarks/tree/main/scripts/"
    click Scenarios "https://github.com/aspnet/benchmarks/tree/main/scenarios/"
    click HttpClient "https://github.com/aspnet/benchmarks/tree/main/src/BenchmarksApps/"
    click TcpClient "https://github.com/aspnet/benchmarks/tree/main/src/TcpClient/"
    click WSClient "https://github.com/aspnet/benchmarks/tree/main/src/WebsocketClient/"
    click BenchHarness "https://github.com/aspnet/benchmarks/tree/main/src/Benchmarks/"
    click BenchApps "https://github.com/aspnet/benchmarks/tree/main/src/BenchmarksApps/"
    click NetBench "https://github.com/aspnet/benchmarks/tree/main/src/System/Net/Benchmarks/"
    click Envoy "https://github.com/aspnet/benchmarks/tree/main/docker/envoy/"
    click Nginx "https://github.com/aspnet/benchmarks/tree/main/docker/nginx/"
    click HAProxy "https://github.com/aspnet/benchmarks/tree/main/docker/haproxy/"
    click Postgres "https://github.com/aspnet/benchmarks/tree/main/docker/postgres-techempower/"
    click MySQL "https://github.com/aspnet/benchmarks/tree/main/docker/mysql-techempower/"
    click MongoDB "https://github.com/aspnet/benchmarks/tree/main/docker/mongodb-techempower/"
    click SQLServer "https://github.com/aspnet/benchmarks/tree/main/docker/mssql-techempower/"
    click Redis "https://github.com/aspnet/benchmarks/tree/main/docker/redis/"
    click SBController "https://github.com/aspnet/benchmarks/tree/main/docker/servicebus-controller/"

    %% Styles
    classDef ci fill:#D6EFFF,stroke:#0366d6,stroke-dasharray:5 5
    classDef orch fill:#FFF5B1,stroke:#D09E2A
    classDef runtime fill:#F0F0F0,stroke:#999999
    classDef client fill:#FFD8B5,stroke:#E76F00
    classDef proxy fill:#E5D4ED,stroke:#914EBD
    classDef server fill:#FFD8B5,stroke:#E76F00
    classDef db fill:#DFF2BF,stroke:#4F8A10
    classDef metrics fill:#E5E5E5,stroke:#666666,stroke-dasharray:2 2
```
