# crctdd/quantumultx architecture

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

- Interactive diagram: https://gitdiagram.com/crctdd/quantumultx
- Repository: https://github.com/crctdd/quantumultx

## Overview

##### Project type and purpose
- This is an open-source collection of network proxy/filter configurations and helper scripts.
- It bundles “Rule” lists (domains to block or allow), “Rewrite” JavaScript rules, standalone “Scripts” (e.g., fetching oil prices, clearing DNS cache), a “Profiles” directory with a .conf template, and some “Images”/data files.
- The README simply notes these were “borrowed” from other contributors, so this is essentially a configuration & scripting toolkit for a proxy-based environment (e.g., Surge/Quantumult/X, Loon).

##### File structure
- Top-level directories
- Profiles: .conf templates that tie everything together
- Rewrite: JS modules that define URL rewrite rules
- Rule: lists of domains/services by category (Bank, StreamingMedia, TikTok, etc.)
- Scripts: standalone JS scripts for periodic tasks
- Patterns
- Profiles/*.conf references the Rule lists and Rewrite scripts
- The proxy engine loads each type at startup
- Scripts may run on a schedule (cron) within the proxy environment
- No obvious “backend” or “frontend”—this is a toolset intended to run within a host proxy app.

##### README for additional insights
- Confirms these are third-party scripts aggregated in one repo

a. Main components
1. Configuration Manager (Profiles)
2. Rule Engine (loads Rule/*.list)
3. Rewrite Engine (loads Rewrite/*.js)
4. Script Scheduler/Executor (runs Scripts/*.js on timers or triggers)
5. Data Assets (Images/*.txt)
6. External Proxy App (e.g., Quantumult X, Surge)
b. Relationships & interactions
- The Proxy App reads Profiles/TS.conf
- Profiles.conf references:
– Rule Engine → imports each .list file
– Rewrite Engine → imports each JS rule
– Script Scheduler → imports each standalone script
- Scripts may fetch external data (oil prices, DNS) and write to local storage or update rules
c. Architectural patterns
- Modular plugin approach: each directory is a plugin‐type
- Separation of concerns: rules vs rewrites vs utility scripts
- Extensibility: new .list or .js files drop into folders automatically discovered at runtime
d. Key technologies
- JavaScript for all logic (Rewrite and Scripts)
- Plain text .list files for domain lists
- .conf format for the Profile (Surge/Quantumult style)

## Diagram (Mermaid)

```mermaid
flowchart TB
    ProxyApp["External Proxy App"]:::external
    ConfigManager["Configuration Manager\n(Profiles/TS.conf)"]:::config
    subgraph "Rule Engine" 
        RuleEngine["Rule Engine\n(Bank, TikTok, StreamingMedia)"]:::engine
    end
    subgraph "Rewrite Engine"
        SEX["SEX.js"]:::engine
    end
    subgraph "Script Scheduler/Executor"
        DD["dd_daily.js"]:::engine
        CZOIL["chaozhou_oil_price.js"]:::engine
        DNSCLEAR["dns-clear-cache.js"]:::engine
        GZOIL["guangdong_oil_price.js"]:::engine
        LICENSE["license.js"]:::engine
    end
    subgraph "Data Assets"
        COLOR["Color.txt"]:::data
        MINI["mini.txt"]:::data
        MINI1["mini-1.txt"]:::data
        MINICOLOR["miniColor.txt"]:::data
    end
    ExternalAPIs["External APIs / DNS"]:::external

    ProxyApp -->|"reads"| ConfigManager
    ConfigManager -->|"loads"| RuleEngine
    ConfigManager -->|"loads"| SEX
    ConfigManager -->|"imports"| DD
    ConfigManager -->|"imports"| CZOIL
    ConfigManager -->|"imports"| DNSCLEAR
    ConfigManager -->|"imports"| GZOIL
    ConfigManager -->|"imports"| LICENSE

    RuleEngine -->|"filters traffic"| ProxyApp
    SEX -->|"rewrites URLs"| ProxyApp

    DD -->|"executes on schedule"| ExternalAPIs
    CZOIL -->|"fetches oil prices"| ExternalAPIs
    GZOIL -->|"fetches oil prices"| ExternalAPIs
    DNSCLEAR -->|"clears cache"| ExternalAPIs
    LICENSE -->|"manages license"| ExternalAPIs

    COLOR -->|feeds data into| DD
    MINI -->|feeds data into| CZOIL
    MINI1 -->|feeds data into| GZOIL
    MINICOLOR -->|feeds data into| SEX

    click ConfigManager "https://github.com/crctdd/quantumultx/blob/main/Profiles/TS.conf"
    click RuleEngine "https://github.com/crctdd/quantumultx/tree/main/Rule/"
    click SEX "https://github.com/crctdd/quantumultx/blob/main/Rewrite/SEX.js"
    click DD "https://github.com/crctdd/quantumultx/blob/main/Scripts/dd_daily.js"
    click CZOIL "https://github.com/crctdd/quantumultx/blob/main/Scripts/chaozhou_oil_price.js"
    click DNSCLEAR "https://github.com/crctdd/quantumultx/blob/main/Scripts/dns-clear-cache.js"
    click GZOIL "https://github.com/crctdd/quantumultx/blob/main/Scripts/guangdong_oil_price.js"
    click LICENSE "https://github.com/crctdd/quantumultx/blob/main/Scripts/license.js"
    click COLOR "https://github.com/crctdd/quantumultx/blob/main/Images/Color.txt"
    click MINI "https://github.com/crctdd/quantumultx/blob/main/Images/mini.txt"
    click MINI1 "https://github.com/crctdd/quantumultx/blob/main/Images/mini-1.txt"
    click MINICOLOR "https://github.com/crctdd/quantumultx/blob/main/Images/miniColor.txt"

    classDef engine fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef config fill:#FFA500,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
