Introducing a new way to review your PRs.

Read the announcement

2dust / v2rayn

A GUI client for Windows, Linux and macOS, support Xray and sing-box and others

View on GitHub

13 documents · Updated Nov 16, 2026

overview

Knowledge Base updated: 2026-11-16

Knowledge Base Index

Orientation

This repository is v2rayN, a .NET proxy client suite built around a shared ServiceLib core. The highest-level flow is: UI or WebAPI input updates shared configuration/profile state, generates a proxy-core config, launches or restarts a proxy core, and reports status/statistics back to the caller.

Main parts:

  • v2rayN/ServiceLib/ — shared domain logic, persistence, profile parsing, config generation, core runtime control, network/update flows, and UI-agnostic MVVM view models.
  • v2rayN/v2rayN/ — Windows WPF desktop shell.
  • v2rayN/v2rayN.Desktop/ — cross-platform Avalonia desktop shell.
  • v2rayN/v2rayN.WebAPI/ — headless ASP.NET WebAPI runtime with auth, setup, update, backup, and launcher support.
  • v2rayN/ServiceLib.Tests/, v2rayN/v2rayN.WebAPI/Tests/, v2rayN/ServiceLib.UdpTest/, v2rayN/AmazTool/ — test suites and supporting tools.

Critical state lives in ServiceLib configuration/database entities under ServiceLib/Handler/Data/** and ServiceLib/Models/Entities/**; WebAPI auth/session/setup state is owned by v2rayN.WebAPI/Security/**; runtime process and update state is coordinated in ServiceLib managers/services and WebAPI runtime services.

Architecture diagrams

flowchart TD
  subgraph UI[Desktop UI shells]
    WPF[v2rayN WPF]
    Avalonia[v2rayN.Desktop Avalonia]
  end

  subgraph Shared[ServiceLib]
    VM[ViewModels]
    Data[Config persistence]
    Fmt[Profiles and subscriptions]
    Config[Core config generation]
    Runtime[Core runtime/processes]
    Net[Download/update/speedtest]
  end

  subgraph Headless[v2rayN.WebAPI]
    API[Api endpoints]
    WebRuntime[Runtime services]
    Security[Security and sessions]
    Launcher[Launcher/deployment]
  end

  subgraph Tools[Build, tests, tools]
    Tests[Test projects]
    Amaz[AmazTool]
    Packaging[Packaging scripts]
  end

  WPF --> VM
  Avalonia --> VM
  VM --> Data
  VM --> Fmt
  VM --> Config
  VM --> Runtime
  VM --> Net
  API --> WebRuntime
  API --> Security
  WebRuntime --> Data
  WebRuntime --> Config
  WebRuntime --> Runtime
  WebRuntime --> Net
  Launcher --> API
  Tests --> Shared
  Tests --> Headless
  Amaz --> Packaging
flowchart LR
  Input[UI or WebAPI request] --> Profiles[Profile/subscription handling]
  Profiles --> Persist[ConfigDbHandler / persisted entities]
  Persist --> Build[CoreConfigHandler and core config services]
  Build --> Launch[CoreManager / ProcessService]
  Launch --> ProxyCore[Proxy core process]
  ProxyCore --> Stats[Statistics services]
  Stats --> Caller[UI status or WebAPI response/events]
sequenceDiagram
  participant Client as Browser/API client
  participant Endpoints as v2rayN.WebAPI Api
  participant Auth as Security services
  participant Runtime as V2rayRuntime services
  participant ServiceLib as ServiceLib
  participant Core as Proxy core process

  Client->>Endpoints: authenticated runtime request
  Endpoints->>Auth: validate session/setup policy
  Auth-->>Endpoints: allowed
  Endpoints->>Runtime: apply profile/settings/update action
  Runtime->>ServiceLib: mutate config or generate runtime config
  ServiceLib->>Core: start/restart/stop process
  Core-->>ServiceLib: status/statistics
  Runtime-->>Endpoints: result/snapshot/events
  Endpoints-->>Client: API response or stream
flowchart TD
  Release[Release/package metadata] --> UpdateService[ServiceLib UpdateService]
  UpdateService --> Download[DownloadService / DownloaderHelper]
  Download --> Stage[WebAPI or desktop staging policy]
  Stage --> Preflight[Preflight and mutation gates]
  Preflight --> Apply[Apply core/web/geofile update]
  Apply --> Restart[Runtime restart or launcher workflow]

Glossary

  • ServiceLib — shared library containing the core application model, persistence, runtime orchestration, and UI-independent view models.
  • ProfileItem — persisted proxy/server profile entity used as input to share-link handling and core config generation.
  • CoreConfig — generated v2ray/Xray, sing-box, or Clash runtime configuration emitted from app profiles/settings.
  • V2rayRuntime — WebAPI-side runtime facade coordinating headless core lifecycle, settings/profile mutations, updates, and backups.
  • AmazTool — repository tool project used by build/release workflows outside the main apps.

Codebase-wide invariants

  • Shared business logic is centralized under v2rayN/ServiceLib/**, while product surfaces live in separate host projects: v2rayN/v2rayN/**, v2rayN/v2rayN.Desktop/**, and v2rayN/v2rayN.WebAPI/**.
  • Desktop UI shells mirror many shared workflows with platform-specific views: WPF uses v2rayN/v2rayN/Views/*.xaml*, while Avalonia uses v2rayN/v2rayN.Desktop/Views/*.axaml*.
  • WebAPI runtime concerns are separated by directory: routes in v2rayN/v2rayN.WebAPI/Api/**, DTO/contracts in Contracts/**, orchestration in Services/**, auth/policy middleware in Security/**, and native process workflows in Launcher/**.
  • Core-family config generation is split by target runtime under v2rayN/ServiceLib/Services/CoreConfig/V2ray/**, v2rayN/ServiceLib/Services/CoreConfig/Singbox/**, and v2rayN/…/CoreConfigClashService.cs.
  • Tests are colocated by product area rather than embedded in production projects: v2rayN/ServiceLib.Tests/**, v2rayN/v2rayN.WebAPI/Tests/**, and v2rayN/ServiceLib.UdpTest/**.

Routing table