# nirevil/vless architecture

> Architecture diagram of the GitHub repository nirevil/vless, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nirevil/vless
- Repository: https://github.com/nirevil/vless

## Overview

##### Main Components
- GitHub Actions Workflows – Located under the .github/workflows directory, these workflows trigger the dynamic update process every two hours and make sure that configuration files (in directories like “edge”, “sub”, “boringtun‐…”, etc.) are regenerated.
- Dynamic Configuration Generator – At the heart of the system are back‑end scripts such as backend.py and other utilities (for instance, the “real address generator” and the boringtun CLI tool written in Rust). These components process raw data (like Cloudflare IPs, DNS configuration, etc.) and produce updated subscription files.
- DNS over HTTPS Workers – The “DNS over HTTPS” directory contains worker scripts (e.g. _worker.js) that likely handle DNS queries or may serve as lightweight edge code to channel some of the subscription functionalities.
- Supporting Assets and Frontend Scripts – The “edge” directory (with assets such as JavaScript files, CSS, and images) serves as the presentation layer (for example, generating QR codes or showing usage instructions when a user visits the GitHub Pages or Cloudflare-hosted site).

##### Relationships/Interactions
- The configuration generator components take in “raw data” such as static IP files (for example, Cloudflare-IPs.json) and other source files, perform processing/transformation (for example, reordering, validating, or combining data for DNS over HTTPS) and output updated configuration files.
- These updated files are then “stored” back in various directories (like “sub”, “edge”, etc.). This storage represents the updated state of configuration assets that public clients will later poll or pull.

##### Architectural Patterns and Technologies
- Continuous integration/delivery (CI/CD) aspect through GitHub Actions which continuously regenerates parts of the repository.
- “dynamic/static separation” pattern: the backend and CLI tools continuously generate configuration data (the “dynamic” part), which then gets served as static files that clients can use.
- Mention the mix of technology stacks used—for example, Python for backend scripting (backend.py), Rust for WireGuard-related functionality (boringtun CLI), Node.js/JavaScript (frontend or worker scripts), and YAML/JSON for configuration formats.
- That due to the automated update system some directories and files (like workflows, borin-tun and edge files) are “volatile” and should not be manually modified.

## Diagram (Mermaid)

```mermaid
flowchart TD
    GA["GitHub Actions Workflows (CI/CD)"]:::ci
    click GA "https://github.com/nirevil/vless/tree/main/.github/workflows"

    subgraph "Dynamic Configuration Generator"
        DGen1["backend.py"]:::processing
        click DGen1 "https://github.com/nirevil/vless/blob/main/backend.py"
        DGen2["real address generator"]:::processing
        click DGen2 "https://github.com/nirevil/vless/tree/main/real address generator"
        DGen3["boringtun CLI tool"]:::processing
        click DGen3 "https://github.com/nirevil/vless/blob/main/boringtun-boringtun-cli-0.5.2"
    end

    GA --> DGen1
    GA --> DGen2
    GA --> DGen3

    subgraph "DNS over HTTPS Workers"
        DNS["DNS over HTTPS Worker"]:::dns
        click DNS "https://github.com/nirevil/vless/blob/main/DNS over HTTPS/Azadi-DNS/_worker.js"
    end

    GA --> DNS

    subgraph "Configuration Assets Repository"
        SUB["sub (Directory)"]:::storage
        click SUB "https://github.com/nirevil/vless/tree/main/sub"
        CF["Cloudflare-IPs.json"]:::storage
        click CF "https://github.com/nirevil/vless/blob/main/Cloudflare-IPs.json"
        SB["sing-box.json"]:::storage
        click SB "https://github.com/nirevil/vless/blob/main/sing-box.json"
        WARP["warp.json"]:::storage
        click WARP "https://github.com/nirevil/vless/blob/main/warp.json"
    end

    DGen1 --> SUB
    DGen2 --> CF
    DGen3 --> SB
    DGen1 --> WARP

    subgraph "Supporting Assets and Frontend Scripts"
        EDGE["edge (Directory)"]:::frontend
        click EDGE "https://github.com/nirevil/vless/tree/main/edge"
    end

    subgraph "Client Interfaces / Subscription Endpoints"
        CLIENT["Client Endpoints"]:::client
    end

    SUB --> CLIENT
    CF --> CLIENT
    SB --> CLIENT
    WARP --> CLIENT
    EDGE --> CLIENT
    DNS --> CLIENT

    classDef ci fill:#a2d2ff,stroke:#0a74da,stroke-width:2px;
    classDef processing fill:#bde0fe,stroke:#0077b6,stroke-width:2px;
    classDef dns fill:#caffbf,stroke:#40916c,stroke-width:2px;
    classDef storage fill:#ffec99,stroke:#ffb703,stroke-width:2px;
    classDef frontend fill:#f9c74f,stroke:#f9844a,stroke-width:2px;
    classDef client fill:#ffadad,stroke:#ff4d6d,stroke-width:2px;
```
