# mahdibland/v2rayaggregator architecture

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

- Interactive diagram: https://gitdiagram.com/mahdibland/v2rayaggregator
- Repository: https://github.com/mahdibland/v2rayaggregator

## Overview

V2RayAggregator collects public proxy subscriptions and free-airport subscriptions, converts and validates their nodes, then tests and ranks them before publishing mixed, Base64, and Clash outputs. Public-node and airport processing are separate branches. README documents the overall speed-filtering workflow and output formats; sampled code confirms key collection, conversion, and output operations, but does not expose the full speed-test orchestration, so that connection is documented rather than inferred from unsampled workflow files.

Main entry points: [`utils/list_merge.py`](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge.py) (Public source refresh), [`utils/list_merge_airport.py`](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge_airport.py) (Airport source refresh), [`utils/sub_convert.py`](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/sub_convert.py) (Subscription conversion), [`utils/get_subs.py`](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/get_subs.py) (Public subscription fetch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Subscription collection"]
  node_public_refresh["Public source refresh<br/>[list_merge.py]"]
  node_airport_refresh["Airport source refresh"]
  node_url_updates["URL updates<br/>[list_update.py]"]
  node_public_fetch["Public subscription fetch<br/>[get_subs.py]"]
  node_airport_fetch["Airport subscription fetch<br/>[get_subs.py]"]
  node_subscriptions[("Subscription lists<br/>[sub_list.json]")]
  node_airport_subscriptions[("Airport subscription lists")]
end

subgraph group_processing["Node processing"]
  node_converter["Subscription conversion<br/>[sub_convert.py]"]
  node_node_checks["Node validation<br/>[subs_function.py]"]
  node_public_merge["Public node merge<br/>[list_merge.py]"]
  node_airport_merge["Airport node merge"]
end

subgraph group_testing["Speed testing"]
  node_public_speed["Public speed results<br/>[output.py]"]
  node_airport_speed["Airport speed results<br/>[output.py]"]
end

subgraph group_outputs["Published outputs"]
  node_public_publish["Public node outputs<br/>[output.py]"]
  node_airport_publish["Airport node outputs<br/>[output.py]"]
  node_public_clash["Public Clash config"]
  node_airport_clash["Airport Clash config"]
end

node_automation(("Scheduled automation"))
node_sources(("Subscription sources"))
node_speedtest["LiteSpeedTest"]

node_automation -.->|"starts collection"| node_public_refresh
node_automation -.->|"starts collection"| node_airport_refresh
node_sources -.->|"provides URLs"| node_public_refresh
node_sources -.->|"provides URLs"| node_airport_refresh
node_public_refresh -->|"updates URLs"| node_url_updates
node_airport_refresh -->|"updates URLs"| node_url_updates
node_public_refresh -->|"fetches subscriptions"| node_public_fetch
node_airport_refresh -->|"fetches subscriptions"| node_airport_fetch
node_public_refresh -.->|"reads list"| node_subscriptions
node_airport_refresh -->|"reads list"| node_airport_subscriptions
node_public_fetch -->|"converts content"| node_converter
node_public_fetch -->|"validates nodes"| node_node_checks
node_public_refresh -->|"merges nodes"| node_public_merge
node_airport_refresh -.->|"merges nodes"| node_airport_merge
node_public_merge -->|"formats output"| node_converter
node_public_merge -.->|"checks nodes"| node_node_checks
node_airport_merge -.->|"formats output"| node_converter
node_public_merge -.->|"shares fetcher"| node_airport_fetch
node_public_speed -->|"writes ranked nodes"| node_public_publish
node_airport_speed -->|"writes ranked nodes"| node_airport_publish
node_speedtest -.->|"produces results"| node_public_speed
node_speedtest -.->|"produces results"| node_airport_speed
node_public_publish -.->|"supplies nodes"| node_public_clash
node_airport_publish -.->|"supplies nodes"| node_airport_clash
node_public_clash -->|"uses conversion"| node_converter
node_airport_clash -->|"uses conversion"| node_converter

click node_public_refresh "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge.py"
click node_airport_refresh "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge_airport.py"
click node_url_updates "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_update.py"
click node_public_fetch "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/get_subs.py"
click node_airport_fetch "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/get_subs.py"
click node_converter "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/sub_convert.py"
click node_node_checks "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/subs_function.py"
click node_public_merge "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge.py"
click node_airport_merge "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge_airport.py"
click node_public_speed "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/speedtest/output.py"
click node_airport_speed "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/airport/speedtest/output.py"
click node_public_publish "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/speedtest/output.py"
click node_airport_publish "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/airport/speedtest/output.py"
click node_public_clash "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/eternity_convert.py"
click node_airport_clash "https://github.com/mahdibland/v2rayaggregator/blob/master/utils/eternity_convert_airport.py"
click node_subscriptions "https://github.com/mahdibland/v2rayaggregator/blob/master/sub/sub_list.json"
click node_airport_subscriptions "https://github.com/mahdibland/v2rayaggregator/blob/master/sub/sub_list_airport.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_refresh,node_airport_refresh,node_url_updates,node_public_fetch,node_airport_fetch,node_subscriptions,node_airport_subscriptions toneBlue
class node_converter,node_node_checks,node_public_merge,node_airport_merge toneAmber
class node_public_speed,node_airport_speed toneMint
class node_public_publish,node_airport_publish,node_public_clash,node_airport_clash toneRose
class node_automation,node_sources,node_speedtest toneIndigo
```

## Components

### Subscription collection

- [Public source refresh](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge.py): `utils/list_merge.py`
- [Airport source refresh](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge_airport.py): `utils/list_merge_airport.py`
- [URL updates](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_update.py): `utils/list_update.py`
- [Public subscription fetch](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/get_subs.py): `utils/get_subs.py`
- [Airport subscription fetch](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/get_subs.py): `utils/get_subs.py`
- [Subscription lists](https://github.com/mahdibland/v2rayaggregator/blob/master/sub/sub_list.json): `sub/sub_list.json`
- [Airport subscription lists](https://github.com/mahdibland/v2rayaggregator/blob/master/sub/sub_list_airport.json): `sub/sub_list_airport.json`

### Node processing

- [Subscription conversion](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/sub_convert.py): `utils/sub_convert.py`
- [Node validation](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/subs_function.py): `utils/subs_function.py`
- [Public node merge](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge.py): `utils/list_merge.py`
- [Airport node merge](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/list_merge_airport.py): `utils/list_merge_airport.py`

### Speed testing

- [Public speed results](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/speedtest/output.py): `utils/speedtest/output.py`
- [Airport speed results](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/airport/speedtest/output.py): `utils/airport/speedtest/output.py`

### Published outputs

- [Public node outputs](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/speedtest/output.py): `utils/speedtest/output.py`
- [Airport node outputs](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/airport/speedtest/output.py): `utils/airport/speedtest/output.py`
- [Public Clash config](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/eternity_convert.py): `utils/eternity_convert.py`
- [Airport Clash config](https://github.com/mahdibland/v2rayaggregator/blob/master/utils/eternity_convert_airport.py): `utils/eternity_convert_airport.py`

### Other components

- **Scheduled automation**
- **Subscription sources**
- **LiteSpeedTest**

## Connections

- Scheduled automation → Public source refresh: starts collection
- Scheduled automation → Airport source refresh: starts collection
- Subscription sources → Public source refresh: provides URLs
- Subscription sources → Airport source refresh: provides URLs
- Public source refresh → URL updates: updates URLs (evidence: `utils/list_merge.py`)
- Airport source refresh → URL updates: updates URLs (evidence: `utils/list_merge_airport.py`)
- Public source refresh → Public subscription fetch: fetches subscriptions (evidence: `utils/list_merge.py`)
- Airport source refresh → Airport subscription fetch: fetches subscriptions (evidence: `utils/list_merge_airport.py`)
- Public source refresh → Subscription lists: reads list
- Airport source refresh → Airport subscription lists: reads list (evidence: `utils/list_merge_airport.py`)
- Public subscription fetch → Subscription conversion: converts content (evidence: `utils/get_subs.py`)
- Public subscription fetch → Node validation: validates nodes (evidence: `utils/get_subs.py`)
- Public source refresh → Public node merge: merges nodes (evidence: `utils/list_merge.py`)
- Airport source refresh → Airport node merge: merges nodes (evidence: `utils/list_merge_airport.py`)
- Public node merge → Subscription conversion: formats output (evidence: `utils/list_merge.py`)
- Public node merge → Node validation: checks nodes
- Airport node merge → Subscription conversion: formats output (evidence: `utils/list_merge_airport.py`)
- Public node merge → Airport subscription fetch: shares fetcher (evidence: `utils/list_merge.py`)
- Public speed results → Public node outputs: writes ranked nodes (evidence: `utils/speedtest/output.py`)
- Airport speed results → Airport node outputs: writes ranked nodes (evidence: `utils/airport/speedtest/output.py`)
- LiteSpeedTest → Public speed results: produces results
- LiteSpeedTest → Airport speed results: produces results
- Public node outputs → Public Clash config: supplies nodes
- Airport node outputs → Airport Clash config: supplies nodes
- Public Clash config → Subscription conversion: uses conversion (evidence: `utils/eternity_convert.py`)
- Airport Clash config → Subscription conversion: uses conversion (evidence: `utils/eternity_convert_airport.py`)
