Overview

Relevant source files

• .github/workflows/build-all.yml
• .github/workflows/build-windows-desktop.yml
• .github/workflows/build-windows.yml
• .github/workflows/package-zip.yml
• .github/workflows/pub-key.yml
• .github/workflows/upload-sign.yml
• README.md
• v2rayN/Directory.Build.props
• v2rayN/Directory.Packages.props
• v2rayN/ServiceLib/Handler/AutoStartupHandler.cs
• v2rayN/ServiceLib/ServiceLib.csproj
• v2rayN/v2rayN.Desktop/v2rayN.Desktop.csproj
• v2rayN/v2rayN/v2rayN.csproj

This document provides a high-level technical overview of v2rayN, a cross-platform GUI client for proxy protocols including VMess, VLESS, Shadowsocks, Trojan, Hysteria2, TUIC, and WireGuard. It explains the application's architecture, core components, and how they interact.

Purpose and Scope

v2rayN serves as a management interface for external proxy core implementations such as Xray, sing-box, and mihomo. It handles configuration persistence, subscription updates, routing rules, DNS settings, network testing, and system-wide proxy integration.

The codebase consists of three primary .NET projects:

Project	UI Framework	Target Platform	Key Dependencies
v2rayN	WPF (.NET 10.0-windows)	Windows only	MaterialDesignThemes, H.NotifyIcon.Wpf, ReactiveUI.WPF
v2rayN.Desktop	Avalonia (.NET 10.0)	Windows, Linux, macOS	Semi.Avalonia, DialogHost.Avalonia, ReactiveUI.Avalonia
ServiceLib	Class Library (.NET 10.0)	All platforms	ReactiveUI, sqlite-net-e, CliWrap, WebDav.Client

Both UI projects reference ServiceLib and share the same ViewModels, business logic handlers, and data models, ensuring consistent behavior across platforms.

Sources: v2rayN/v2rayN/v2rayN.csproj1-41 v2rayN/v2rayN.Desktop/v2rayN.Desktop.csproj1-58 v2rayN/ServiceLib/ServiceLib.csproj1-96

High-Level Architecture

The application implements a four-layer MVVM architecture where dual UI implementations share a common business logic library (ServiceLib).

System Component Diagram

Sources: v2rayN/v2rayN/v2rayN.csproj37-39 v2rayN/v2rayN.Desktop/v2rayN.Desktop.csproj39-41 v2rayN/ServiceLib/ServiceLib.csproj7-23

Core Components

Dual UI Implementation

v2rayN supports both Windows-specific WPF and cross-platform Avalonia. They share identical ViewModels located in ServiceLib.

• WPF Implementation: Targeted at Windows users, utilizing MaterialDesignThemes for a native look and H.NotifyIcon.Wpf for system tray integration. v2rayN/v2rayN/v2rayN.csproj7-23
• Avalonia Implementation: Targeted at Windows, Linux, and macOS, utilizing Semi.Avalonia for UI styling and SkiaSharp for cross-platform rendering. v2rayN/v2rayN.Desktop/v2rayN.Desktop.csproj13-34

Shared Business Logic (ServiceLib)

ServiceLib acts as the engine of the application. It contains:

1. ViewModels: Shared UI state using ReactiveUI and source generators. v2rayN/ServiceLib/ServiceLib.csproj10-16
2. Config Management: ConfigHandler manages the main configuration and interaction with the SQLite database for profile storage via sqlite-net-e. v2rayN/ServiceLib/ServiceLib.csproj17-18
3. Core Management: Handles the lifecycle of proxy cores using CliWrap for process control. v2rayN/ServiceLib/ServiceLib.csproj23

Proxy Core Configuration Generation

One of the primary functions of ServiceLib is transforming user-defined profiles into complex JSON/YAML configurations required by proxy cores.

Configuration Data Flow Diagram

• V2Ray/Xray: The system builds a V2rayConfig object, handling outbounds, routing, and balancers.
• Sing-box: The system builds a SingboxConfig object, transforming profiles into Outbound4Sbox and Inbound4Sbox entities.

Sources: v2rayN/ServiceLib/ServiceLib.csproj26-57

Configuration Persistence

v2rayN uses a hybrid approach for data storage:

• JSON: Stores general application settings and UI preferences.
• SQLite: Stores large datasets including server profiles and traffic statistics via sqlite-net-e and Repobot.SQLite.Unofficial. v2rayN/ServiceLib/ServiceLib.csproj17-18

Sample Resources

The application includes numerous embedded templates in ServiceLib used to initialize default configurations and core settings.

Resource Name	Purpose
SingboxSampleClientConfig	Default sing-box client template
SampleTunInbound	Template for TUN mode inbounds
pac	Proxy Auto-Config script template
dns_singbox_normal	Default DNS settings for sing-box
clash_tun_yaml	Clash TUN mode configuration template
linux_autostart_config	Desktop entry template for Linux autostart

Sources: v2rayN/ServiceLib/ServiceLib.csproj29-57

External Integration

Proxy Cores

v2rayN supports multiple cores, identified by core types and handled by specific service implementations.

Sources: README.md1-12 v2rayN/ServiceLib/ServiceLib.csproj43-54

System Integration

• Autostart: Managed via AutoStartupHandler.cs, which implements platform-specific logic for Windows (Registry/TaskScheduler), Linux (.desktop files), and macOS (LaunchAgents). v2rayN/ServiceLib/Handler/AutoStartupHandler.cs9-40
• TUN Mode: Provides virtual network interface support (e.g., SampleTunInbound or tun_singbox_inbound) for system-wide proxying. v2rayN/ServiceLib/ServiceLib.csproj48-54
• Localization: Supports 8 languages via ResUI resource files, including English, Chinese (Simplified/Traditional), Farsi, French, Hungarian, Indonesian, and Russian. v2rayN/ServiceLib/ServiceLib.csproj60-95
• Cross-Platform Utilities: Includes shell scripts for Linux and macOS to handle proxy settings (proxy_set_linux_sh) and process management (kill_as_sudo_linux_sh). v2rayN/ServiceLib/ServiceLib.csproj37-42

Sources: v2rayN/ServiceLib/Handler/AutoStartupHandler.cs5-230 v2rayN/ServiceLib/ServiceLib.csproj37-42 v2rayN/ServiceLib/ServiceLib.csproj60-95