# yzhzeng/goodlink architecture

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

- Interactive diagram: https://gitdiagram.com/yzhzeng/goodlink
- Repository: https://github.com/yzhzeng/goodlink

## Overview

##### Main Components
- Local Client – This can be the command-line version or the Windows UI version (found in the “ui2” directory) that sets up either a SOCKS5 proxy or port-forwarding service by listening on a specified local port.
- Remote Server – This component (running with the “--remote” flag) is deployed on the host that provides access to internal resources (like remote desktop, NAS, or internal web services).
- Communication Module – The direct P2P connection between local and remote, based on QUIC, with built-in encryption (modules under “aes”, “md5”, and “tls2”). This is the secure channel established with a shared key.
- Proxy/Forwarding Logic – Depending on mode, the application uses the “socks5” module for proxy mode or parts of “proxy” and “pro” for port forwarding.
- NAT Traversal Component – “stun2” helps with traversing NAT to establish the peer-to-peer connection.
- Configuration & Utilities – Configurations and command-line arguments (in “config”), various utility tools (in “tools”), and build/infrastructure files (Dockerfile, Makefile) that support deployment.
- UI Components – For the Windows UI, the “ui2” and “theme” directories provide the graphical interface and visual theming.

##### Relationships and Interactions
- The Local Client sends a connection request (with parameters such as local port, key, and possibly a remote target for port-forwarding) into the network stack.
- Communication flows securely via the encrypted QUIC-based link to the Remote Server.
- In proxy mode, the local SOCKS5 server (implemented in “socks5”) intercepts application requests and forwards them over the secure channel. In forwarding mode, the connection is bridged directly between the local and remote port specifications.
- The encryption and integrity modules (in “aes”, “md5”, “tls2”) ensure data is securely exchanged.
- The NAT traversal logic (“stun2”) engages to overcome any intermediary NAT issues.
- The configuration layer (from “config”) governs command-line arguments and runtime behavior, while utility code (from “tools”) may support auxiliary functions like monitoring or additional networking capabilities.

##### Architectural Patterns and Core Technologies
- Modular design – Each responsibility (UI, encryption, network proxying, NAT traversal) is encapsulated in its own package or directory.
- Client-Server (or peer-to-peer) architecture – Even though there isn’t a centralized server, there are clearly defined roles (local vs. remote) which exchange information over defined network protocols.
- Protocol Abstraction – The project abstracts protocol details (QUIC, SOCKS5, and TCP port forwarding) so that multiple connection modes are supported.
- Deployment flexibility – The design supports different runtime environments (command-line, Docker, Windows UI).

##### Detailed Capture of Architectural Elements
- Be very explicit about how components interact and depend on the key parameter (the shared secret).
- Separate the concerns: networking layer (handling QUIC and connection retries), proxy modules (handling system-specific behaviors like SOCKS5 and port mapping), and application logic (deciding on operational mode, processing configurations).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Local Side"
        CLI("Local Client (CLI)"):::client
        UI("Local Client (Windows UI)"):::client
        UITheme("UI Theme"):::client
        Proxy("SOCKS5 Proxy Module"):::client
        PForward("Port Forwarding Module"):::client
    end

    subgraph "Encrypted P2P Channel over QUIC"
        ENC_BRIDGE("Encryption Bridge"):::channel
        ENC_AES("AES Library"):::channel
        ENC_MD5("MD5 Library"):::channel
        ENC_TLS_CLIENT("TLS Client"):::channel
        ENC_TLS_SERVER("TLS Server"):::channel
    end

    subgraph "Remote Side"
        RS("Remote Server (Internal Services)"):::server
        RF("Remote Port Forwarding Module"):::server
    end

    subgraph "Deployment & Config"
        CONFIG("Configuration"):::config
        UTILS("Utilities & Build"):::util
        BUILD("Docker & Build"):::util
    end

    NAT("NAT Traversal (STUN)"):::nat

    %% Local Side interactions
    CLI -->|"triggers"| Proxy
    CLI -->|"triggers"| PForward
    UI  -->|"triggers"| Proxy
    UI  -->|"triggers"| PForward
    UI  --> UITheme

    %% Flows to Encryption Channel
    Proxy -->|"ProxyMode"| ENC_BRIDGE
    PForward -->|"ForwardingMode"| ENC_BRIDGE

    %% Encryption Channel branches to Remote Side
    ENC_BRIDGE -->|"ProxyTraffic"| RS
    ENC_BRIDGE -->|"ForwardTraffic"| RF

    %% Encryption Channel details (informational links)
    ENC_BRIDGE -.-> ENC_AES
    ENC_BRIDGE -.-> ENC_MD5
    ENC_BRIDGE -.-> ENC_TLS_CLIENT
    ENC_BRIDGE -.-> ENC_TLS_SERVER

    %% NAT Traversal interacts with Encryption Channel
    NAT --- ENC_BRIDGE

    %% Deployment & Config influences (informational)
    CONFIG --- CLI
    CONFIG --- UI
    UTILS --- CONFIG
    BUILD --- UTILS

    %% Click Events
    click CLI "https://github.com/yzhzeng/goodlink/blob/master/main_cmd.go"
    click UI "https://github.com/yzhzeng/goodlink/tree/master/ui2"
    click UITheme "https://github.com/yzhzeng/goodlink/tree/master/theme"
    click RS "https://github.com/yzhzeng/goodlink/blob/master/pro/remote.go"
    click Proxy "https://github.com/yzhzeng/goodlink/tree/master/socks5"
    click PForward "https://github.com/yzhzeng/goodlink/blob/master/pro/local.go"
    click ENC_AES "https://github.com/yzhzeng/goodlink/blob/master/aes/aes.go"
    click ENC_MD5 "https://github.com/yzhzeng/goodlink/blob/master/md5/md5.go"
    click ENC_TLS_CLIENT "https://github.com/yzhzeng/goodlink/blob/master/tls2/client.go"
    click ENC_TLS_SERVER "https://github.com/yzhzeng/goodlink/blob/master/tls2/server.go"
    click NAT "https://github.com/yzhzeng/goodlink/blob/master/stun2/cli.go"
    click CONFIG "https://github.com/yzhzeng/goodlink/blob/master/config/config.go"
    click UTILS "https://github.com/yzhzeng/goodlink/tree/master/tools"
    click BUILD "https://github.com/yzhzeng/goodlink/tree/master/Dockerfile"

%% Styles
classDef client fill:#add8e6,stroke:#000,stroke-width:2px;
classDef channel fill:#90ee90,stroke:#000,stroke-width:2px;
classDef server fill:#ffb6c1,stroke:#000,stroke-width:2px;
classDef nat fill:#fdfd96,stroke:#000,stroke-width:2px;
classDef config fill:#d3d3d3,stroke:#000,stroke-width:2px;
classDef util fill:#dda0dd,stroke:#000,stroke-width:2px;
```
