# oscar-googol/workervless2sub architecture

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

- Interactive diagram: https://gitdiagram.com/oscar-googol/workervless2sub
- Repository: https://github.com/oscar-googol/workervless2sub

## Overview

WorkerVless2sub is a Cloudflare Worker that turns user-supplied or configured VMess/VLESS/Trojan node details into optimized subscriptions. Its main workflow accepts either a quick `/auto` request or a custom `/sub` request, gathers preferred line candidates, and returns a subscription in the requested format. The README also documents a browser-based one-click generator, Clash/Sing-box conversion, scheduled-style dynamic UUIDs, and Telegram notifications. Runtime logic is concentrated in `_worker.js`; unsampled implementation details are represented only where the README documents the capability.

Main entry points: [`_worker.js`](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js) (Worker handler), [`addressesapi.txt`](https://github.com/oscar-googol/workervless2sub/blob/main/addressesapi.txt) (Address lists), [`addressescsv.csv`](https://github.com/oscar-googol/workervless2sub/blob/main/addressescsv.csv) (Speed-test CSV), [`addressesipv6api.txt`](https://github.com/oscar-googol/workervless2sub/blob/main/addressesipv6api.txt) (IPv6 addresses)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request and UI"]
  node_worker["Worker handler<br/>[_worker.js]"]
  node_request_config["Request config<br/>[_worker.js]"]
  node_web_generator["Web generator<br/>[_worker.js]"]
end

subgraph group_lines["Line sources"]
  node_static_lines["Static candidates<br/>[_worker.js]"]
  node_remote_lists["Remote address lists<br/>[_worker.js]"]
  node_csv_candidates["CSV candidates<br/>[_worker.js]"]
  node_proxy_pool["Proxy IP pool<br/>[_worker.js]"]
  node_address_text["Address lists<br/>[addressesapi.txt]"]
  node_address_csv["Speed-test CSV<br/>[addressescsv.csv]"]
  node_ipv6_list["IPv6 addresses"]
end

subgraph group_subscription["Subscription output"]
  node_node_builder["Node builder<br/>[_worker.js]"]
  node_dynamic_uuid["Dynamic UUID<br/>[_worker.js]"]
  node_format_output["Subscription formats<br/>[_worker.js]"]
end

subgraph group_integrations["External integrations"]
  node_converter["Subconverter service"]
  node_ip_lookup["IP geolocation"]
  node_telegram["Telegram bot"]
end

node_user(("Subscriber"))
node_subscription_client(("Subscription client"))

node_user -->|"sends request"| node_worker
node_worker -->|"serves page"| node_web_generator
node_web_generator -->|"submits details"| node_worker
node_worker -->|"parses parameters"| node_request_config
node_request_config -->|"loads configured lines"| node_static_lines
node_request_config -->|"selects list URLs"| node_remote_lists
node_remote_lists -.->|"fetches list"| node_address_text
node_remote_lists -.->|"fetches list"| node_ipv6_list
node_request_config -->|"selects CSV URLs"| node_csv_candidates
node_csv_candidates -.->|"fetches measurements"| node_address_csv
node_worker -->|"builds nodes"| node_node_builder
node_worker -->|"derives UUIDs"| node_dynamic_uuid
node_worker -->|"formats subscription"| node_format_output
node_format_output -.->|"requests conversion"| node_converter
node_worker -.->|"looks up IP details"| node_ip_lookup
node_worker -.->|"sends notification"| node_telegram
node_format_output -->|"returns subscription"| node_subscription_client
node_worker -->|"collects proxy IPs"| node_proxy_pool

click node_worker "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"
click node_request_config "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"
click node_web_generator "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"
click node_static_lines "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"
click node_remote_lists "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"
click node_csv_candidates "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"
click node_proxy_pool "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"
click node_address_text "https://github.com/oscar-googol/workervless2sub/blob/main/addressesapi.txt"
click node_address_csv "https://github.com/oscar-googol/workervless2sub/blob/main/addressescsv.csv"
click node_ipv6_list "https://github.com/oscar-googol/workervless2sub/blob/main/addressesipv6api.txt"
click node_node_builder "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"
click node_dynamic_uuid "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"
click node_format_output "https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js"

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_worker,node_request_config,node_web_generator,node_subscription_client toneBlue
class node_static_lines,node_remote_lists,node_csv_candidates,node_proxy_pool,node_address_text,node_address_csv,node_ipv6_list toneAmber
class node_node_builder,node_dynamic_uuid,node_format_output toneMint
class node_converter,node_ip_lookup,node_telegram toneRose
class node_user toneIndigo
```

## Components

### Request and UI

- [Worker handler](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`
- [Request config](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`
- [Web generator](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`

### Line sources

- [Static candidates](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`
- [Remote address lists](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`
- [CSV candidates](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`
- [Proxy IP pool](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`
- [Address lists](https://github.com/oscar-googol/workervless2sub/blob/main/addressesapi.txt): `addressesapi.txt`
- [Speed-test CSV](https://github.com/oscar-googol/workervless2sub/blob/main/addressescsv.csv): `addressescsv.csv`
- [IPv6 addresses](https://github.com/oscar-googol/workervless2sub/blob/main/addressesipv6api.txt): `addressesipv6api.txt`

### Subscription output

- [Node builder](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`
- [Dynamic UUID](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`
- [Subscription formats](https://github.com/oscar-googol/workervless2sub/blob/main/_worker.js): `_worker.js`

### External integrations

- **Subconverter service**
- **IP geolocation**
- **Telegram bot**

### Other components

- **Subscriber**
- **Subscription client**

## Connections

- Subscriber → Worker handler: sends request
- Worker handler → Web generator: serves page
- Web generator → Worker handler: submits details
- Worker handler → Request config: parses parameters
- Request config → Static candidates: loads configured lines
- Request config → Remote address lists: selects list URLs
- Remote address lists → Address lists: fetches list
- Remote address lists → IPv6 addresses: fetches list
- Request config → CSV candidates: selects CSV URLs
- CSV candidates → Speed-test CSV: fetches measurements
- Worker handler → Node builder: builds nodes
- Worker handler → Dynamic UUID: derives UUIDs
- Worker handler → Subscription formats: formats subscription
- Subscription formats → Subconverter service: requests conversion
- Worker handler → IP geolocation: looks up IP details
- Worker handler → Telegram bot: sends notification
- Subscription formats → Subscription client: returns subscription
- Worker handler → Proxy IP pool: collects proxy IPs