# dotnet/yarp architecture

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

- Interactive diagram: https://gitdiagram.com/dotnet/yarp
- Repository: https://github.com/dotnet/yarp

## Overview

##### Project Type and Purpose
- YARP (“Yet Another Reverse Proxy”) is a .NET-based reverse proxy toolkit/library plus a reference ASP.NET Core host and a Kubernetes ingress controller.
- It ships as reusable components (NuGet libraries and project templates) to build highly customizable proxy servers, and includes:
- Core ReverseProxy library (src/ReverseProxy)
- Kubernetes ingress controller (src/Kubernetes.Controller)
- Telemetry/event‐listener library (src/TelemetryConsumption)
- A CLI host/app (src/Application)
- Sample apps and end-to-end tests under samples/ and test/

##### High-level File Structure & Architectural Patterns
- src/ReverseProxy
- Configuration: providers, validators, in-memory snapshot
- Management: ProxyConfigManager, builder extensions
- Routing: endpoint factory, match policies
- Transforms: request/response pipeline enrichment
- SessionAffinity, LoadBalancing, Health, Limits, Delegation, ServiceDiscovery, Utilities, WebSocketsTelemetry
- Forwarder: HttpForwarder middleware using HttpClient
- Model: in-memory representation of clusters/routes
- src/Kubernetes.Controller
- Watches Kubernetes API (via ResourceInformer, informers)
- Converts Ingress resources to YARP config (YarpParser)
- Runs as a background hosted service in ASP.NET Core
- src/TelemetryConsumption
- Listens to .NET EventSources (Forwarder, Http, Kestrel, WebSockets, etc.)
- Exposes consumable metrics for Prometheus or custom sinks
- src/Application
- A console/ASP.NET Core host wiring up the ReverseProxy and optional Kubernetes controller or telemetry modules
- Integration with ASP.NET Core’s IEndpointRouteBuilder and middleware pipeline (IReverseProxyApplicationBuilder)

- ASP.NET Core Host (Program.cs / Generic Host)
- Configuration Providers
- Appsettings.json / InMemoryConfigProvider
- KubernetesConfigProvider (if running controller)
- ProxyConfigManager / Management Layer
- ReverseProxy Pipeline
- Routing Middleware
- Transform Middleware
- SessionAffinity Middleware
- LoadBalancing Middleware
- HealthCheck Middleware
- Limits Middleware
- Delegation Middleware
- Forwarder Middleware (HttpForwarder → HttpClient)
- ServiceDiscovery (DNS / Custom resolvers)
- Backend Clusters / Destinations (external services)
- Kubernetes API Server (for the controller)
- TelemetryConsumers (EventListenerService modules)
- Prometheus / External Metrics Store (optional)
- Host → loads Configuration → feeds ProxyConfigManager
- ProxyConfigManager → (on change) → updates in-memory Model
- Host → attaches ReverseProxy pipeline into ASP.NET Core request loop
- Incoming HTTP Request → Routing → Transforms → SessionAffinity → LoadBalancing → HealthCheck → Limits → Delegation → Forwarder → Backend
- Forwarder → uses HttpClientFactory → outbound HTTP to Destination
- Kubernetes Controller (sidecar or integrated) → watches K8s API → sends translated config into ProxyConfigManager
- TelemetryConsumers → subscribe to EventSources from Forwarder, Kestrel, WebSockets → emit metrics to Prometheus/console
c. Architectural Patterns & Principles:
- Modular middleware pipeline (ASP.NET Core style)
- In-memory dynamic configuration with change notifications
- Strategy patterns for load‐balancing, health, session affinity, transforms
- Separation of concerns: Config → Model → Pipeline → Forwarding
- Observer pattern: EventSource → TelemetryConsumers
- Adapter for Kubernetes CRDs → YARP config
d. Key Technologies & Frameworks:
- .NET 6+ Generic Host / ASP.NET Core
- Microsoft.ReverseProxy libraries
- Kubernetes .NET client (informers)
- System.Net.Http.HttpClient / HttpClientFactory
- EventSource / DiagnosticSource

##### Final Advice
- Control-plane (config, K8s controller) separately from data-plane (request pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane"
        A[ASP.NET Core Host]:::config
        B[Configuration Providers]:::config
        SD[ServiceDiscovery]:::core
        C[ProxyConfigManager]:::config
        D[In-Memory Model]:::config
        A -->|wires up| B
        B -->|provides config| C
        C -->|updates model| D
        C -->|uses| SD

        subgraph "Kubernetes Controller"
            IK[K8s Informers]:::config
            KP[KubernetesConfigProvider]:::config
            YP[YarpParser]:::config
            HS[BackgroundHostedService]:::config
            IK --> KP
            KP --> YP
            YP --> C
            HS -->|runs| IK
        end
    end

    %% Data Plane
    subgraph "Data Plane"
        Req[Incoming HTTP Request]:::external
        M1[Routing Middleware]:::core
        M2[Transform Middleware]:::core
        M3[SessionAffinity Middleware]:::core
        M4[LoadBalancing Middleware]:::core
        M5[HealthCheck Middleware]:::core
        M6[Limits Middleware]:::core
        M7[Delegation Middleware]:::core
        M8[Forwarder Middleware]:::core
        Out[Backend Clusters]:::external

        Req --> M1 --> M2 --> M3 --> M4 --> M5 --> M6 --> M7 --> M8 --> Out
    end

    %% Observability
    subgraph "Observability"
        TC[TelemetryConsumption Library]:::telemetry
        E1[ForwarderEventListenerService]:::telemetry
        E2[HttpEventListenerService]:::telemetry
        E3[KestrelEventListenerService]:::telemetry
        E4[WebSocketsEventListenerService]:::telemetry
        E5[NameResolutionEventListenerService]:::telemetry
        E6[NetSecurityEventListenerService]:::telemetry
        E7[SocketsEventListenerService]:::telemetry
        Metrics[Prometheus / External Metrics]:::external

        TC --> E1
        TC --> E2
        TC --> E3
        TC --> E4
        TC --> E5
        TC --> E6
        TC --> E7

        M8 -->|EventSources| E1
        Req -->|EventSources| E2
        E1 --> Metrics
        E2 --> Metrics
        E3 --> Metrics
        E4 --> Metrics
        E5 --> Metrics
        E6 --> Metrics
        E7 --> Metrics
    end

    %% Click Events
    click A "https://github.com/dotnet/yarp/blob/main/src/Application/Program.cs"
    click B "https://github.com/dotnet/yarp/tree/main/src/ReverseProxy/Configuration"
    click SD "https://github.com/dotnet/yarp/blob/main/src/ReverseProxy/ServiceDiscovery/DnsDestinationResolver.cs"
    click C "https://github.com/dotnet/yarp/blob/main/src/ReverseProxy/Management/ProxyConfigManager.cs"
    click M1 "https://github.com/dotnet/yarp/blob/main/src/ReverseProxy/Routing/ProxyEndpointFactory.cs"
    click M2 "https://github.com/dotnet/yarp/tree/main/src/ReverseProxy/Transforms/Builder"
    click M3 "https://github.com/dotnet/yarp/tree/main/src/ReverseProxy/SessionAffinity"
    click M4 "https://github.com/dotnet/yarp/tree/main/src/ReverseProxy/LoadBalancing"
    click M5 "https://github.com/dotnet/yarp/tree/main/src/ReverseProxy/Health"
    click M6 "https://github.com/dotnet/yarp/blob/main/src/ReverseProxy/Limits/LimitsMiddleware.cs"
    click M7 "https://github.com/dotnet/yarp/blob/main/src/ReverseProxy/Delegation/HttpSysDelegatorMiddleware.cs"
    click M8 "https://github.com/dotnet/yarp/tree/main/src/ReverseProxy/Forwarder"
    click IK "https://github.com/dotnet/yarp/tree/main/src/Kubernetes.Controller/Client"
    click KP "https://github.com/dotnet/yarp/blob/main/src/Kubernetes.Controller/ConfigProvider/KubernetesConfigProvider.cs"
    click YP "https://github.com/dotnet/yarp/blob/main/src/Kubernetes.Controller/Converters/YarpParser.cs"
    click HS "https://github.com/dotnet/yarp/blob/main/src/Kubernetes.Controller/Hosting/BackgroundHostedService.cs"
    click TC "https://github.com/dotnet/yarp/tree/main/src/TelemetryConsumption"
    click E1 "https://github.com/dotnet/yarp/blob/main/src/TelemetryConsumption/Forwarder/ForwarderEventListenerService.cs"
    click E2 "https://github.com/dotnet/yarp/blob/main/src/TelemetryConsumption/Http/HttpEventListenerService.cs"
    click E3 "https://github.com/dotnet/yarp/blob/main/src/TelemetryConsumption/Kestrel/KestrelEventListenerService.cs"
    click E4 "https://github.com/dotnet/yarp/blob/main/src/TelemetryConsumption/WebSockets/WebSocketsEventListenerService.cs"
    click E5 "https://github.com/dotnet/yarp/blob/main/src/TelemetryConsumption/NameResolution/NameResolutionEventListenerService.cs"
    click E6 "https://github.com/dotnet/yarp/blob/main/src/TelemetryConsumption/NetSecurity/NetSecurityEventListenerService.cs"
    click E7 "https://github.com/dotnet/yarp/blob/main/src/TelemetryConsumption/Sockets/SocketsEventListenerService.cs"

    %% Styles
    classDef core fill:#ccf,stroke:#333,stroke-width:1px;
    classDef config fill:#cfc,stroke:#333,stroke-width:1px;
    classDef telemetry fill:#fc9,stroke:#333,stroke-width:1px;
    classDef external fill:#ddd,stroke:#333,stroke-width:1px;
```
