Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Zephyr is a secure and lightweight cross-platform GUI client for the Mihomo (Clash Meta) proxy core. It utilizes a multi-layered architecture built with Tauri v2, Rust, and native JavaScript to provide high-performance proxy management while maintaining a small resource footprint.
Sources: README_en.md:1-10, landing.html:362-370
Core System Layers
Zephyr operates on a four-layer architecture that separates the user interface, communication protocols, business logic, and the proxy core.
1. User Interface (Frontend)
The frontend uses native JavaScript, UnoCSS, and Style Dictionary. It avoids heavy frameworks like React or Vue to eliminate Virtual DOM overhead and reduce the supply chain attack surface.
Sources: landing.html:366-368, FEATURES.md:214-220
2. Tauri IPC
The Inter-Process Communication (IPC) layer manages communication between the frontend and the Rust backend. It handles over 160 commands across 21 functional modules using a capability-based permission model.
Sources: landing.html:373-376, FEATURES.md:253-255
3. Rust Backend
The backend handles system integration, file I/O, security boundaries, and core process management. It manages machine-bound encryption, SSRF protection, and network change coordination.
Sources: README_en.md:162-167, FEATURES.md:267-270
4. Mihomo Core
The bottom layer consists of the Mihomo proxy engine, which provides the actual network routing, TUN interface, and rule-based traffic processing.
Sources: landing.html:388-391, FEATURES.md:3-8
The diagram shows the data flow from the user interface down to the network level.
Sources: landing.html:362-392, FEATURES.md:253-270
Prism Engine Architecture
The Prism Engine is a specialized component within Zephyr that enhances Mihomo's capabilities through declarative rule patches and a JavaScript sandbox.
Components of Prism Engine
- Rule Library: Manages
.prism.yamlfiles with CRUD operations and file watching. - Smart Selector: Uses Exponential Moving Average (EMA) scoring based on latency and success rates to select nodes.
- Script Sandbox: Executes JavaScript within a QuickJS environment constrained by 9 resource limits (e.g., memory, recursion depth).
- Override System: Applies global or per-profile scope configuration overrides using DSL or JavaScript.
Sources: FEATURES.md:143-162, README_en.md:86-98
The diagram represents how the Prism Engine components interact to patch the proxy configuration.
Sources: FEATURES.md:143-165, README_en.md:86-98
Security Architecture
Zephyr implements a "Defense in Depth" strategy with 13 layers of protection to secure user data and network traffic.
| Layer | Implementation Detail | Source File |
|---|---|---|
| Encryption | AES-256-GCM + PBKDF2 with machine-bound fingerprint keys. | SECURITY.md:188-190 |
| SSRF Protection | DNS validation for subscription URLs and blocking private IP redirects. | FEATURES.md:173-176 |
| Sandbox | Script execution limited by time (100ms-300s) and memory (1MB-512MB). | FEATURES.md:151-158 |
| Input Safety | UTF-8 safe truncation and length limits on all IPC commands. | FEATURES.md:184-185 |
| Update Safety | Minisign Ed25519 signature verification + SHA256 integrity checks. | SECURITY.md:191-193 |
Sources: SECURITY.md:185-195, FEATURES.md:171-209
Functional Modules
The system is organized into specialized managers and controllers that handle specific aspects of the application lifecycle.
Connection and Network Management
- TUN Manager: Handles virtual network interface creation and privilege escalation (e.g., polkit, pkexec).
- Network Coordinator: Detects Wi-Fi or network transitions and applies correct Prism configurations using a 2s debounce state machine.
- SysProxy Manager: Controls native system proxy settings for Windows, macOS, and Linux (GNOME/KDE/XFCE).
Sources: FEATURES.md:65-71, FEATURES.md:84-89, FEATURES.md:301-308
Configuration and Subscription
- Subscription Scheduler: A background
tokioscheduler that updates subscriptions at configurable intervals. - Core Manager: Manages profile file I/O and core state transitions (start/stop/restart).
- Backup System: Transactional ZIP export/import using a 3-phase commit (verify, stage, atomic commit).
Sources: FEATURES.md:15-20, FEATURES.md:112-115, FEATURES.md:256-260
The sequence diagram illustrates the workflow for updating a proxy subscription.
Sources: FEATURES.md:15-30, FEATURES.md:171-175
Technical Specifications Summary
| Category | Technology / Metric |
|---|---|
| Backend Language | Rust 1.96.0+ |
| Frontend Language | Native JavaScript (ES6+) |
| Desktop Framework | Tauri v2 |
| Rule DSL | Prism DSL ($prepend, $append, $filter) |
| Installer Size | ~8MB (Lite Version) |
| Memory Usage | ~30MB Runtime |
Sources: README_en.md:162-175, CONTRIBUTING.md:118-125, landing.html:398-405
Conclusion
Zephyr's architecture prioritizes security and performance by utilizing Rust's memory safety and a "zero-framework" frontend approach. By isolating untrusted scripts in a sandbox and employing a multi-layered IPC system, the application maintains a robust boundary between user input and system resources.
Sources: SECURITY.md:185-195, landing.html:150-165