# bmf-san/gondola architecture

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

- Interactive diagram: https://gitdiagram.com/bmf-san/gondola
- Repository: https://github.com/bmf-san/gondola

## Overview

##### Project Type and Purpose
- This is a server-side Go application whose primary function is to act as a reverse proxy. It provides features like static file hosting, virtual host support, graceful shutdown, TLS/SSL support, and detailed (nginx-compatible) access logging.
- The README and file structure indicate that its main responsibilities include reading a YAML configuration, starting an HTTP proxy server, handling request routing to configured upstream targets, and managing logging and signal-based tasks (graceful shutdown, config reload, log reopening).

##### Analyzing the File Structure
- Top-level files and directories (cmd, _examples, testdata) indicate separation between the production code (cmd/main.go, gondola.go, proxy.go, etc.), example configurations/deployment scenarios (_examples), and test resources.
- The presence of configuration files (e.g., config.go and testdata/config/config.yml), logging components (logger.go), and separate modules for proxy handling (proxy.go) help pinpoint the key components of the system.
- Multiple GitHub workflows and Docker/Dockerfile files suggest continuous integration/deployment practices, although these are peripheral to the proxy’s core runtime architecture.
- The test files (gondola_test.go, proxy_test.go, etc.) show unit testing emphasis for reliability.

##### Key Components
a. Entry Point and Command-Line Interface:
– Represent the main execution flow initiated by cmd/main.go which processes command-line options and loads the configuration.

b. Configuration Loader:

c. HTTP Server & Proxy Engine:
– Illustrate the core reverse proxy component. Show how this module intercepts incoming HTTP requests, manages static file serving, and delegates dynamic requests to targeted upstream servers.

d. Upstream Routing/Target Management:
– Create a component for upstream servers. This should visually represent how the proxy decides whether to route a request to a particular backend (depending on host names, paths, or virtual hosts as configured).

e. Logger:
– Highlight the logging component responsible for recording detailed, structured access logs (nginx-compatible and JSON output), and how these logs capture client, request, response, and upstream details.

f. Signal Handler:
– Include a subsystem showing how the application handles OS signals (SIGTERM/SIGINT for graceful shutdown, SIGHUP to reload configuration, SIGUSR1 to reopen logs).

##### Relationships and Interactions
- Incoming HTTP requests hit the HTTP Server/Proxy component.
- The Proxy consults the Configuration Loader for routing rules.
- It then forwards the requests to the appropriate Upstream servers and gathers responses.
- The Logger captures and logs details at every stage.
- Separately, the Command Line handler initiates startup and configuration loading.
- A Signal Handler interacts with multiple components (e.g., graceful shutdown of the server, config reload).

##### Architectural Patterns & Design Principles
- Separation of concerns – distinctly showing configuration management, request routing, logging, and signal handling as separate but interacting modules.
- The project follows a “modular, layered” design where the network I/O is abstracted from business logic (i.e., reverse proxy operations) and system management tasks (logging, signal handling).

##### Required Elements
- Clear labels for each component/module (e.g., “CLI/Entry Point”, “Config Loader”, “HTTP Server/Proxy”, “Upstream Router”, “Logger”, “Signal Handler”).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Entities
    Client["Client"]:::external
    UpstreamServer["Upstream Server"]:::external

    %% Initialization Layer
    subgraph "Initialization Layer"
        CLI["CLI/Entry Point"]:::entry
        Config["Configuration Loader"]:::config
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        HTTP["HTTP Server/Proxy"]:::core
        Upstream["Upstream Router"]:::core
    end

    %% Supporting Services Layer
    subgraph "Supporting Services"
        Logger["Logger"]:::support
        Signal["Signal Handler"]:::support
    end

    %% Connections for Initialization
    CLI -->|"load_config"| Config
    Config -->|"config_settings"| HTTP

    %% Client Request Flow
    Client -->|"HTTP_Request"| HTTP
    HTTP -->|"route_request"| Upstream
    Upstream -.->|"select_target"| UpstreamServer
    HTTP -->|"forward_request"| UpstreamServer
    UpstreamServer -->|"upstream_response"| HTTP

    %% Logging Flow
    HTTP -->|"log_details"| Logger

    %% Signal Interactions
    Signal -->|"shutdown_reload"| HTTP
    Signal -->|"config_reload"| Config

    %% Click Events
    click CLI "https://github.com/bmf-san/gondola/blob/main/cmd/main.go"
    click Config "https://github.com/bmf-san/gondola/blob/main/config.go"
    click HTTP "https://github.com/bmf-san/gondola/blob/main/gondola.go"
    click HTTP "https://github.com/bmf-san/gondola/blob/main/proxy.go"
    click Logger "https://github.com/bmf-san/gondola/blob/main/logger.go"
    click Signal "https://github.com/bmf-san/gondola/blob/main/gondola.go"

    %% Styles
    classDef entry fill:#cce5ff,stroke:#2a9df4,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#f0ad4e,stroke-width:2px;
    classDef core fill:#d1e7dd,stroke:#198754,stroke-width:2px;
    classDef support fill:#f8d7da,stroke:#d63384,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
