# vpn-subcription-links/clashx-v2ray-topfreeproxy architecture

> Architecture diagram of the GitHub repository vpn-subcription-links/clashx-v2ray-topfreeproxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vpn-subcription-links/clashx-v2ray-topfreeproxy
- Repository: https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy

## Overview

This repository publishes combined Clash and V2Ray subscriptions from a configurable registry of upstream feeds. The main maintenance workflow is to load enabled sources, fetch and parse their feeds, merge and validate both formats, then publish subscription files and health reports; optional Mihomo validation can block publication. Users then add a published link to a compatible client. The excerpts show the refresh orchestration and several processing layers, but not every call within refresh, so some documented or indexed relationships are cited at the orchestrator rather than inferred as a detailed pipeline.

Main entry points: [`combine/refresh.py`](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/refresh.py) (Refresh Orchestrator), [`combine/sources.json`](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/sources.json) (Feed Registry), [`combine/download.py`](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/download.py) (Feed Downloader), [`combine/combine.py`](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/combine.py) (Feed Parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_registry["Source Registry"]
  node_sources["Feed Registry<br/>[sources.json]"]
  node_link_manager["Link Manager<br/>[sources.py]"]
end

subgraph group_processing["Refresh Processing"]
  node_refresh["Refresh Orchestrator<br/>[refresh.py]"]
  node_fetcher["Feed Downloader<br/>[download.py]"]
  node_proxy_parser["Feed Parsing<br/>[combine.py]"]
  node_protocol_checks["Protocol Checks<br/>[validation.py]"]
  node_clash_merge["Clash Merger<br/>[combine.py]"]
  node_v2ray_merge["V2Ray Merger<br/>[combine.py]"]
  node_mihomo["Mihomo Validator<br/>[engine.py]"]
end

subgraph group_publishing["Published Subscriptions"]
  node_clash_output["Clash Subscription<br/>[clash.config.yaml]"]
  node_v2ray_output["V2Ray Subscription<br/>[v2ray.config.txt]"]
  node_health_report["Source Health<br/>[health.json]"]
end

subgraph group_consumption["Client Setup"]
  node_clash_client["Clash Client"]
  node_v2ray_client["V2Ray Client"]
end

node_maintainer(("Maintainer"))
node_client_user(("Client User"))
node_upstream_feeds["Feed Providers"]

node_maintainer -->|"edits sources"| node_sources
node_sources -->|"configures links"| node_link_manager
node_maintainer -->|"runs refresh"| node_refresh
node_refresh -->|"loads registry"| node_sources
node_refresh -->|"fetches feeds"| node_fetcher
node_fetcher -->|"requests feeds"| node_upstream_feeds
node_refresh -->|"parses feeds"| node_proxy_parser
node_proxy_parser -->|"checks protocols"| node_protocol_checks
node_refresh -->|"merges Clash"| node_clash_merge
node_refresh -->|"merges V2Ray"| node_v2ray_merge
node_refresh -.->|"validates optionally"| node_mihomo
node_refresh -->|"writes subscription"| node_clash_output
node_refresh -->|"writes subscription"| node_v2ray_output
node_refresh -->|"writes status"| node_health_report
node_client_user -->|"sets up"| node_clash_client
node_client_user -->|"sets up"| node_v2ray_client
node_clash_output -->|"provides link"| node_clash_client
node_v2ray_output -->|"provides link"| node_v2ray_client

click node_sources "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/sources.json"
click node_link_manager "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/sources.py"
click node_refresh "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/refresh.py"
click node_fetcher "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/download.py"
click node_proxy_parser "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/combine.py"
click node_protocol_checks "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/validation.py"
click node_clash_merge "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/combine.py"
click node_v2ray_merge "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/combine.py"
click node_mihomo "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/engine.py"
click node_clash_output "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/clash.config.yaml"
click node_v2ray_output "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/v2ray.config.txt"
click node_health_report "https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/health.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_sources,node_link_manager,node_client_user toneBlue
class node_refresh,node_fetcher,node_proxy_parser,node_protocol_checks,node_clash_merge,node_v2ray_merge,node_mihomo toneAmber
class node_clash_output,node_v2ray_output,node_health_report toneMint
class node_clash_client,node_v2ray_client toneRose
class node_maintainer,node_upstream_feeds toneIndigo
```

## Components

### Source Registry

- [Feed Registry](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/sources.json): `combine/sources.json`
- [Link Manager](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/sources.py): `combine/sources.py`

### Refresh Processing

- [Refresh Orchestrator](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/refresh.py): `combine/refresh.py`
- [Feed Downloader](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/download.py): `combine/download.py`
- [Feed Parsing](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/combine.py): `combine/combine.py`
- [Protocol Checks](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/validation.py): `combine/validation.py`
- [Clash Merger](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/combine.py): `combine/combine.py`
- [V2Ray Merger](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/combine.py): `combine/combine.py`
- [Mihomo Validator](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/engine.py): `combine/engine.py`

### Published Subscriptions

- [Clash Subscription](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/clash.config.yaml): `combine/clash.config.yaml`
- [V2Ray Subscription](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/v2ray.config.txt): `combine/v2ray.config.txt`
- [Source Health](https://github.com/vpn-subcription-links/clashx-v2ray-topfreeproxy/blob/main/combine/health.json): `combine/health.json`

### Client Setup

- **Clash Client**
- **V2Ray Client**

### Other components

- **Maintainer**
- **Client User**
- **Feed Providers**

## Connections

- Maintainer → Feed Registry: edits sources (evidence: `README.md`)
- Feed Registry → Link Manager: configures links (evidence: `combine/sources.py`)
- Maintainer → Refresh Orchestrator: runs refresh (evidence: `README.md`)
- Refresh Orchestrator → Feed Registry: loads registry (evidence: `combine/refresh.py`)
- Refresh Orchestrator → Feed Downloader: fetches feeds (evidence: `combine/refresh.py`)
- Feed Downloader → Feed Providers: requests feeds (evidence: `combine/download.py`)
- Refresh Orchestrator → Feed Parsing: parses feeds (evidence: `combine/refresh.py`)
- Feed Parsing → Protocol Checks: checks protocols (evidence: `combine/combine.py`)
- Refresh Orchestrator → Clash Merger: merges Clash (evidence: `combine/refresh.py`)
- Refresh Orchestrator → V2Ray Merger: merges V2Ray (evidence: `combine/refresh.py`)
- Refresh Orchestrator → Mihomo Validator: validates optionally (evidence: `combine/refresh.py`)
- Refresh Orchestrator → Clash Subscription: writes subscription (evidence: `combine/refresh.py`)
- Refresh Orchestrator → V2Ray Subscription: writes subscription (evidence: `combine/refresh.py`)
- Refresh Orchestrator → Source Health: writes status (evidence: `combine/refresh.py`)
- Client User → Clash Client: sets up (evidence: `README.md`)
- Client User → V2Ray Client: sets up (evidence: `README.md`)
- Clash Subscription → Clash Client: provides link (evidence: `README.md`)
- V2Ray Subscription → V2Ray Client: provides link (evidence: `README.md`)
