# h1v9/balooproxyx architecture

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

- Interactive diagram: https://gitdiagram.com/h1v9/balooproxyx
- Repository: https://github.com/h1v9/balooproxyx

## Overview

##### Project Type and Purpose
- balooProxyX is an open-source, production-ready reverse proxy written in Go that provides staged DDoS mitigation (cookie challenge, PoW JS, captcha), TLS fingerprinting, custom firewall rules, and alerting via Discord.

##### File Structure
- Top-level:
– main.go, Dockerfile, systemd example files, config examples
– assets/html (challenge/error page templates)
– assets/server (default cert/key)
– global/fingerprints (local TLS fingerprint JSON stores)
- core/ directory:
– core/config (config generation & init)
– core/firewall (fingerprint loading, rule evaluation with go-filter)
– core/proxy (proxy logic, X-Forwarded-For handling)
– core/server (HTTP listener, middleware, template rendering, monitor)
– core/utils (helpers: encryption, discord alerts, debugging)
– core/api, core/db, core/domains (supporting modules)

##### README for Insights
- Customizable firewall via wireguard-style expressions
- Three challenge stages, Discord alert integration, Cloudflare mode
- Docker and systemd deployment options

##### Main Components
a. External Clients (“Users/Bots”)
b. (Optional) Cloudflare Edge (TLS passthrough or proxy)
c. balooProxyX Node
- TLS Termination & Fingerprint Loader (core/firewall → global/fingerprints)
- Config Loader (core/config → config.json)
- Rule Engine (core/firewall using go-filter)
- Challenge Pipeline (cookie → JS PoW → captcha; assets/html via core/server/template.go)
- Proxy Forwarder (core/proxy → backend domain over HTTP/HTTPS)
- Monitor & Metrics (core/server/monitor, core/utils/debug)
- Alerting (core/utils/discord hooking into attack start/end)
- API Endpoints (core/api for potential external control)
d. Backend Services (your origin web servers)
e. Data Stores
- Configuration JSON (disk)
- TLS fingerprint JSON files (global/fingerprints)
f. External Integrations
- Discord Webhooks (alert channel)
- Optional GitHub version-check API
- Deployment orchestrators (Docker container, systemd unit)

##### Relationships and Interactions
1. Client → (Cloudflare) → balooProxyX TLS Listener
2. TLS handshake triggers fingerprint lookup
3. Request flows into Rule Engine → adjusts suspicion level
4. Based on susLv, one or more challenges served via HTML templates
5. Successful requests forwarded to backend (with X-Forwarded-For)
6. Backend response returned to client
7. Monitoring collects CPU/RPS/bypass data → logs to console or daemon mode
8. On attack events, send Discord alerts

##### Architectural Patterns and Technologies
- Layered pipeline: TLS → Fingerprint → Firewall Rules → Challenge → Forward
- Modular Go packages for separation of concerns
- go-filter rule engine for extensible firewall expressions
- HTML template subsystem for challenge pages
- JSON-based config and data storage
- Docker + systemd for deployment

##### Essential Elements Checklist
- Clear labels for every component and sub-component
- Notation of Daemon (-d) and Stealth modes for console output and branding

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Users("Users / Bots"):::network
    Cloudflare("Cloudflare Edge"):::network

    %% balooProxyX Node
    subgraph "balooProxyX Node"
        direction TB
        TLS["TLS Termination & Fingerprint Loader"]:::module
        Config["Config Loader"]:::module
        Rule["Rule Engine"]:::module
        Challenge["Challenge Pipeline"]:::module
        ProxyFwd["Proxy Forwarder"]:::module
        Monitor["Monitor & Metrics"]:::module
        Alert["Alerting (Discord Webhooks)"]:::module
        API["API Endpoints"]:::module

        %% Data Stores
        subgraph "Data Stores"
            direction TB
            ConfigStore["Configuration JSON (disk)"]:::datastore
            Fingerprints["TLS Fingerprint JSON files"]:::datastore
        end
    end

    %% Backend and External Integrations
    Backend("Backend Services"):::network
    Discord("Discord Webhooks"):::external
    GitHub("GitHub Version-Check API"):::external
    Infra("Deployment Orchestrators\n(Docker, systemd)"):::external

    %% Main Flow
    Users -->|"TLS over TCP"| Cloudflare
    Cloudflare -->|"TLS handshake"| TLS
    TLS -->|"lookup fingerprints"| Fingerprints
    TLS -->|"load config"| Config
    Config -->|"load settings"| ConfigStore
    TLS -->|"pass to"| Rule
    Rule -->|"evaluate rules"| Rule
    Rule -->|"susLv decision"| Challenge
    Challenge -->|"serve HTML"| Users
    Challenge -->|"on success"| ProxyFwd
    ProxyFwd -->|"forward HTTP/HTTPS\n(X-Forwarded-For)"| Backend
    Backend -->|"response"| Users

    %% Monitoring and Alerts
    Monitor ---|collect metrics| TLS
    Monitor ---|collect metrics| Rule
    Monitor ---|collect metrics| ProxyFwd
    Alert ---|on attack events| Discord
    Rule ---|trigger alerts| Alert

    %% API and Version Check
    API -->|"external control"| TLS
    API -->|"external control"| Rule
    API -->|"external control"| ProxyFwd
    GitHub ---|version check| API

    %% Infrastructure
    Infra ---|deploy| TLS

    %% Click Events
    click TLS "https://github.com/h1v9/balooproxyx/blob/main/core/firewall/fingerprint.go"
    click Fingerprints "https://github.com/h1v9/balooproxyx/tree/main/global/fingerprints/"
    click Config "https://github.com/h1v9/balooproxyx/blob/main/core/config/init.go"
    click ConfigStore "https://github.com/h1v9/balooproxyx/blob/main/examples/config.json"
    click Rule "https://github.com/h1v9/balooproxyx/blob/main/core/firewall/eval.go"
    click Challenge "https://github.com/h1v9/balooproxyx/blob/main/core/server/template.go"
    click ProxyFwd "https://github.com/h1v9/balooproxyx/blob/main/core/proxy/proxy.go"
    click Monitor "https://github.com/h1v9/balooproxyx/blob/main/core/server/monitor.go"
    click Alert "https://github.com/h1v9/balooproxyx/blob/main/core/utils/discord.go"
    click API "https://github.com/h1v9/balooproxyx/blob/main/core/api/api.go"
    click Infra "https://github.com/h1v9/balooproxyx/blob/main/main.go"

    %% Styles
    classDef network fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef module fill:#d4edda,stroke:#333,stroke-width:1px
    classDef datastore fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
```
