# fbonareis/goexpert-ratelimiter architecture

> Architecture diagram of the GitHub repository fbonareis/goexpert-ratelimiter, 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/fbonareis/goexpert-ratelimiter
- Repository: https://github.com/fbonareis/goexpert-ratelimiter

## Overview

##### Project type and purpose
- This is a Go-based backend microservice whose sole responsibility is to expose a simple HTTP API and enforce rate limiting per IP or API key, backed by Redis.
- The README confirms it’s intended to run in Docker (via docker-compose) alongside a Redis container, serving a `/sample` endpoint with rate-limit middleware.

##### File structure
- Top level:
- cmd/ratelimiter/main.go → entry point for the service
- Dockerfile & docker-compose.yaml → container build and orchestration
- internal/infra/… → contains all infrastructure code (configs, rate-limit implementation, webserver & middleware)
- test/ → integration or API tests against the running service
- Patterns & architectural hints:
- Separation of concerns under `internal/infra`:
– configs (configuration loader)
– ratelimit (core rate limiter interface + Redis implementation)
– web (HTTP server, handlers, middleware)
- A single process that hosts the webserver and middleware; Redis is external.

##### README for additional insights
- Environment variables define Redis host/credentials and two rate-limit thresholds (per IP, per token).
- The application exposes only one endpoint for demonstration (`/sample`), protected by the rate-limit middleware layer.
- Execution instructions confirm the service + Redis run in Docker.

a. Main components:
- Client(s) (e.g., curl, browser, mobile app)
- Go Rate-Limiter Service
– HTTP Server (Router + `/sample` handler)
– Middleware Layer (rate limiter)
– Configuration Loader
– Rate Limiter Core (interface)
– Redis Limiter Implementation
- Redis Cache/Store (as external service)
- Docker + Docker-Compose orchestration (optional container boundary)
b. Relationships & interactions:
– Client → HTTP Server: incoming request
– HTTP Server → Middleware: intercept request before handler
– Middleware → Rate Limiter Core → Redis Limiter → Redis: check/increment tokens
– Middleware → HTTP Server: either pass through or reject (429)
– Handler → Response → Client
– The service reads configuration at startup (Env loader → config.go)
c. Architectural patterns & principles:
– Layered architecture: Handler ↔ Middleware ↔ Core ↔ Infra (Redis)
– Dependency inversion: rate limiter interface decouples core logic from Redis implementation
– Single responsibility: config loader, rate‐limit logic, webserver all separated
d. Key technologies/frameworks:
– Language: Go
– HTTP framework: net/http (custom webserver under `internal/infra/web/webserver`)
– Redis client (library used in redis_limiter.go)
– Docker & Docker-Compose for containerization

##### Detailed capture of essential elements
- Do not subdivide too granularly—focus on the five major components: Client, HTTP Server, Middleware, RedisLimiter, Redis.
- Middleware with the two rate-limit rules (per IP & per token) and config source.
- Optionally, show the environment‐variable config file feeding into the configuration loader.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["API Client"]:::external

    %% Docker Compose Boundary
    subgraph "Docker-Compose Network" 
        direction TB
        %% Go Service Container
        subgraph "Go Rate-Limiter Service" 
            direction TB
            Entry["main.go\n(Entry Point)"]:::internal
            Config["Configuration Loader"]:::internal
            Starter["HTTP Server Starter"]:::internal
            Webserver["Webserver Setup\n(Router & Server)"]:::internal
            Middleware["Rate-Limit Middleware\n(IP & Token Rules)"]:::internal
            Core["RateLimiter Interface"]:::internal
            Impl["RedisLimiter Implementation"]:::internal
            Handler["/sample Handler"]:::internal
        end

        %% Redis Container
        Redis[("Redis Cache")]:::db
    end

    %% Tests
    subgraph "Tests" 
        direction TB
        APITest["API Tests"]:::test
        EnvFile["Test .env"]:::test
    end

    %% Flows
    Client -->|"HTTP Request"| Entry
    Entry -->|load config| Config
    Entry -->|start server| Starter
    Starter -->|initialize| Webserver
    Webserver -->|incoming req| Middleware
    Middleware -->|check limits| Core
    Core -->|delegate| Impl
    Impl -->|INCR/GET| Redis
    Redis -->|result| Impl
    Impl -->|limit status| Core
    Core -->|allow/deny| Middleware
    Middleware -->|forward| Handler
    Handler -->|response| Client

    APITest -->|"uses .env"| EnvFile
    APITest -->|requests| Client

    %% Click Events
    click Entry "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/cmd/ratelimiter/main.go"
    click Dockerfile "https://github.com/fbonareis/goexpert-ratelimiter/tree/main/Dockerfile"
    click docker-compose "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/docker-compose.yaml"
    click Config "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/internal/infra/configs/config.go"
    click Core "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/internal/infra/ratelimit/rate_limit.go"
    click Impl "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/internal/infra/ratelimit/limiter/redis_limiter.go"
    click Starter "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/internal/infra/web/webserver/starter.go"
    click Webserver "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/internal/infra/web/webserver/webserver.go"
    click Handler "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/internal/infra/web/sample_handler.go"
    click Middleware "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/internal/infra/web/webserver/middleware/middleware_ratelimiter.go"
    click APITest "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/test/api_test.go"
    click EnvFile "https://github.com/fbonareis/goexpert-ratelimiter/blob/main/test/.env"

    %% Styles
    classDef external fill:#f9d5a2,stroke:#333,stroke-width:1px
    classDef internal fill:#a2d5f9,stroke:#333,stroke-width:1px
    classDef db fill:#a2f9a2,stroke:#333,stroke-width:1px
    classDef test fill:#e2e2e2,stroke:#333,stroke-width:1px
```
