# fossabot/clash architecture

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

- Interactive diagram: https://gitdiagram.com/fossabot/clash
- Repository: https://github.com/fossabot/clash

## Overview

Step 1: Identify the project type and purpose
- Clash is a rule-based network proxy service written in Go.
- It exposes HTTP/HTTPS and SOCKS5 listeners, applies user-defined rules (domain suffix/keyword, GeoIP, final), selects a proxy or “direct/reject” action, and can chain or benchmark proxies (url-test).
- It also provides a RESTful external-controller API for dynamic control.

Step 2: Analyze the file structure
- Top level: main.go (entry), Makefile/Dockerfile for build & deploy, .travis.yml for CI, Gopkg.* for Go deps.
- adapters/: implementations of outbound strategies (direct, reject, shadowsocks, url-test).
- constant/: shared constants (adapter names, address types, rule types, traffic metrics).
- hub/: core orchestrator—reads config, holds global state (proxy definitions, groups, rulesets), runs external-controller server.
- proxy/: inbound servers
- proxy/http/: HTTP(S) proxy (CONNECT & standard requests)
- proxy/socks/: SOCKS5 proxy (TCP/UDP)
- rules/: rule matcher implementations (domain-suffix, domain-keyword, geoip, ipcidr, final).
- tunnel/: connection logic to upstream (builds actual TCP connections, logs, error handling).
- observable/: event bus for publishing/subscribing metrics & url-test results.
- docs/: documentation, LICENSE, README.md.

Step 3: Examine README for additional insights
- Features: HTTP/HTTPS, SOCKS, Surge-style config, GeoIP support.
- Configuration: INI file defines ports, proxies, proxy groups, rules.
- External controller: REST API on a configurable port for live control (via hub/server.go).
- Docker support via docker-compose.

a. Main components
- Clients (any HTTP/SOCKS5-capable application)
- HTTP Proxy Server (proxy/http/)
- SOCKS Proxy Server (proxy/socks/)
- Rule Engine (rules/ + constant/)
- Hub – Config Manager & REST API Controller (hub/)
- Adapter Factory & Pool (adapters/)
- Tunnel Manager (tunnel/)
- Observable/EventBus (observable/)
- GeoIP Database (data file loaded by rules/geoip.go)

b. Relationships & interactions
1. Client → HTTP/SOCKS listener
2. Listener → Rule Engine: “Which adapter?”
3. Rule Engine queries Hub for configured proxies/groups
4. Hub.AdapterFactory ↔ adapters/: instantiate or select an adapter (direct, reject, shadowsocks, url-test)
5. Adapter → Tunnel Manager: Dial upstream (could be direct host or another proxy)
6. Tunnel → External Network or next-hop proxy
7. Responses flow back along the same path in reverse
8. Observable:
- Adapters and Tunnel publish metrics (latency, failures)
- url-test adapter subscribes to schedule active benchmarks
9. External Controller (REST API) ↔ Hub: dynamic config reload, status queries

c. Architectural patterns & design principles
- Strategy Pattern: adapters implement a common interface for outbound connections
- Observer Pattern: observable package for metrics, url-test scheduling
- Factory Pattern: hub constructs adapters based on config.toml
- Modular design: strict separation between ingress (proxy servers), processing (rules, hub), egress (adapters, tunnel), and monitoring (observable)

d. Significant technologies/frameworks
- Go 1.10+ (net/http, net package)
- go-shadowsocks2 for Shadowsocks adapter
- INI parser for config
- Docker & docker-compose for containerization
- Travis CI for continuous integration
- External daemons (pm2, supervisor) for process management

- Two parallel ingress paths: HTTP and SOCKS listeners.
- Centralize rule evaluation before selecting an outbound adapter.
- External-controller API connecting to the Hub for runtime changes.

Step 6: Diagramming guidelines
- Request flow (Client → Listener → Rule Engine → Adapter → Tunnel → Network)
- Control flow (External Controller → Hub; Observable ↔ Adapters)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Point
    Entry["Entry Point"]:::core
    click Entry "https://github.com/fossabot/clash/blob/master/main.go"

    %% Clients
    Client["Client (HTTP/SOCKS5 App)"]:::external

    %% Ingress Servers
    subgraph "Ingress Servers"
        direction TB
        subgraph "HTTP Proxy Server"
            direction TB
            HTTPServer["server.go"]:::ingress
            HTTPHandler["http.go"]:::ingress
            HTTPSHandler["https.go"]:::ingress
            click HTTPServer "https://github.com/fossabot/clash/blob/master/proxy/http/server.go"
            click HTTPHandler "https://github.com/fossabot/clash/blob/master/proxy/http/http.go"
            click HTTPSHandler "https://github.com/fossabot/clash/blob/master/proxy/http/https.go"
        end
        subgraph "SOCKS Proxy Server"
            direction TB
            SOCKSTCP["tcp.go"]:::ingress
            SOCKSUDP["udp.go"]:::ingress
            click SOCKSTCP "https://github.com/fossabot/clash/blob/master/proxy/socks/tcp.go"
            click SOCKSUDP "https://github.com/fossabot/clash/blob/master/proxy/socks/udp.go"
        end
    end

    %% Core Processing
    subgraph "Core Processors"
        direction TB
        RuleEngine["Rule Engine"]:::core
        HubNode["Hub (Config Manager & REST API)"]:::core
    end
    click RuleEngine "https://github.com/fossabot/clash/blob/master/rules/domain_suffix.go"
    click RuleEngine "https://github.com/fossabot/clash/blob/master/rules/domain_keyword.go"
    click RuleEngine "https://github.com/fossabot/clash/blob/master/rules/geoip.go"
    click RuleEngine "https://github.com/fossabot/clash/blob/master/rules/ipcidr.go"
    click RuleEngine "https://github.com/fossabot/clash/blob/master/rules/final.go"
    click RuleEngine "https://github.com/fossabot/clash/blob/master/constant/rule.go"
    click RuleEngine "https://github.com/fossabot/clash/blob/master/constant/addr.go"
    click HubNode "https://github.com/fossabot/clash/blob/master/hub/configs.go"
    click HubNode "https://github.com/fossabot/clash/blob/master/hub/server.go"

    %% Adapter Factory & Implementations
    subgraph "Adapters (Strategy)"
        direction TB
        AdapterFactory["Factory & Util"]:::outbound
        DirectAdapter["direct.go"]:::outbound
        RejectAdapter["reject.go"]:::outbound
        ShadowsocksAdapter["shadowsocks.go"]:::outbound
        UrlTestAdapter["urltest.go"]:::outbound
        AdapterUtil["util.go"]:::outbound
        AdapterConst["adapters.go"]:::outbound
        click DirectAdapter "https://github.com/fossabot/clash/blob/master/adapters/direct.go"
        click RejectAdapter "https://github.com/fossabot/clash/blob/master/adapters/reject.go"
        click ShadowsocksAdapter "https://github.com/fossabot/clash/blob/master/adapters/shadowsocks.go"
        click UrlTestAdapter "https://github.com/fossabot/clash/blob/master/adapters/urltest.go"
        click AdapterUtil "https://github.com/fossabot/clash/blob/master/adapters/util.go"
        click AdapterConst "https://github.com/fossabot/clash/blob/master/constant/adapters.go"
    end

    %% Tunnel Manager
    subgraph "Tunnel Manager"
        direction TB
        TunnelCore["tunnel.go"]:::outbound
        TunnelLog["log.go"]:::outbound
        TunnelUtil["utils.go"]:::outbound
        click TunnelCore "https://github.com/fossabot/clash/blob/master/tunnel/tunnel.go"
        click TunnelLog "https://github.com/fossabot/clash/blob/master/tunnel/log.go"
        click TunnelUtil "https://github.com/fossabot/clash/blob/master/tunnel/utils.go"
    end

    %% Support Services
    subgraph "Support Services"
        direction TB
        Observable["Observable/EventBus"]:::support
        GeoIPDB["GeoIP Database"]:::support
        click Observable "https://github.com/fossabot/clash/blob/master/observable/observable.go"
        click Observable "https://github.com/fossabot/clash/blob/master/observable/iterable.go"
        click Observable "https://github.com/fossabot/clash/blob/master/observable/subscriber.go"
        click Observable "https://github.com/fossabot/clash/blob/master/observable/util.go"
    end

    %% Shared Constants & Docs
    subgraph "Shared & Docs"
        direction TB
        TrafficConst["traffic.go"]:::support
        ConfigConst["config.go"]:::support
        click TrafficConst "https://github.com/fossabot/clash/blob/master/constant/traffic.go"
        click ConfigConst "https://github.com/fossabot/clash/blob/master/constant/config.go"
        Docs["README.md"]:::support
        click Docs "https://github.com/fossabot/clash/blob/master/README.md"
        Documentation["docs/"]:::support
        click Documentation "https://github.com/fossabot/clash/tree/master/docs/"
        CI[".travis.yml"]:::support
        click CI "https://github.com/fossabot/clash/blob/master/.travis.yml"
        Dockerfile["Dockerfile"]:::support
        click Dockerfile "https://github.com/fossabot/clash/tree/master/Dockerfile"
        MakefileNode["Makefile"]:::support
        click MakefileNode "https://github.com/fossabot/clash/tree/master/Makefile"
    end

    %% External Controller
    ExternalController["External Controller (REST API)"]:::core

    %% External Network
    ExternalNetwork["External Network"]:::external

    %% Connections: Request Flow
    Client -->|"HTTP/SOCKS5"| HTTPServer
    Client -->|"HTTP/SOCKS5"| SOCKSTCP

    HTTPServer -->|"request"| RuleEngine
    HTTPHandler --> RuleEngine
    HTTPSHandler --> RuleEngine
    SOCKSTCP --> RuleEngine
    SOCKSUDP --> RuleEngine

    RuleEngine -->|"config lookup"| HubNode
    HubNode -->|"adapter config"| AdapterFactory

    AdapterFactory --> DirectAdapter
    AdapterFactory --> RejectAdapter
    AdapterFactory --> ShadowsocksAdapter
    AdapterFactory --> UrlTestAdapter
    AdapterFactory --> AdapterUtil

    DirectAdapter --> TunnelCore
    RejectAdapter --> TunnelCore
    ShadowsocksAdapter --> TunnelCore
    UrlTestAdapter --> TunnelCore

    TunnelCore -->|"dial"| ExternalNetwork

    %% Response Flow
    ExternalNetwork -->|"response"| TunnelCore
    TunnelCore --> RuleEngine
    RuleEngine --> Client

    %% Control & Monitoring
    ExternalController -->|"REST API calls"| HubNode
    Observable <-->|"publish/subscribe"| DirectAdapter
    Observable <-->|"publish/subscribe"| RejectAdapter
    Observable <-->|"publish/subscribe"| ShadowsocksAdapter
    Observable <-->|"publish/subscribe"| UrlTestAdapter
    Observable <-->|"publish/subscribe"| TunnelCore

    RuleEngine -->|"GeoIP lookup"| GeoIPDB

    %% Styles
    classDef ingress fill:#aecbfa,stroke:#1e88e5;
    classDef core fill:#c8e6c9,stroke:#388e3c;
    classDef outbound fill:#ffe0b2,stroke:#f57c00;
    classDef support fill:#e1bee7,stroke:#8e24aa;
    classDef external fill:#eeeeee,stroke:#616161;
```
