# pxzya/v2scan architecture

> Architecture diagram of the GitHub repository pxzya/v2scan, 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/pxzya/v2scan
- Repository: https://github.com/pxzya/v2scan

## Overview

V2Scan is a desktop scanner for Telegram-sourced proxy and VPN share links. The user selects a public channel or subscription, optionally configures discovery through a SOCKS proxy, and starts a scan; the backend retrieves and extracts links, tests config endpoints, enriches results with country flags, and streams results to the interface for display or export. Saved channels persist locally. The README provides only the product name, so this map relies on the sampled source descriptions and excerpts; some wiring beyond those excerpts is omitted.

Main entry points: [`api.py`](https://github.com/pxzya/v2scan/blob/main/api.py) (Scan API), [`scraper.py`](https://github.com/pxzya/v2scan/blob/main/scraper.py) (Channel scraper), [`gui/app.js`](https://github.com/pxzya/v2scan/blob/main/gui/app.js) (Scan interface), [`subscriptions.py`](https://github.com/pxzya/v2scan/blob/main/subscriptions.py) (Subscription fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_desktop["Webview host<br/>[main.py]"]
  node_ui["Scan interface<br/>[app.js]"]
end

subgraph group_workflow["Scan workflow"]
  node_api["Scan API<br/>[api.py]"]
  node_tester["TCP config tester<br/>[tester.py]"]
end

subgraph group_sources["Sources and parsing"]
  node_scraper["Channel scraper<br/>[scraper.py]"]
  node_subscription["Subscription fetcher<br/>[subscriptions.py]"]
  node_config_parser["Config parser<br/>[parser.py]"]
  node_proxy_parser["Telegram proxy parser<br/>[proxy_links.py]"]
end

subgraph group_support["State and enrichment"]
  node_geo["Country lookup<br/>[geo.py]"]
  node_channel_store[("Saved channels<br/>[channels_store.py]")]
end

node_user(("User"))
node_telegram["Telegram web preview"]
node_subscription_service["Subscription URL"]
node_proxy_service["Discovery proxy"]
node_target_servers["Config servers"]
node_geo_service["IP geolocation API"]

node_user -->|"configures and starts"| node_ui
node_desktop -->|"loads"| node_ui
node_ui -->|"invokes scan and channel actions"| node_api
node_api -->|"dispatches scan events"| node_ui
node_api -->|"manages saved channels"| node_channel_store
node_api -->|"scrapes channel"| node_scraper
node_api -->|"fetches subscription"| node_subscription
node_api -->|"parses discovery proxy"| node_proxy_parser
node_api -->|"tests configs"| node_tester
node_api -->|"looks up hosts"| node_geo
node_scraper -->|"fetches public pages"| node_telegram
node_scraper -->|"extracts configs"| node_config_parser
node_scraper -->|"extracts proxy links"| node_proxy_parser
node_subscription -->|"fetches content"| node_subscription_service
node_subscription -->|"extracts configs"| node_config_parser
node_subscription -->|"extracts proxy links"| node_proxy_parser
node_scraper -.->|"routes discovery requests"| node_proxy_service
node_tester -->|"opens TCP connections"| node_target_servers
node_geo -->|"submits host lookups"| node_geo_service
node_ui -->|"requests valid-config export"| node_api

click node_desktop "https://github.com/pxzya/v2scan/blob/main/main.py"
click node_ui "https://github.com/pxzya/v2scan/blob/main/gui/app.js"
click node_api "https://github.com/pxzya/v2scan/blob/main/api.py"
click node_scraper "https://github.com/pxzya/v2scan/blob/main/scraper.py"
click node_subscription "https://github.com/pxzya/v2scan/blob/main/subscriptions.py"
click node_config_parser "https://github.com/pxzya/v2scan/blob/main/parser.py"
click node_proxy_parser "https://github.com/pxzya/v2scan/blob/main/proxy_links.py"
click node_tester "https://github.com/pxzya/v2scan/blob/main/tester.py"
click node_geo "https://github.com/pxzya/v2scan/blob/main/geo.py"
click node_channel_store "https://github.com/pxzya/v2scan/blob/main/channels_store.py"

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_desktop,node_ui,node_user,node_telegram toneBlue
class node_api,node_tester toneAmber
class node_scraper,node_subscription,node_config_parser,node_proxy_parser,node_target_servers,node_geo_service toneMint
class node_geo,node_channel_store toneRose
class node_subscription_service,node_proxy_service toneIndigo
```

## Components

### Desktop interface

- [Webview host](https://github.com/pxzya/v2scan/blob/main/main.py): `main.py`
- [Scan interface](https://github.com/pxzya/v2scan/blob/main/gui/app.js): `gui/app.js`

### Scan workflow

- [Scan API](https://github.com/pxzya/v2scan/blob/main/api.py): `api.py`
- [TCP config tester](https://github.com/pxzya/v2scan/blob/main/tester.py): `tester.py`

### Sources and parsing

- [Channel scraper](https://github.com/pxzya/v2scan/blob/main/scraper.py): `scraper.py`
- [Subscription fetcher](https://github.com/pxzya/v2scan/blob/main/subscriptions.py): `subscriptions.py`
- [Config parser](https://github.com/pxzya/v2scan/blob/main/parser.py): `parser.py`
- [Telegram proxy parser](https://github.com/pxzya/v2scan/blob/main/proxy_links.py): `proxy_links.py`

### State and enrichment

- [Country lookup](https://github.com/pxzya/v2scan/blob/main/geo.py): `geo.py`
- [Saved channels](https://github.com/pxzya/v2scan/blob/main/channels_store.py): `channels_store.py`

### Other components

- **User**
- **Telegram web preview**
- **Subscription URL**
- **Discovery proxy**
- **Config servers**
- **IP geolocation API**

## Connections

- User → Scan interface: configures and starts
- Webview host → Scan interface: loads
- Scan interface → Scan API: invokes scan and channel actions
- Scan API → Scan interface: dispatches scan events
- Scan API → Saved channels: manages saved channels
- Scan API → Channel scraper: scrapes channel
- Scan API → Subscription fetcher: fetches subscription
- Scan API → Telegram proxy parser: parses discovery proxy
- Scan API → TCP config tester: tests configs
- Scan API → Country lookup: looks up hosts
- Channel scraper → Telegram web preview: fetches public pages
- Channel scraper → Config parser: extracts configs
- Channel scraper → Telegram proxy parser: extracts proxy links
- Subscription fetcher → Subscription URL: fetches content
- Subscription fetcher → Config parser: extracts configs
- Subscription fetcher → Telegram proxy parser: extracts proxy links
- Channel scraper → Discovery proxy: routes discovery requests
- TCP config tester → Config servers: opens TCP connections
- Country lookup → IP geolocation API: submits host lookups
- Scan interface → Scan API: requests valid-config export