# perbu/hazelnut architecture

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

- Interactive diagram: https://gitdiagram.com/perbu/hazelnut
- Repository: https://github.com/perbu/hazelnut

## Overview

##### Main Components
- CLI / Entrypoint (main.go)
- Configuration Loader (config package)
- Service Orchestrator (service/server.go)
- Frontend HTTP Server (frontend package)
- Cache Layer (cache package with lrucache and mapcache implementations)
- Backend Reverse-Proxy (backend package)
- Metrics Exporter (metrics package)
- External Systems
– Upstream HTTP/HTTPS target
– Prometheus scraper

##### Relationships & Data Flow
– Startup:
- main.go reads config via config.Config
- main calls service.New(ctx, cfg, logger) → returns a Server object
- Server.Run starts two listeners:
– Frontend listener (default port 8080)
– Metrics listener (default port 9091)
– Request handling chain (decorate pattern):
1. Client → Frontend HTTP listener (frontend package)
2. Metrics middleware (metrics package) increments request counter
3. Cache middleware (cache package) checks for a hit:
- Hit → return cached response + increment cache_hits metric
- Miss → pass request to backend
4. Backend reverse proxy (backend package) forwards request to target (config.BackendConfig.Target, Scheme)
5. Backend response → cache.Store (on CacheConfig.MaxObj/MaxCost) → return to client
6. Metrics middleware logs misses, errors
– Metrics endpoint: Prometheus scrapes /metrics on metrics port

##### Architectural Patterns & Principles
- Layered / modular design: clear separation of config, service orchestration, HTTP I/O, caching, backend proxy, metrics.
- Decorator / middleware chain for caching and metrics around the core reverse-proxy handler.
- Interface abstraction for cache.Backend (allows lrucache vs mapcache).
- Single binary with embedded library mode (examples/embed shows embedding via server.New).

##### Technologies & Libraries
- Go’s net/http for server & client
- Ristretto-based high-performance cache (cache/lrucache)
- YAML configuration (config/config.go)
- Prometheus Go client (metrics/metrics.go)
- Go modules (go.mod)

##### Detail Checklist
– main.go / CLI → config loader → service.New
– service.Run → starts frontend + metrics servers
– Frontend handler → metrics.Middleware → cache.Middleware → backend.Proxy
– cache package: interface, lrucache & mapcache implementations
– backend package: HTTP client & reverse-proxy logic
– metrics package: Prometheus counters/gauges exposed on /metrics
– External: Upstream target (configurable), Prometheus scrape

## Diagram (Mermaid)

```mermaid
graph TB
    %% Control Flow
    subgraph "Control / Initialization"
        direction TB
        Main["main.go"]:::control
        Config["config/config.go"]:::control
        Service["service/server.go"]:::control
        EmbedExample["examples/embed/main.go"]:::control
    end

    Main -->|"reads config"| Config
    Config -->|"calls service.New"| Service
    Service -->|"starts frontend listener"| FrontendListener
    Service -->|"starts metrics listener"| MetricsListener
    EmbedExample -->|"imports config & service"| Service

    %% HTTP Frontend
    subgraph "HTTP Frontend" 
        direction TB
        FrontendListener["Frontend Listener\n(port 8080)"]:::data
        FrontendHandler["frontend/frontend.go"]:::data
    end

    %% Cache Layer
    subgraph "Cache Layer"
        direction TB
        CacheInterface["cache/cache.go"]:::data
        LRU["cache/lrucache/lrucache.go"]:::data
        MapCache["cache/mapcache/lrucache.go"]:::data
    end

    %% HTTP Backend
    subgraph "HTTP Backend"
        direction TB
        BackendProxy["backend/backend.go"]:::data
        Upstream["Upstream HTTP/HTTPS Target"]:::external
    end

    %% Observability
    subgraph "Observability"
        direction TB
        MetricsListener["Metrics Listener\n(port 9091)"]:::obs
        MetricsMiddleware["metrics/metrics.go"]:::obs
        PromScraper["Prometheus Scraper"]:::external
    end

    %% External Client
    Client["Client"]:::external

    %% Request Flow
    Client -->|"HTTP request"| FrontendListener
    FrontendListener -->|"handle request"| FrontendHandler
    FrontendHandler -->|"metrics middleware"| MetricsMiddleware
    MetricsMiddleware -->|"cache middleware"| CacheInterface
    CacheInterface -->|"cache miss"| BackendProxy
    BackendProxy -->|"forward request"| Upstream
    Upstream -->|"response"| BackendProxy
    BackendProxy -->|"store response"| CacheInterface
    CacheInterface -->|"return response"| MetricsMiddleware
    MetricsMiddleware -->|"return to client"| FrontendHandler
    FrontendHandler -->|"HTTP response"| Client

    %% Metrics Scrape
    PromScraper -->|"scrape /metrics"| MetricsListener

    %% Click Events
    click Main "https://github.com/perbu/hazelnut/blob/main/main.go"
    click Config "https://github.com/perbu/hazelnut/blob/main/config/config.go"
    click Service "https://github.com/perbu/hazelnut/blob/main/service/server.go"
    click EmbedExample "https://github.com/perbu/hazelnut/blob/main/examples/embed/main.go"
    click FrontendHandler "https://github.com/perbu/hazelnut/blob/main/frontend/frontend.go"
    click CacheInterface "https://github.com/perbu/hazelnut/blob/main/cache/cache.go"
    click LRU "https://github.com/perbu/hazelnut/blob/main/cache/lrucache/lrucache.go"
    click MapCache "https://github.com/perbu/hazelnut/blob/main/cache/mapcache/lrucache.go"
    click BackendProxy "https://github.com/perbu/hazelnut/blob/main/backend/backend.go"
    click MetricsMiddleware "https://github.com/perbu/hazelnut/blob/main/metrics/metrics.go"

    %% Styles
    classDef control fill:#e0ffe0,stroke:#097f00,color:#095700;
    classDef data fill:#e0f0ff,stroke:#004080,color:#002040;
    classDef obs fill:#fff0e0,stroke:#aa6500,color:#663d00;
    classDef external fill:#f0f0f0,stroke:#888888,color:#444444
```
