# surgioproject/surgio architecture

> Architecture diagram of the GitHub repository surgioproject/surgio, 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/surgioproject/surgio
- Repository: https://github.com/surgioproject/surgio

## Overview

##### Project Type and Purpose
- Its primary purpose is to allow users to define their configurations (via templates, custom providers, and filters) and then output structured proxy configuration files.
- The provided examples, guides, and documentation all center around generating configurations for various client apps like Clash, QuantumultX, and Surge.

##### File Structure to Define Major Components
- CLI Entry Points – Located in the “bin” folder (bin/dev, bin/run) with the main Node.js entry transitions into the actual code in the “src” directory.
- Command Handlers – Found in “src/commands”; these modules (e.g., check, generate, new, lint) process user commands from the CLI.
- Core Modules:
- Configuration Management: “src/config.ts”, “config.js”, and “configurables.ts” handle project configuration.
- Generation Engine: “src/generator” is responsible for processing templates and creating the final configuration output.
- Provider Implementations: “src/provider” contains multiple provider classes (e.g., ClashProvider, ShadowsocksSubscribeProvider) for different proxy standards.
- Filters and Validators: “src/filters” and “src/validators” ensure that configuration data is processed and validated correctly before generation.
- Utility Functions: “src/utils” provides common functions (for HTTP requests, error handling, etc.) that are shared across the project.
- Testing and Examples – The “test” and “examples” directories contain unit tests and sample configurations to validate functionality and guide users.

##### Relationships and Interactions Between Components
- The CLI launches from the “bin” files. This initiates command parsing (src/commands), which then directs execution to specific modules.
- Each command will invoke the configuration module to load user preferences and settings.
- The generator module (src/generator) uses provider modules (src/provider) along with templates to build the final output.
- Filters (src/filters) are applied to refine the configuration data.
- Validators (src/validators) check that each part of the configuration meets expected standards before outputting the final configuration file.
- Utility modules (src/utils) support API calls, HTTP interactions, and error handling across these processes.

##### Architectural Patterns and Key Technologies
- Modularity: Each functionality (commands, providers, filters, validators, and utilities) is separated into its own module, promoting extensibility.
- CLI Command Pattern: The “src/commands” folder demonstrates a clear command-based architecture where each command encapsulates specific behaviors.
- Plugin/Provider Pattern: The “src/provider” directory shows how different proxy providers are implemented in a pluggable fashion.
- Testing is emphasized with dedicated directories for unit tests, ensuring each module’s reliability.
- The project uses TypeScript (evident from .ts files and tsconfig files) to enforce type-safety and maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI("User CLI Input"):::cli
        CLIDev("CLI: dev"):::cli
        CLIRun("CLI: run"):::cli
        CH("Command Handlers (src/commands)"):::cli
    end

    CLI --> CLIDev
    CLI --> CLIRun
    CLIDev --> CH
    CLIRun --> CH

    %% Configuration Management Group
    subgraph "Configuration Management"
        direction TB
        CM("Configuration Management"):::core
        CM1("config.ts"):::core_small
        CM2("config.js"):::core_small
        CM3("configurables.ts"):::core_small
        CM --> CM1
        CM --> CM2
        CM --> CM3
    end

    %% Generation Engine Group
    subgraph "Generation Engine"
        direction TB
        GE("Generation Engine"):::core
        GE1("artifact.ts"):::core_small
        GE2("index.ts"):::core_small
        GE3("json-template.ts"):::core_small
        GE4("template.ts"):::core_small
        GE --> GE1
        GE --> GE2
        GE --> GE3
        GE --> GE4
    end

    %% Provider Implementations Group
    subgraph "Provider Implementations"
        direction TB
        PI("Provider Implementations"):::core
        PI1("ClashProvider.ts"):::core_small
        PI2("ShadowsocksSubscribeProvider.ts"):::core_small
        PI3("TrojanProvider.ts"):::core_small
        PI --> PI1
        PI --> PI2
        PI --> PI3
    end

    %% Filters Group
    subgraph "Filters"
        direction TB
        F("Filters"):::core
        F1("filters.ts"):::core_small
        F2("classes.ts"):::core_small
        F3("index.ts"):::core_small
        F4("utils.ts"):::core_small
        F --> F1
        F --> F2
        F --> F3
        F --> F4
    end

    %% Validators Group
    subgraph "Validators"
        direction TB
        V("Validators"):::core
        V1("surgio-config.ts"):::core_small
        V2("shadowsocks.ts"):::core_small
        V3("trojan.ts"):::core_small
        V --> V1
        V --> V2
        V --> V3
    end

    %% Supporting Modules
    UF("Utility Functions (src/utils)"):::support

    %% Testing and Examples
    subgraph "Testing & Examples"
        T("Testing (test)"):::test
        E("Examples (examples)"):::test
    end

    %% Flow Connections Between Groups
    CH -->|"loads config"| CM
    CM -->|"provides settings"| GE
    GE -->|"generates output via"| PI
    GE -->|"applies"| F
    F -->|"validated by"| V

    %% Utility Functions supporting core modules
    UF --- CM
    UF --- GE
    UF --- PI
    UF --- F
    UF --- V

    %% Testing & Examples validate commands
    CH -->|"verified by"| T
    CH -->|"illustrated by"| E

    %% Click Events for CLI Entry Points and Command Handlers
    click CLIDev "https://github.com/surgioproject/surgio/tree/master/bin/dev"
    click CLIRun "https://github.com/surgioproject/surgio/tree/master/bin/run"
    click CH "https://github.com/surgioproject/surgio/tree/master/src/commands"

    %% Click Events for Configuration Management
    click CM1 "https://github.com/surgioproject/surgio/blob/master/src/config.ts"
    click CM2 "https://github.com/surgioproject/surgio/blob/master/config.js"
    click CM3 "https://github.com/surgioproject/surgio/blob/master/src/configurables.ts"

    %% Click Events for Generation Engine
    click GE1 "https://github.com/surgioproject/surgio/blob/master/src/generator/artifact.ts"
    click GE2 "https://github.com/surgioproject/surgio/blob/master/src/generator/index.ts"
    click GE3 "https://github.com/surgioproject/surgio/blob/master/src/generator/json-template.ts"
    click GE4 "https://github.com/surgioproject/surgio/blob/master/src/generator/template.ts"

    %% Click Events for Provider Implementations
    click PI1 "https://github.com/surgioproject/surgio/blob/master/src/provider/ClashProvider.ts"
    click PI2 "https://github.com/surgioproject/surgio/blob/master/src/provider/ShadowsocksSubscribeProvider.ts"
    click PI3 "https://github.com/surgioproject/surgio/blob/master/src/provider/TrojanProvider.ts"

    %% Click Events for Filters
    click F1 "https://github.com/surgioproject/surgio/blob/master/src/filters/filters.ts"
    click F2 "https://github.com/surgioproject/surgio/blob/master/src/filters/classes.ts"
    click F3 "https://github.com/surgioproject/surgio/blob/master/src/filters/index.ts"
    click F4 "https://github.com/surgioproject/surgio/blob/master/src/filters/utils.ts"

    %% Click Events for Validators
    click V1 "https://github.com/surgioproject/surgio/blob/master/src/validators/surgio-config.ts"
    click V2 "https://github.com/surgioproject/surgio/blob/master/src/validators/shadowsocks.ts"
    click V3 "https://github.com/surgioproject/surgio/blob/master/src/validators/trojan.ts"

    %% Click Event for Utility Functions
    click UF "https://github.com/surgioproject/surgio/tree/master/src/utils"

    %% Click Events for Testing and Examples
    click T "https://github.com/surgioproject/surgio/tree/master/test"
    click E "https://github.com/surgioproject/surgio/tree/master/examples"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef core fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef core_small fill:#FDEBD0,stroke:#E67E22,stroke-width:1px;
    classDef support fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef test fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
```
