# 0xradikal/free-v2ray-configs architecture

> Architecture diagram of the GitHub repository 0xradikal/free-v2ray-configs, 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/0xradikal/free-v2ray-configs
- Repository: https://github.com/0xradikal/free-v2ray-configs

## Overview

Free V2Ray Configs aggregates public proxy configurations, filters and tests candidates, then publishes subscription formats and health/index metadata; users import those feeds into a client, while a live dashboard presents repository data. The graph preserves the documented verification, conversion, geographic, and dashboard branches. Some implementation details are unsampled, so edges are limited to shown imports/calls or README statements.

Main entry points: [`scripts/aggregate.py`](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/aggregate.py) (Aggregation), [`scripts/pipeline.py`](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/pipeline.py) (Cascade coordinator), [`dashboard-src/src/App.tsx`](https://github.com/0xradikal/free-v2ray-configs/blob/main/dashboard-src/src/App.tsx) (Dashboard application), [`scripts/countries.py`](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/countries.py) (Country feeds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and processing"]
  node_aggregate["Aggregation<br/>[aggregate.py]"]
  node_source_catalog["Source catalog<br/>[sources.py]"]
  node_core["Config engine<br/>[core.py]"]
  node_geo["GeoIP enrichment<br/>[geo.py]"]
end

subgraph group_verification["Verification cascade"]
  node_pipeline["Cascade coordinator<br/>[pipeline.py]"]
  node_filters["Structural filters<br/>[filters.py]"]
  node_reachability["TCP reachability<br/>[reachability.py]"]
  node_realtest["Proxy request tests<br/>[realtest.py]"]
end

subgraph group_publication["Feeds and metadata"]
  node_converters["Config converters<br/>[converters.py]"]
  node_mihomo["Mihomo compatibility<br/>[mihomo_compat.py]"]
  node_countries["Country feeds<br/>[countries.py]"]
  node_state["Run state<br/>[state.py]"]
  node_validate["Output validation<br/>[validate.py]"]
  node_subscriptions["Published subscriptions"]
  node_health["Health metadata<br/>[health.json]"]
  node_index["Feed index<br/>[index.json]"]
end

subgraph group_dashboard["Live dashboard"]
  node_dashboard_app["Dashboard application<br/>[App.tsx]"]
  node_dashboard_sections["Dashboard sections<br/>[sections.tsx]"]
  node_fetch_json["JSON fetch and mirrors<br/>[fetchJson.ts]"]
end

node_maintainer(("Pipeline maintainer"))
node_upstreams["Public config sources"]
node_clients(("V2Ray clients"))

node_maintainer -.->|"initiates"| node_aggregate
node_upstreams -.->|"provides configs"| node_aggregate
node_aggregate -->|"uses sources"| node_source_catalog
node_aggregate -->|"parses and deduplicates"| node_core
node_core -->|"looks up location"| node_geo
node_aggregate -->|"enriches endpoints"| node_geo
node_pipeline -->|"runs filtering"| node_filters
node_pipeline -->|"runs TCP checks"| node_reachability
node_pipeline -->|"runs request tests"| node_realtest
node_filters -->|"parses configs"| node_converters
node_pipeline -->|"uses conversions"| node_converters
node_aggregate -->|"converts outputs"| node_converters
node_aggregate -->|"checks compatibility"| node_mihomo
node_aggregate -->|"uses run state"| node_state
node_pipeline -->|"uses country feeds"| node_countries
node_countries -->|"uses config engine"| node_core
node_countries -->|"resolves countries"| node_geo
node_aggregate -->|"writes feed formats"| node_subscriptions
node_aggregate -->|"builds feed index"| node_index
node_aggregate -.->|"publishes health stats"| node_health
node_validate -.->|"validates outputs"| node_subscriptions
node_clients -->|"imports feeds"| node_subscriptions
node_dashboard_app -->|"fetches JSON"| node_fetch_json
node_dashboard_app -->|"reads metadata"| node_index
node_dashboard_app -->|"reads health data"| node_health
node_dashboard_app -->|"renders sections"| node_dashboard_sections

click node_aggregate "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/aggregate.py"
click node_source_catalog "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/sources.py"
click node_core "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/core.py"
click node_geo "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/geo.py"
click node_pipeline "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/pipeline.py"
click node_filters "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/filters.py"
click node_reachability "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/reachability.py"
click node_realtest "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/realtest.py"
click node_converters "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/converters.py"
click node_mihomo "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/mihomo_compat.py"
click node_countries "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/countries.py"
click node_state "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/state.py"
click node_validate "https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/validate.py"
click node_subscriptions "https://github.com/0xradikal/free-v2ray-configs/tree/main/all"
click node_health "https://github.com/0xradikal/free-v2ray-configs/blob/main/health.json"
click node_index "https://github.com/0xradikal/free-v2ray-configs/blob/main/index.json"
click node_dashboard_app "https://github.com/0xradikal/free-v2ray-configs/blob/main/dashboard-src/src/App.tsx"
click node_dashboard_sections "https://github.com/0xradikal/free-v2ray-configs/blob/main/dashboard-src/src/sections.tsx"
click node_fetch_json "https://github.com/0xradikal/free-v2ray-configs/blob/main/dashboard-src/src/lib/fetchJson.ts"

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_aggregate,node_source_catalog,node_core,node_geo,node_clients toneBlue
class node_pipeline,node_filters,node_reachability,node_realtest toneAmber
class node_converters,node_mihomo,node_countries,node_state,node_validate,node_subscriptions,node_health,node_index toneMint
class node_dashboard_app,node_dashboard_sections,node_fetch_json toneRose
class node_maintainer,node_upstreams toneIndigo
```

## Components

### Collection and processing

- [Aggregation](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/aggregate.py): `scripts/aggregate.py`
- [Source catalog](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/sources.py): `scripts/sources.py`
- [Config engine](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/core.py): `scripts/core.py`
- [GeoIP enrichment](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/geo.py): `scripts/geo.py`

### Verification cascade

- [Cascade coordinator](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/pipeline.py): `scripts/pipeline.py`
- [Structural filters](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/filters.py): `scripts/filters.py`
- [TCP reachability](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/reachability.py): `scripts/reachability.py`
- [Proxy request tests](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/realtest.py): `scripts/realtest.py`

### Feeds and metadata

- [Config converters](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/converters.py): `scripts/converters.py`
- [Mihomo compatibility](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/mihomo_compat.py): `scripts/mihomo_compat.py`
- [Country feeds](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/countries.py): `scripts/countries.py`
- [Run state](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/state.py): `scripts/state.py`
- [Output validation](https://github.com/0xradikal/free-v2ray-configs/blob/main/scripts/validate.py): `scripts/validate.py`
- [Published subscriptions](https://github.com/0xradikal/free-v2ray-configs/tree/main/all): `all`
- [Health metadata](https://github.com/0xradikal/free-v2ray-configs/blob/main/health.json): `health.json`
- [Feed index](https://github.com/0xradikal/free-v2ray-configs/blob/main/index.json): `index.json`

### Live dashboard

- [Dashboard application](https://github.com/0xradikal/free-v2ray-configs/blob/main/dashboard-src/src/App.tsx): `dashboard-src/src/App.tsx`
- [Dashboard sections](https://github.com/0xradikal/free-v2ray-configs/blob/main/dashboard-src/src/sections.tsx): `dashboard-src/src/sections.tsx`
- [JSON fetch and mirrors](https://github.com/0xradikal/free-v2ray-configs/blob/main/dashboard-src/src/lib/fetchJson.ts): `dashboard-src/src/lib/fetchJson.ts`

### Other components

- **Pipeline maintainer**
- **Public config sources**
- **V2Ray clients**

## Connections

- Pipeline maintainer → Aggregation: initiates
- Public config sources → Aggregation: provides configs
- Aggregation → Source catalog: uses sources (evidence: `scripts/aggregate.py`)
- Aggregation → Config engine: parses and deduplicates (evidence: `scripts/aggregate.py`)
- Config engine → GeoIP enrichment: looks up location (evidence: `scripts/core.py`)
- Aggregation → GeoIP enrichment: enriches endpoints (evidence: `scripts/aggregate.py`)
- Cascade coordinator → Structural filters: runs filtering (evidence: `scripts/pipeline.py`)
- Cascade coordinator → TCP reachability: runs TCP checks (evidence: `scripts/pipeline.py`)
- Cascade coordinator → Proxy request tests: runs request tests (evidence: `scripts/pipeline.py`)
- Structural filters → Config converters: parses configs (evidence: `scripts/filters.py`)
- Cascade coordinator → Config converters: uses conversions (evidence: `scripts/pipeline.py`)
- Aggregation → Config converters: converts outputs (evidence: `scripts/aggregate.py`)
- Aggregation → Mihomo compatibility: checks compatibility (evidence: `scripts/aggregate.py`)
- Aggregation → Run state: uses run state (evidence: `scripts/aggregate.py`)
- Cascade coordinator → Country feeds: uses country feeds (evidence: `scripts/pipeline.py`)
- Country feeds → Config engine: uses config engine (evidence: `scripts/countries.py`)
- Country feeds → GeoIP enrichment: resolves countries (evidence: `scripts/countries.py`)
- Aggregation → Published subscriptions: writes feed formats (evidence: `scripts/aggregate.py`)
- Aggregation → Feed index: builds feed index (evidence: `scripts/aggregate.py`)
- Aggregation → Health metadata: publishes health stats
- Output validation → Published subscriptions: validates outputs
- V2Ray clients → Published subscriptions: imports feeds (evidence: `README.md`)
- Dashboard application → JSON fetch and mirrors: fetches JSON (evidence: `dashboard-src/src/App.tsx`)
- Dashboard application → Feed index: reads metadata (evidence: `README.md`)
- Dashboard application → Health metadata: reads health data (evidence: `README.md`)
- Dashboard application → Dashboard sections: renders sections (evidence: `dashboard-src/src/App.tsx`)
