# go-gost/gost architecture

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

- Interactive diagram: https://gitdiagram.com/go-gost/gost
- Repository: https://github.com/go-gost/gost

## Overview

##### Project Type and Purpose
- This is a Go-based command-line application that implements a secure tunnel (proxy/tunneling) with multi-protocol support. It can be used in different modes (forward proxy, port forwarding, reverse proxy) and is intended to provide secure, flexible network tunneling capabilities.
- The README shows that the system supports a range of functionalities—from multi-port listening to plugins, routing control, dynamic configuration, and integrated APIs/GUI. This tells us that both the core tunneling engine and its extensibility are fundamental to the design.

##### Analyzing the File Structure
- The project has a single executable command in the “cmd/gost” directory, where main.go acts as the entry point and auxiliary files (program.go, register.go, version.go) subdivide functionality for program initialization, registration of modules or protocols, and version management.
- Build and deployment support is evident from files such as Dockerfile, .goreleaser.yaml, Makefile, as well as GitHub workflows in the “.github/workflows” directory. This indicates a well-structured CI/CD and release process.
- The existence of “gost.yml” suggests that the application supports external configuration, impacting how the tunnel chains are built or managed.

##### Architectural Components
- Core Application Module: Represented by the cmd/gost component where the main application logic lives.
- Configuration Module: Read configuration data (from gost.yml and dynamic configurations via the API) to control tunnel behavior.
- Tunneling Engine: Core logic that enables multi-level forwarding chain, protocol handling (TCP/UDP, DNS, etc.), and various tunneling modes (forward, reverse, port forwarding).
- Plugin System: Extendable architecture to allow additional functionalities such as routing control, limits, custom protocols, and integration with GUIs/WebUI.
- Web API/Monitoring: Components to handle Prometheus metrics, dynamic configuration, and the Web API to interact via HTTP.
- External Integrations: Docker support for container deployments and CI/CD pipelines to support automated building and releases.
- CLI and Utility Components: Parts of the system dealing with command-line parsing and version/reporting, as seen in register.go and version.go.

##### Relationships and Data Flow
- That configuration data is loaded early in the application lifecycle, which then configures the tunneling engine.
- How the core tunneling engine directs data through the appropriate protocol chains based on the configuration: e.g., separate branches or nodes for forward proxy, port forwarding, and reverse proxy modes.
- Interactions with external modules such as plugins, external monitoring (Prometheus), and the web API interface.
- Communications and dependencies from external clients to the secure tunnel endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: User/Client
    U["User/Client"]:::user

    %% Layer 2: Input Interfaces
    CI["CLI Interface"]:::core
    WA["Web API/Monitoring"]:::interface
    VU["Version Utility"]:::core

    %% Layer 3: Startup & Configuration
    CA["Core Application Module"]:::core
    CFG["Configuration Module"]:::config
    PS["Plugin System"]:::plugin

    %% Layer 4: Tunneling Logic
    TE["Tunneling Engine"]:::engine
    FP["Forward Proxy"]:::engine
    PF["Port Forwarding"]:::engine
    RP["Reverse Proxy"]:::engine

    %% Layer 5: External Integrations
    GH["GitHub Workflows"]:::integration
    DF["Dockerfile"]:::integration
    GR[".goreleaser.yaml"]:::integration
    MK["Makefile"]:::integration

    %% Connections from User/Client to Input Interfaces
    U -->|"starts"| CI
    U -->|"requests"| WA
    U -->|"version inquiry"| VU

    %% Input Interfaces feed into the Core Application Module
    CI -->|"executes"| CA
    VU --> CA
    WA --> CA

    %% Configuration Module loads and supplies data to Core Application Module
    CFG -->|"loads config"| CA

    %% Core Application Module triggers Tunneling Engine and Plugin System
    CA -->|"initializes"| TE
    CA -->|"registers"| PS

    %% Tunneling Engine branches into different modes
    TE -->|"handles"| FP
    TE -->|"handles"| PF
    TE -->|"handles"| RP

    %% Tunneling Engine feeds back monitoring data to Web API/Monitoring
    TE -->|"metrics"| WA

    %% External Integrations deploy and build the Core Application Module
    GH -->|"CI/CD triggers"| CA
    DF --> CA
    GR --> CA
    MK --> CA

    %% Styles
    classDef user fill:#FFECB3,stroke:#9E9E9E,stroke-width:2px;
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef config fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef engine fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef plugin fill:#F8BBD0,stroke:#880E4F,stroke-width:2px;
    classDef integration fill:#B2EBF2,stroke:#006064,stroke-width:2px;
    classDef interface fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;

    %% Click Events
    click CA "https://github.com/go-gost/gost/tree/master/cmd/gost"
    click CFG "https://github.com/go-gost/gost/blob/master/gost.yml"
    click CI "https://github.com/go-gost/gost/blob/master/cmd/gost/main.go"
    click VU "https://github.com/go-gost/gost/blob/master/cmd/gost/version.go"
    click PS "https://github.com/go-gost/gost/blob/master/cmd/gost/register.go"
    click TE "https://github.com/go-gost/gost/blob/master/cmd/gost/program.go"
    click GH "https://github.com/go-gost/gost/tree/master/.github/workflows"
    click DF "https://github.com/go-gost/gost/tree/master/Dockerfile"
    click GR "https://github.com/go-gost/gost/blob/master/.goreleaser.yaml"
    click MK "https://github.com/go-gost/gost/tree/master/Makefile"
```
