# git-clone-abhinav/load-balancer architecture

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

- Interactive diagram: https://gitdiagram.com/git-clone-abhinav/load-balancer
- Repository: https://github.com/git-clone-abhinav/load-balancer

## Overview

The project is an HTTP load balancer built in Go, designed to distribute incoming requests among a list of primary RPC endpoints and, if necessary, fallback RPC endpoints. It incorporates a caching mechanism (using a 2Q in-memory strategy) to temporarily blacklist endpoints returning “429 Too Many Requests” responses, and it includes a Slack notification system to alert when all endpoints are down. Additionally, the project is containerized using Docker and orchestrated with Docker Compose, reflecting a production-ready deployment environment.

##### Main Components
- HTTP Server: The point where the load balancer listens for incoming HTTP requests.
- Load Balancer Logic: The core functionality that handles request forwarding. It implements the randomized round-robin strategy for selecting primary RPC endpoints and secondary fallback endpoints.
- RPC Endpoints: Two distinct collections – the primary endpoints and the fallback endpoints – to which the load balancer forwards requests.
- Caching Mechanism: An in-memory (2Q) cache that stores endpoints flagged with “429 Too Many Requests” status to avoid immediate retry.
- Slack Notification Module: Sends alerts through Slack when all endpoint options have been exhausted.
- Environment Configuration: The use of the `.env` file to load configuration parameters (RPC URLs, port, TTL, Slack webhook URL, etc.).
- Docker Infrastructure: Components for containerization including the Dockerfile (with multi-stage builds) and docker-compose.yml for service orchestration.
- Platform-Specific Binaries: The pre-built binaries in the bin/ directory (for Linux, macOS, Windows) indicating cross-platform support.

- Within Load Balancer Logic:
a. Branching to the primary RPC endpoints list.
- Configuration loading (from the .env file) feeding into the initialization of both the Load Balancer Logic and caching modules.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly delineate between the request handling (HTTP server) and the logic for load balancing, error handling (429 responses), and notifications.
- Failover and Fallback: Emphasize the decision flow between primary and fallback endpoint lists.
- Caching for Resiliency: Highlight the caching mechanism that prevents overload on endpoints triggering rate-limiting.
- Containerization: Incorporate Docker build stages showing the environment takeover for efficient production deployment.

##### Technologies and Tools
- Programming Language: Go.
- Containerization: Docker and Docker Compose.
- Notification: Slack API.
- In-Memory Database: Custom or library-based implementation of a Two-Queue (2Q) caching algorithm.
- Build Tools: go.mod, go.sum, and build scripts (build.sh).

##### Final Recommendations
- Initialization or configuration (like loading the .env file) is mentioned as part of the startup process.
- Avoid overcomplication: list all components, but arrange them logically, focusing on their interconnections.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Application Components
    subgraph "Core Application"
        F["Environment Configuration (.env)"]:::config
        A["HTTP Server & Load Balancer Logic"]:::backend
        B["Primary RPC Endpoints"]:::rpc
        C["Fallback RPC Endpoints"]:::rpc
        D["Cache Mechanism (2Q)"]:::cache
        E["Slack Notification"]:::notification
    end

    %% Deployment Environment Components
    subgraph "Deployment Environment"
        I["Build Tools (build.sh, go.mod, go.sum)"]:::deployment
        G1["Dockerfile"]:::deployment
        G2["docker-compose.yml"]:::deployment
        H["Platform-Specific Binaries"]:::deployment
    end

    %% Data Flow Connections in Core Application
    F -->|"loads"| A
    A -->|"forwards"| B
    A -->|"fallback"| C
    A -->|"on429"| D
    A -->|"alert"| E

    %% Deployment Relationships
    I -->|"builds using"| G1
    I -->|"builds using"| G2
    G1 -->|"containerizes"| A
    G2 -->|"orchestrates"| A
    H --- A

    %% Click Events based on Component Mapping
    click A "https://github.com/git-clone-abhinav/load-balancer/blob/master/main.go"
    click G1 "https://github.com/git-clone-abhinav/load-balancer/tree/master/Dockerfile"
    click G2 "https://github.com/git-clone-abhinav/load-balancer/blob/master/docker-compose.yml"
    click H "https://github.com/git-clone-abhinav/load-balancer/tree/master/bin/"
    click I "https://github.com/git-clone-abhinav/load-balancer/blob/master/build.sh"

    %% Styles
    classDef backend fill:#AEC6CF,stroke:#333,stroke-width:2px;
    classDef rpc fill:#FFB347,stroke:#333,stroke-width:2px;
    classDef cache fill:#77DD77,stroke:#333,stroke-width:2px;
    classDef notification fill:#F49AC2,stroke:#333,stroke-width:2px;
    classDef config fill:#CFCFC4,stroke:#333,stroke-width:2px;
    classDef deployment fill:#B19CD9,stroke:#333,stroke-width:2px;
```
