# alexspx/oxidegate architecture

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

- Interactive diagram: https://gitdiagram.com/alexspx/oxidegate
- Repository: https://github.com/alexspx/oxidegate

## Overview

##### Project type and purpose
- OxideGate is a cloud-native, high-performance reverse proxy written in Rust.
- It accepts HTTP/1.1 and HTTP/2 client requests, applies routing and load-balancing logic, and forwards requests to backend services.
- Key features: asynchronous I/O (Tokio), HTTP server (hyper), configurable routing, multiple load-balancing algorithms.

##### File structure
- Top-level:
- Cargo.toml, Cargo.lock – Rust package definition.
- dockerfile – container build.
- k6/ – performance test script.
- src/ – application source.
- tests/ – unit tests for load-balancer.
- src/ breakdown:
- config.rs – loads and validates the TOML configuration.
- lib.rs – library entry points and shared types (types.rs).
- main.rs – application bootstrap (reads config, starts servers).
- load_balancer/ – implementations of RoundRobin, LeastConnections, WeightedRoundRobin.
- proxy_service/ – core HTTP proxy logic:
– gateway_body.rs – body handling
– proxy_bridge.rs – connects client and backend streams
– proxy_handler.rs – request/response routing handler
- server/ – server lifecycle management:
– http.rs, https.rs – hyper server setup
– server_manager.rs – spawns listeners, handles shutdown
- tests/load_balancer.rs – verifies each LB algorithm.

##### README for additional insights
- Configurable via environment variable CONFIG_FILE referencing a TOML.
- Sections: server, frontends, backends, LB algorithms.
- Example config shows how path_prefixes and backend servers map.

a. Main components
1. External Clients – HTTP/1.1 and HTTP/2 requests.
2. OxideGate Proxy
- Configuration Loader (config.rs)
- Server Manager (server_manager.rs)
- HTTP Listener (http.rs) / HTTPS Listener (https.rs)
- Proxy Service
‑ Proxy Handler
‑ Proxy Bridge
‑ Gateway Body
- Load-Balancer Module
‑ RoundRobin
‑ LeastConnections
‑ WeightedRoundRobin
3. Backend Services – one or more HTTP servers (any implementation).
4. k6 Tester (optional) – simulates load.
b. Relationships and interactions
- Clients send requests → Server Manager routes to HTTP/HTTPS Listener.
- Listener forwards incoming requests to Proxy Handler.
- Proxy Handler consults Configuration to identify which backend and LB algorithm.
- Load-Balancer picks a backend server instance.
- Proxy Bridge opens connection to that backend and streams data (gateway_body).
- Responses flow back along the same chain to the client.
- Tests (k6) target the public proxy endpoint.
c. Architectural patterns and principles
- Modular separation: configuration, server orchestration, HTTP transport, proxy logic, load-balancing.
- Strategy pattern for LB algorithms: interchangeable implementations behind a common trait.
- Asynchronous event-driven design via Tokio and hyper.
d. Key technologies
- Rust (Cargo, Tokio, hyper)
- TOML config loader (serde)
- Docker for containerization
- k6 for performance testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Client["External Client\n(HTTP/1.1, HTTP/2)"]:::external
    k6["k6 Tester"]:::external
    Backend["Backend Service"]:::external

    %% Configuration File
    ConfigFile[(TOML Config File)]:::config

    %% Docker Container Boundary
    subgraph "Docker Container" 
        direction TB

        %% Configuration Loader
        ConfigLoader["Configuration Loader"]:::config
        ServerManager["Server Manager"]:::network

        %% Listeners
        HTTPListener["HTTP Listener\n(port 3000)"]:::network
        HTTPSListener["HTTPS Listener\n(port 3001)"]:::network

        %% Proxy Service
        subgraph "Proxy Service" 
            direction TB
            ProxyHandler["Proxy Handler"]:::network
            ProxyBridge["Proxy Bridge"]:::network
            GatewayBody["Gateway Body"]:::network
        end

        %% Load Balancer Module
        subgraph "Load Balancer Module" 
            direction TB
            LBFactory["LB Factory & Module Entry"]:::algo
            RoundRobin["Round Robin"]:::algo
            LeastConn["Least Connections"]:::algo
            WeightedRR["Weighted Round Robin"]:::algo
        end
    end

    %% Connections
    Client -->|"HTTP request"| ServerManager
    k6 -->|"Load Test"| Client
    ServerManager -->|spawns listener| HTTPListener
    ServerManager -->|spawns listener| HTTPSListener
    HTTPListener -->|"forward request"| ProxyHandler
    HTTPSListener -->|"forward request"| ProxyHandler
    ProxyHandler -->|"load config"| ConfigLoader
    ConfigFile -->|"TOML parse"| ConfigLoader
    ProxyHandler -->|"select backend"| LBFactory
    LBFactory -->|"uses strategy"| RoundRobin
    LBFactory -->|"uses strategy"| LeastConn
    LBFactory -->|"uses strategy"| WeightedRR
    LBFactory -->|pick instance| ProxyBridge
    ProxyBridge -->|stream data via| GatewayBody
    ProxyBridge -->|"connect"| Backend
    Backend -->|"response"| ProxyBridge
    ProxyBridge -->|"response"| ProxyHandler
    ProxyHandler -->|"reply"| Client

    %% Legend
    subgraph "Legend"
        direction TB
        L1["Process Component"]:::process
        L2["Network Layer"]:::network
        L3["Algorithm Module"]:::algo
        L4["Configuration"]:::config
        L5["External/System"]:::external
    end

    %% Styles
    classDef network fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef algo fill:#E6FFEA,stroke:#28a745,color:#28a745;
    classDef config fill:#FFF4D6,stroke:#DBAB09,color:#DBAB09;
    classDef external fill:#F0F0F0,stroke:#666666,color:#333333;
    classDef process fill:#FFFFFF,stroke:#000000,color:#000000;

    %% Click Events
    click ConfigLoader "https://github.com/alexspx/oxidegate/blob/main/src/config.rs"
    click ServerManager "https://github.com/alexspx/oxidegate/blob/main/src/server/server_manager.rs"
    click HTTPListener "https://github.com/alexspx/oxidegate/blob/main/src/server/http.rs"
    click HTTPSListener "https://github.com/alexspx/oxidegate/blob/main/src/server/https.rs"
    click ProxyHandler "https://github.com/alexspx/oxidegate/blob/main/src/proxy_service/proxy_handler.rs"
    click ProxyBridge "https://github.com/alexspx/oxidegate/blob/main/src/proxy_service/proxy_bridge.rs"
    click GatewayBody "https://github.com/alexspx/oxidegate/blob/main/src/proxy_service/gateway_body.rs"
    click RoundRobin "https://github.com/alexspx/oxidegate/blob/main/src/load_balancer/round_robin_lb.rs"
    click LeastConn "https://github.com/alexspx/oxidegate/blob/main/src/load_balancer/least_connections_lb.rs"
    click WeightedRR "https://github.com/alexspx/oxidegate/blob/main/src/load_balancer/weighted_round_robin_lb.rs"
    click LBFactory "https://github.com/alexspx/oxidegate/blob/main/src/load_balancer/factory.rs"
    click LBFactory "https://github.com/alexspx/oxidegate/blob/main/src/load_balancer/mod.rs"
    click k6 "https://github.com/alexspx/oxidegate/blob/main/k6/script.js"
    click Backend "https://github.com/alexspx/oxidegate/blob/main/tests/load_balancer.rs"
    click ConfigFile "https://github.com/alexspx/oxidegate/blob/main/README.md"
    click ConfigFile "https://github.com/alexspx/oxidegate/blob/main/Cargo.toml"
    click ConfigFile "https://github.com/alexspx/oxidegate/blob/main/Cargo.lock"
```
