# alpkeskin/rota architecture

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

- Interactive diagram: https://gitdiagram.com/alpkeskin/rota
- Repository: https://github.com/alpkeskin/rota

## Overview

##### Project type and purpose
- Rota is a Go-based, backend-only microservice/CLI tool that runs as a local HTTP proxy server with built-in intelligent proxy rotation and an optional REST API for health, metrics and history.
- Its core use case is to accept incoming HTTP/SOCKS requests, pick an upstream proxy from a pool (with configurable rotation strategies), forward traffic, monitor proxy health, and optionally expose status via an API.

##### File structure
- cmd/rota/main.go: the single entrypoint that wires everything together.
- internal/config: loads and validates config.yml.
- internal/logging: centralized logger.
- internal/watcher: file watcher for live reloading of the proxy list.
- internal/proxy: core proxy pool, rotation strategies, health-checker, proxy handler.
- internal/middleware: HTTP middleware (rate limiting, basic auth, logging).
- internal/api: REST API handlers (healthz, /proxies, /metrics, /history).
- static: contains assets (logo, example config/schema).

##### README for additional insights
- Configuration is YAML-driven (proxy_file, rotation, rate_limit, api.enabled).
- Two server processes actually run in one binary:
- Proxy server listening on proxy.host:proxy.port
- API server (if enabled) on api.port
- Supports dynamic file-watch reloading, health checks, retry/fallback logic, multiple rotation algorithms.

##### Detail without over-splitting
- Every major internal package as a component, but group closely related files (e.g., proxy_loader + proxy_checker under “Proxy Pool Manager”).
- Don’t forget cross-cutting concerns (logging, middleware) drawn as horizontal layers or side-bars interacting with request flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration"
        ConfigLoader["Config Loader"]:::core
        ConfigFile["config.yml"]:::external
        StaticAssets["Static Assets"]:::external
    end

    subgraph "Core Components"
        Logger["Logger"]:::infra
        Watcher["File Watcher"]:::infra
        subgraph "Proxy Pool Manager"
            Loader["Loader"]:::core
            HealthChecker["Health Checker"]:::core
            ProxyTypes["Core Types & Usage"]:::core
        end
        Rotation["Rotation Engine"]:::core
    end

    subgraph "Server Layer"
        Middleware["Middleware Layer"]:::infra
        ProxyServer["HTTP Proxy Server\n(proxy:8080)"]:::infra
        APIServer["REST API Server\n(api:8081)"]:::infra
        Metrics["Metrics Endpoint"]:::infra
    end

    subgraph "External Systems"
        FileSystem["File System\n(proxies.txt)"]:::external
        ExtProxies["External Proxies"]:::external
    end

    Main["Entry Point\n(cmd/rota/main.go)"]:::infra

    Main --> ConfigLoader
    Main --> Logger
    Main --> Watcher
    Main --> Loader
    Main --> Rotation
    Main --> Middleware
    Main --> ProxyServer
    Main --> APIServer

    ConfigFile --> ConfigLoader
    StaticAssets --> ConfigLoader

    FileSystem -->|reload event| Watcher
    Watcher -->|new proxy list| Loader

    Loader --> HealthChecker
    HealthChecker --> Loader
    Loader --> ProxyTypes
    ProxyTypes --> Rotation

    Middleware -->|HTTP request| Rotation
    Rotation -->|selected proxy| ProxyServer
    ProxyServer -->|forward to| ExtProxies
    ExtProxies -->|response| ProxyServer
    ProxyServer -->|response| Middleware

    ProxyServer -->|passes through| Logger
    APIServer -->|reads state| Loader
    APIServer -->|reads state| HealthChecker
    APIServer -->|reads logs| Logger
    APIServer -.->|optional| Metrics

    Logger -->|logs events| Main
    Logger -->|logs events| Loader
    Logger -->|logs events| Watcher
    Logger -->|logs events| ProxyServer
    Logger -->|logs events| APIServer

    click Main "https://github.com/alpkeskin/rota/blob/main/cmd/rota/main.go"
    click ConfigLoader "https://github.com/alpkeskin/rota/blob/main/internal/config/config.go"
    click ConfigLoader "https://github.com/alpkeskin/rota/blob/main/internal/config/schema.go"
    click Logger "https://github.com/alpkeskin/rota/blob/main/internal/logging/logging.go"
    click Watcher "https://github.com/alpkeskin/rota/blob/main/internal/watcher/watcher.go"
    click Loader "https://github.com/alpkeskin/rota/blob/main/internal/proxy/loader.go"
    click HealthChecker "https://github.com/alpkeskin/rota/blob/main/internal/proxy/check.go"
    click ProxyTypes "https://github.com/alpkeskin/rota/blob/main/internal/proxy/proxy_types.go"
    click ProxyTypes "https://github.com/alpkeskin/rota/blob/main/internal/proxy/proxy_usage.go"
    click Rotation "https://github.com/alpkeskin/rota/blob/main/internal/proxy/proxy_rotation.go"
    click ProxyServer "https://github.com/alpkeskin/rota/blob/main/internal/proxy/proxy_handler.go"
    click ProxyServer "https://github.com/alpkeskin/rota/blob/main/internal/proxy/proxy.go"
    click Middleware "https://github.com/alpkeskin/rota/blob/main/internal/middleware/middleware.go"
    click APIServer "https://github.com/alpkeskin/rota/blob/main/internal/api/api.go"
    click APIServer "https://github.com/alpkeskin/rota/blob/main/internal/api/api_types.go"
    click StaticAssets "https://github.com/alpkeskin/rota/tree/main/static/"
    classDef core fill:#add8e6,stroke:#000,stroke-width:1px
    classDef infra fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px
```
