# sagernet/sing architecture

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

- Interactive diagram: https://gitdiagram.com/sagernet/sing
- Repository: https://github.com/sagernet/sing

## Overview

##### Main Components
a. Common Utilities Layer – The “common” directory holds a wide range of reusable packages such as:
- Atomic operations, binary encoding, and buffer management ("atomic", "binary", "buf", "bufio").
- Network and system-specific functions (“network”, “control”, “tls”, “debug”).
- Various utility functions (e.g. “json”, “domain”, “cache”, “metadata”, “observable”).
b. Protocol Layer – The “protocol” directory provides implementations for:
- HTTP-based communication (“protocol/http” – handling address resolution, client connections, handshake, etc.).
- SOCKS protocol support (“protocol/socks” and its submodules for SOCKS4 and SOCKS5, including specialized handshake and packet handling functions).
c. Service/API Layer – In the “service” directory, utilities and service managers are found for:
- File management (“service/filemanager”).
- A “pause” functionality and broader registry services.
d. Additional Utilities – The “contrab” directory supplies auxiliary but essential components:
- A freelru caching mechanism and maphash implementations that are valuable for performance-critical caching and hashing operations.

##### Relationships and Interactions
- The common utilities serve as the foundation for nearly every other part of the system. They are used by both the protocol and service layers.
- The protocol layer abstracts and implements networking logic. It leverages common packages (like those found in “network”, “tls”, “bufio”, etc.) to handle the intricacies of HTTP and SOCKS communication.
- The service layer builds upon the protocol layer and the common utilities to provide higher-level service orchestration (for example, handling file management and pause/resume functionality).
- The additional utilities in “contrab” (like freelru) are cross-cutting components that integrate into different parts of the system (for caching results in protocols or services).

##### Architectural Patterns and Design Principles
- Modular/Layered Approach – The clear separation into “common,” “protocol,” “service,” and “contrab” reflects a layered design, which is typical in large-scale systems. Each layer has a set of well-defined responsibilities.
- Reusability – The “common” directory indicates a strong focus on extracting reusable components that can be shared across different parts of the project.
- Abstraction and Separation of Concerns – The separation between protocol implementations and service orchestration suggests that each module is designed to handle specific tasks, making the overall system easier to maintain and extend.
- Platform-specific adaptations are evident (for example, different source files for Unix/Windows in “bufio,” “control,” “ntp,” etc.), which reflects a design that takes into account diverse operating environments.

##### Relevant Technologies and Libraries
- Go Modules (indicated by go.mod and go.sum) suggest dependency management via Go’s native tooling.
- The project uses go-specific linters and workflows (see “.golangci.yml” and GitHub Actions workflows in “.github/workflows”), highlighting best practices for code quality and CI/CD.
- The existence of Makefile indicates build automation for running tests and linters.

##### Final Remarks
- The goal is to provide a visual map that makes it clear how foundational utilities, protocol implementations, and higher-level services interact. This helps in understanding the separation of concerns, ease of testing individual parts, and the potential for future extensions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Common Utilities Layer
    subgraph "Common Utilities"
        COMMON["Common Utilities\n(Buffer, atomic ops, etc.)"]:::common
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        HTTP["HTTP Communication\n(Address resolution, handshake)"]:::protocol
        SOCKS["SOCKS Communication\n(Protocol support for SOCKS)"]:::protocol
        subgraph "SOCKS Protocol Details"
            SOCKS4["SOCKS4\n(Handshake, packet handling)"]:::protocol
            SOCKS5["SOCKS5\n(Handshake, packet handling)"]:::protocol
        end
    end

    %% Service/API Layer
    subgraph "Service/API Layer"
        FILEMGMT["File Management\n(Orchestrates file operations)"]:::service
        PAUSE["Pause Functionality\n(Manages pause/resume)"]:::service
    end

    %% Additional Utilities
    CONTRAB["Contrab Utilities\n(freelru, maphash)"]:::contrab

    %% Relationships
    HTTP -->|"uses"| COMMON
    SOCKS -->|"uses"| COMMON
    SOCKS4 -->|"part_of"| SOCKS
    SOCKS5 -->|"part_of"| SOCKS

    FILEMGMT -->|"leverages"| HTTP
    FILEMGMT -->|"leverages"| COMMON
    PAUSE -->|"leverages"| HTTP
    PAUSE -->|"leverages"| COMMON

    CONTRAB -.-> COMMON
    CONTRAB -.-> HTTP
    CONTRAB -.-> SOCKS
    CONTRAB -.-> FILEMGMT
    CONTRAB -.-> PAUSE

    %% Click Events
    click COMMON "https://github.com/sagernet/sing/tree/dev/common"
    click HTTP "https://github.com/sagernet/sing/tree/dev/protocol/http"
    click SOCKS "https://github.com/sagernet/sing/tree/dev/protocol/socks"
    click FILEMGMT "https://github.com/sagernet/sing/tree/dev/service/filemanager"
    click PAUSE "https://github.com/sagernet/sing/tree/dev/service/pause"
    click CONTRAB "https://github.com/sagernet/sing/tree/dev/contrab"

    %% Styles
    classDef common fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef protocol fill:#aed6f1,stroke:#21618c,stroke-width:2px;
    classDef service fill:#a9dfbf,stroke:#196f3d,stroke-width:2px;
    classDef contrab fill:#f5b7b1,stroke:#922b21,stroke-width:2px;
```
