# danroc/geoblock architecture

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

- Interactive diagram: https://gitdiagram.com/danroc/geoblock
- Repository: https://github.com/danroc/geoblock

## Overview

##### Main Components Identification
The system should be represented with these key components:

a) Core Service Components:
- Forward Auth Server (main HTTP service)
- Configuration Manager
- Rules Engine
- IP Resolution Service
- Metrics Collector

b) External Dependencies:
- GeoLite2 Database
- IP Location DB
- Reverse Proxies (Traefik/NGINX/Caddy)

##### Flow Representation

a) Request Flow:
##### Response back to Reverse Proxy (204 or 403)

b) Configuration Flow:
##### Auto-reload trigger → Rules Engine update

c) Database Updates:
- Daily automatic updates for GeoLite2 databases

##### Component Details

For each major component, include:

a) Forward Auth Server:
- HTTP endpoints
- Request validation
- Headers processing (X-Forwarded-*)

b) Rules Engine:
- Policy evaluation
- Country checking
- ASN verification
- Network matching
- Domain validation

c) IP Resolution:
- Geolocation lookup
- ASN resolution
- Network matching

##### Additional Elements

Include:
- Metrics collection flow
- Health check endpoint
- Configuration auto-reload mechanism
- Database update schedule

##### Technical Details

- Port 8080 for service
- Configuration file location (/etc/geoblock/config.yaml)
- Supported HTTP methods
- Response status codes (204, 403)
- Metrics format (JSON)

This system design should effectively communicate how Geoblock processes requests, evaluates rules, and integrates with reverse proxies while maintaining its configuration and databases.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        C[Client Request]
    end

    subgraph "Reverse Proxies"
        RP1["Traefik"]:::proxy
        RP2["NGINX"]:::proxy
        RP3["Caddy"]:::proxy
    end

    subgraph "Forward Auth Service"
        FAS["Forward Auth Server\n(Port 8080)"]:::core
        EP1["/v1/forward-auth"]:::endpoint
        EP2["/v1/health"]:::endpoint
        EP3["/v1/metrics"]:::endpoint
        
        subgraph "Core Components"
            CM["Configuration Manager"]:::core
            RE["Rules Engine"]:::core
            IRS["IP Resolution Service"]:::core
            MC["Metrics Collector"]:::core
        end

        subgraph "Rule Evaluation"
            CC["Country Check"]:::rule
            AC["ASN Check"]:::rule
            NM["Network Match"]:::rule
            DV["Domain Validation"]:::rule
        end
    end

    subgraph "Data Layer"
        GL["GeoLite2 DB"]:::db
        IPDB["IP Location DB"]:::db
        CF["Config Files\n(/etc/geoblock/config.yaml)"]:::config
    end

    C --> RP1 & RP2 & RP3
    RP1 & RP2 & RP3 --> FAS
    FAS --> EP1 & EP2 & EP3
    EP1 --> RE
    RE --> CC & AC & NM & DV
    CC & AC & NM & DV --> IRS
    IRS --> GL & IPDB
    CF --> CM
    CM --> RE
    EP3 --> MC

    %% Component Mappings
    click FAS "https://github.com/danroc/geoblock/blob/main/internal/server/server.go"
    click CM "https://github.com/danroc/geoblock/blob/main/internal/config/reader.go"
    click RE "https://github.com/danroc/geoblock/blob/main/internal/rules/engine.go"
    click IRS "https://github.com/danroc/geoblock/blob/main/internal/ipres/resolver.go"
    click RP1 "https://github.com/danroc/geoblock/tree/main/examples/traefik/"
    click RP2 "https://github.com/danroc/geoblock/tree/main/examples/nginx/"
    click RP3 "https://github.com/danroc/geoblock/tree/main/examples/caddy/"
    click NM "https://github.com/danroc/geoblock/blob/main/internal/itree/itree.go"
    click DV "https://github.com/danroc/geoblock/blob/main/internal/utils/glob/glob.go"
    click CF "https://github.com/danroc/geoblock/blob/main/examples/config.yaml"

    %% Styles
    classDef proxy fill:#E0E0E0,stroke:#333
    classDef core fill:#B3E0FF,stroke:#333
    classDef endpoint fill:#FFB366,stroke:#333
    classDef rule fill:#FFE6CC,stroke:#333
    classDef db fill:#99FF99,stroke:#333
    classDef config fill:#FFFF99,stroke:#333

    %% Legend
    subgraph Legend
        L1["Reverse Proxy"]:::proxy
        L2["Core Component"]:::core
        L3["Endpoint"]:::endpoint
        L4["Rule"]:::rule
        L5["Database"]:::db
        L6["Configuration"]:::config
    end
```
