# threemammals/ocelot architecture

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

- Interactive diagram: https://gitdiagram.com/threemammals/ocelot
- Repository: https://github.com/threemammals/ocelot

## Overview

##### Project Type and Purpose
- Project Type: An API Gateway built as a series of ASP.NET Core middleware components.
- Purpose: To act as a unified entry point for microservices architectures. It routes, aggregates, transforms, and secures HTTP requests and responses between clients and multiple downstream services. It also supports additional features such as caching, rate limiting, load balancing, service discovery, and integration with logging/tracing systems.

##### File Structure
- The top-level directories (“src”, “samples”, “test”, “docs”, “docker”, “.github”, etc.) indicate a large, solution-oriented project with multiple assemblies.
- In “src” you see various projects:
– Core functionality under Ocelot (middleware, configuration, request handling, error handling, etc.).
– Provider integrations like Consul, Eureka, Kubernetes, Polly for resiliency, and tracing integrations (Butterfly, OpenTracing).
– A set of “Configuration” projects that build and validate Ocelot’s JSON (or file-based) configuration into the internal representation.
– Middleware pipelines for authentication, authorization, rate limiting, caching, header/query transformation, etc.
- The “samples” directory provides multiple usage examples (Basic, Configuration, Eureka, GraphQL, Kubernetes, ServiceDiscovery, ServiceFabric, Web) showing how Ocelot integrates with different technologies.
- The “test” directory holds unit, integration, and acceptance tests that validate the behavior of individual middlewares and pipelines.

##### README for Additional Insights
- The README clearly lays out the Ocelot pipeline as a sequence of ASP.NET Core middleware.
- It details key features such as Routing, Request Aggregation, authentication/authorization, caching, QoS, load balancing, service discovery, and logging/tracing.
- Modular pattern where each middleware is responsible for a transformation or function on the request or response, culminating in the delegation to the downstream service.

a. Main Components
– Client/Consumer:
- External clients sending HTTP/HTTPS requests.
– API Gateway (Ocelot):
- Entry Point Middleware Pipeline:
▪ Authentication Middleware (includes integration with IdentityServer or other token providers)
▪ Authorization Middleware (claim and scope based checks)
▪ Routing and Request Aggregation Middleware (decides how and where to route requests)
▪ Transformation Middleware (headers, queries, claims, etc.)
▪ Caching Middleware (output caching handling downstream responses)
▪ Rate Limiting Middleware (to throttle requests)
▪ Load Balancing Component (integrates with various balancing strategies such as Round Robin, Least Connection, Sticky Sessions)
▪ Quality of Service (QoS) using Polly policy integration for resilience
▪ Service Discovery Providers (to locate downstream services via Consul, Eureka, Kubernetes, Service Fabric, etc.)
▪ Request/Response Mediation (mapping HttpRequest to HttpRequestMessage, and vice versa)
▪ Logging/Tracing (tracing integration using Butterfly or OpenTracing middlewares)
– Downstream Services:
- Microservices that handle business logic. The gateway eventually routes requests to these services.
– Configuration Management:
- Ocelot’s configuration repository (file-based and/or dynamic via providers like Consul).
– Supporting Infrastructure:
- Dependency injection mechanism (via the Ocelot Builder and administration builder).
- Custom middleware and delegating handlers that can be injected or extended by users.

b. Relationships and Interactions
– Data flows from external clients into the API gateway.
– Within the gateway, the middleware pipeline sequentially transforms the request (authentication → authorization → routing/aggregation → caching → load balancing).
– The gateway then forms a proper HttpRequestMessage and communicates with one or more downstream services.
– The response flows back through the pipeline where output transformation (header, query, claims adjustments) and logging/tracing occurs.
– The configuration system and providers (like file repositories or dynamic sources from Consul/Eureka) feed into the pipeline setup.

c. Architectural Patterns and Design Principles
– Middleware Pattern: The core design relies on a chain of middleware components forming a pipeline.
– Dependency Injection: For injecting providers, handlers, and middleware components.
– Separation of Concerns: Different middleware handles routing, aggregation, rate limiting, caching, and error handling separately.
– Extensibility: Custom middleware and delegating handlers act as extension points.
– Resilience: Integrates with Polly for QoS and handles load balancing via multiple strategies.

d. Relevant Technologies, Frameworks, or Libraries
– ASP.NET Core (Middleware, DI, HTTP pipeline).
– Polly for resilience and QoS standards.
– Service Discovery libraries: Consul, Eureka, Kubernetes, Service Fabric.
– Logging/Tracing: Butterfly, OpenTracing.
– .NET multi-targeting practices (net8.0/net9.0 support)
– Docker for containerization and build scripts provided in the “docker” directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["External Client"]:::client

    subgraph "Infrastructure Layer"
        ConfigInfra["Configuration Management"]:::infra
        DIInfra["Dependency Injection & Administration"]:::infra
    end

    subgraph "API Gateway Layer"
        APIGateway["API Gateway Middleware Pipeline"]:::gateway
        Auth["Authentication Middleware"]:::middleware
        Authz["Authorization Middleware"]:::middleware
        Aggregation["Request Aggregation Middleware"]:::middleware
        Headers["Headers Transformation Middleware"]:::middleware
        Claims["Claims Transformation Middleware"]:::middleware
        Query["Query String Transformation Middleware"]:::middleware
        Cache["Caching Middleware"]:::middleware
        Rate["Rate Limiting Middleware"]:::middleware
        LB["Load Balancing Middleware"]:::middleware
        QoS["QoS/Resiliency (Polly)"]:::middleware
        Discovery["Service Discovery Providers"]:::external
        Logging["Logging & Tracing"]:::external
    end

    Downstream["Downstream Services (Microservices)"]:::service

    %% Request flow
    Client --> APIGateway
    ConfigInfra --> APIGateway
    DIInfra --> APIGateway
    APIGateway --> Auth
    Auth --> Authz
    Authz --> Aggregation
    Aggregation --> Headers
    Headers --> Claims
    Claims --> Query
    Query --> Cache
    Cache --> Rate
    Rate --> LB
    LB --> QoS
    QoS --> Discovery
    Discovery --> Logging
    Logging --> Downstream
    %% Response flow
    Downstream -->|"response"| APIGateway
    APIGateway -->|"response"| Client

    %% Click Events
    click APIGateway "https://github.com/threemammals/ocelot/tree/develop/src/Ocelot/Middleware"
    click Auth "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot/Authentication/Middleware/AuthenticationMiddleware.cs"
    click Authz "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot/Authorization/Middleware/AuthorizationMiddleware.cs"
    click Aggregation "https://github.com/threemammals/ocelot/tree/develop/src/Ocelot/Multiplexer"
    click Headers "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot/Headers/Middleware/HttpHeadersTransformationMiddleware.cs"
    click Claims "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot/Claims/Middleware/ClaimsToClaimsMiddleware.cs"
    click Query "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot/QueryStrings/Middleware/ClaimsToQueryStringMiddleware.cs"
    click Cache "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot/Cache/Middleware/OutputCacheMiddleware.cs"
    click Rate "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot/RateLimiting/Middleware/RateLimitingMiddleware.cs"
    click LB "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot/LoadBalancer/Middleware/LoadBalancingMiddleware.cs"
    click QoS "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot.Provider.Polly"
    click Discovery "https://github.com/threemammals/ocelot/blob/develop/src/Ocelot.Provider.Consul"
    click Logging "https://github.com/threemammals/ocelot/tree/develop/src/Ocelot/Tracing/Butterfly"
    click ConfigInfra "https://github.com/threemammals/ocelot/tree/develop/src/Ocelot/Configuration"
    click DIInfra "https://github.com/threemammals/ocelot/tree/develop/src/Ocelot/DependencyInjection"

    %% Styles
    classDef client fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef gateway fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef middleware fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef infra fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef service fill:#d1f2eb,stroke:#333,stroke-width:2px;
```
