How xishang0128/sparkle works
1. Overall shape
Sparkle is an Electron desktop application built with React and TypeScript. The app is split into the standard three-process model: main process for system/core control, preload as the IPC bridge, and renderer for the UI.
2. Main process as the control plane
src/main is the architectural center. It owns application startup, lifecycle, window/tray creation, local service orchestration, and all privileged operations such as launching Mihomo, editing system proxy state, handling permissions, and managing auto-updates.
3. Mihomo core integration
The most important backend subsystem is src/main/core, which manages the Mihomo proxy engine. It includes process control, API access, startup sequencing, profile checks, runtime/service coordination, and profile updates. This is the boundary where Sparkle turns user configuration into a running proxy service.
4. Configuration domain
src/main/config contains the app’s configuration model and transformations for app settings, profile settings, overrides, and controlled Mihomo settings. This is the main persistence/configuration boundary feeding both the core runtime and the renderer UI.
5. System integration layer
src/main/sys handles OS-specific capabilities: automatic launch at login, system proxy toggling, SSID/system inspection, and other miscellaneous platform interactions. This layer is what makes the app behave like a desktop network utility rather than just a UI around Mihomo.
6. Feature resolvers / orchestration
src/main/resolve contains app-level feature wiring: tray menu, shortcuts, theme, server, deep links, updater, floating window, traffic monitor, backup, and Git/Gist-like integrations. These modules connect lower-level services to user-facing behaviors and secondary windows.
7. Local service and auth boundary
src/main/service appears to manage local service APIs, auth/key storage, fallback handling, and service lifecycle coordination. This is likely the internal API surface used by the renderer and preload to request privileged actions without direct main-process access.
8. Preload as the IPC boundary
src/preload exposes a typed bridge between renderer and main process. It is the security boundary that allows the UI to call into Electron/main capabilities without direct Node access in the renderer. Shared typings in src/shared/types define this contract.
9. Renderer as the product UI
src/renderer is a React app with multiple pages for profiles, proxies, rules, logs, DNS, connections, TUN, sysproxy, resources, Sub-Store, settings, and override management. The UI is organized around operational control of Mihomo and the local system rather than generic app navigation.
10. UI state is grouped by domain
The renderer uses hooks such as use-app-config, use-profile-config, use-override-config, use-controled-mihomo-config, and use-groups to bind domain state to pages and components. This suggests a domain-driven front end, where each major configuration area has its own state and editor surface.
11. Specialized renderer surfaces
In addition to the main window, there are dedicated renderer entry points for a floating window and a tray menu app. These support compact operational views separate from the main dashboard.
12. Cross-cutting infrastructure
Utilities in src/main/utils and src/renderer/src/utils handle logging, IPC helpers, YAML/template processing, notifications, icons, hashing, validation, and user-agent generation. These are supporting layers rather than core architecture, but they glue together config editing, status reporting, and platform behavior.
13. Packaging and platform delivery
The repo includes Electron build config, platform-specific installers, and AUR packaging scripts. That indicates the application is shipped as a native desktop product for Windows/macOS/Linux, with install-time integration such as desktop entries, service scripts, and platform entitlements.
14. Primary data flow
The key runtime flow is: user action in React UI → preload IPC bridge → main-process service/core/config modules → Mihomo API/process or system proxy actions → status/log/state returned back to the renderer. A second flow handles persistence and recovery through profiles, overrides, backup/restore, and updater paths.
15. Main architectural boundaries
The important boundaries to capture in a diagram are: renderer vs preload vs main, UI vs privileged OS actions, configuration management vs proxy runtime, and local app state vs external Mihomo/controller/backup services. Sparkle’s architecture is centered on controlling a proxy engine and the host OS from a rich Electron front end.
Main entry points: index.ts Main entry · manager.ts Core runtime · App.tsx Renderer app · menu.ts Feature wiring
Components 17
Main process
Privileged Electron control plane and desktop integration.
- Main entry · Starts the app and wires main-process subsystems.
src/main/index.ts - Core runtime · Owns Mihomo process control, startup sequencing, API access, and profile/runtime coordination.
src/main/core/manager.ts - Config domain · Manages app, profile, override, and controlled Mihomo configuration state.
src/main/config/index.ts - System layer · Handles auto-start, system proxy, SSID, and other host OS interactions.
src/main/sys/interface.ts - Local service · Exposes local service APIs, auth storage, fallback handling, and lifecycle coordination.
src/main/service/manager.ts - Feature wiring · Connects trays, shortcuts, updates, deep links, windows, backups, and secondary integrations.
src/main/resolve/menu.ts - Tray system · Builds and updates the tray menu and tray-driven interactions.
src/main/resolve/tray.ts - Auto updater · Coordinates update checks and application update delivery.
src/main/resolve/autoUpdater.ts - Sysproxy · Controls host proxy state and related bypass/PAC behavior.
src/main/sys/sysproxy.ts
Renderer UI
React front end and feature pages.
- Renderer app · Top-level React application shell and route wiring.
src/renderer/src/App.tsx - Pages · Main operational surfaces for profiles, proxies, rules, logs, DNS, connections, TUN, sysproxy, resources, Sub-Store, settings, and overrides.
src/renderer/src/pages/profiles.tsx - Domain hooks · Binds app, profile, override, controlled Mihomo, groups, and rule state into the UI.
src/renderer/src/hooks/use-app-config.tsx - Side panels · Compact controls and status cards for proxy, profile, log, DNS, traffic, TUN, and sysproxy.
src/renderer/src/components/sider/profile-card.tsx - Floating window · Dedicated compact renderer entry point for a floating operational view.
src/renderer/src/FloatingApp.tsx - Tray menu UI · Dedicated renderer entry point for the tray menu surface.
src/renderer/src/TrayMenuApp.tsx
Shared bridge
IPC contract and shared type definitions.
- Preload bridge · Typed security boundary between renderer and main-process capabilities.
src/preload/index.ts - Shared types · Defines shared renderer-main type contracts and controller shapes.
src/shared/types/types.d.ts
Connections 23
- Main entry → Core runtime: boots · Main startup initializes Mihomo control.
- Main entry → Config domain: loads · App startup reads configuration state.
- Main entry → System layer: wires · Main entry sets up platform integration.
- Main entry → Local service: starts · Bootstraps local service and auth surfaces.
- Main entry → Feature wiring: registers · Installs feature wiring and desktop behaviors.
- Feature wiring → Tray system: creates · Feature wiring owns tray behavior.
- Feature wiring → Auto updater: coordinates · Feature wiring integrates auto-update flow.
- Feature wiring → Sysproxy: controls · Feature wiring can toggle system proxy state.
- Core runtime → Config domain: consumes · Core runtime uses app and profile config.
- Core runtime → Local service: exposes · Core runtime is surfaced through local service APIs.
- Core runtime → System layer: invokes · Core runtime triggers OS-level actions when needed.
- Core runtime → Sysproxy: applies · Core startup and runtime can affect system proxy.
- Local service → Preload bridge: serves · Service surface is consumed through the preload bridge.
- Preload bridge → Shared types: types · Bridge contract is defined by shared types.
- Preload bridge → Renderer app: bridges · Preload exposes main-process capabilities to the UI.
- Renderer app → Pages: navigates · App shell hosts the operational pages.
- Renderer app → Domain hooks: binds · UI shell relies on domain hooks for state.
- Pages → Side panels: shares · Pages and side panels present the same control domain.
- Renderer app → Floating window: spawns · Separate entry point for compact floating UI.
- Renderer app → Tray menu UI: spawns · Separate entry point for tray menu UI.
- Domain hooks → Preload bridge: calls · Hooks request privileged actions through IPC.
- Pages → Domain hooks: reads · Pages consume domain-specific config and status.
- Config domain → Domain hooks: syncs · Configuration state flows back into the renderer.