# xishang0128/sparkle architecture

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

- Interactive diagram: https://gitdiagram.com/xishang0128/sparkle
- Repository: https://github.com/xishang0128/sparkle

## Overview

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: [`src/main/index.ts`](https://github.com/xishang0128/sparkle/blob/master/src/main/index.ts) (Main entry), [`src/main/core/manager.ts`](https://github.com/xishang0128/sparkle/blob/master/src/main/core/manager.ts) (Core runtime), [`src/renderer/src/App.tsx`](https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/App.tsx) (Renderer app), [`src/main/resolve/menu.ts`](https://github.com/xishang0128/sparkle/blob/master/src/main/resolve/menu.ts) (Feature wiring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_main["Main process"]
  node_node_main_entry["Main entry<br/>electron bootstrap<br/>[index.ts]"]
  node_node_main_core["Core runtime<br/>mihomo control<br/>[manager.ts]"]
  node_node_main_config["Config domain<br/>app config<br/>[index.ts]"]
  node_node_main_sys["System layer<br/>os integration<br/>[interface.ts]"]
  node_node_main_service["Local service<br/>privileged api<br/>[manager.ts]"]
  node_node_main_resolve["Feature wiring<br/>ui orchestration<br/>[menu.ts]"]
  node_node_main_tray(("Tray system<br/>desktop surface<br/>[tray.ts]"))
  node_node_main_updater(("Auto updater<br/>delivery flow<br/>[autoUpdater.ts]"))
  node_node_main_proxy["Sysproxy<br/>system proxy<br/>[sysproxy.ts]"]
end

subgraph group_grp_renderer["Renderer UI"]
  node_node_renderer_app["Renderer app<br/>react shell<br/>[App.tsx]"]
  node_node_renderer_pages["Pages<br/>ui screens<br/>[profiles.tsx]"]
  node_node_renderer_hooks["Domain hooks<br/>state binding<br/>[use-app-config.tsx]"]
  node_node_renderer_sider["Side panels<br/>dashboard widgets<br/>[profile-card.tsx]"]
  node_node_renderer_floating(("Floating window<br/>secondary ui<br/>[FloatingApp.tsx]"))
  node_node_renderer_traymenu(("Tray menu UI<br/>secondary ui<br/>[TrayMenuApp.tsx]"))
end

subgraph group_grp_shared["Shared bridge"]
  node_node_preload["Preload bridge<br/>ipc bridge<br/>[index.ts]"]
  node_node_shared_types["Shared types<br/>ipc contracts<br/>[types.d.ts]"]
end

node_node_main_entry -->|"boots"| node_node_main_core
node_node_main_entry -->|"loads"| node_node_main_config
node_node_main_entry -->|"wires"| node_node_main_sys
node_node_main_entry -->|"starts"| node_node_main_service
node_node_main_entry -->|"registers"| node_node_main_resolve
node_node_main_resolve -->|"creates"| node_node_main_tray
node_node_main_resolve -->|"coordinates"| node_node_main_updater
node_node_main_resolve -->|"controls"| node_node_main_proxy
node_node_main_core -->|"consumes"| node_node_main_config
node_node_main_core -->|"exposes"| node_node_main_service
node_node_main_core -->|"invokes"| node_node_main_sys
node_node_main_core -->|"applies"| node_node_main_proxy
node_node_main_service -->|"serves"| node_node_preload
node_node_preload -->|"types"| node_node_shared_types
node_node_preload -->|"bridges"| node_node_renderer_app
node_node_renderer_app -->|"navigates"| node_node_renderer_pages
node_node_renderer_app -->|"binds"| node_node_renderer_hooks
node_node_renderer_pages -->|"shares"| node_node_renderer_sider
node_node_renderer_app -->|"spawns"| node_node_renderer_floating
node_node_renderer_app -->|"spawns"| node_node_renderer_traymenu
node_node_renderer_hooks -->|"calls"| node_node_preload
node_node_renderer_pages -->|"reads"| node_node_renderer_hooks
node_node_main_config -->|"syncs"| node_node_renderer_hooks

click node_node_main_entry "https://github.com/xishang0128/sparkle/blob/master/src/main/index.ts"
click node_node_main_core "https://github.com/xishang0128/sparkle/blob/master/src/main/core/manager.ts"
click node_node_main_config "https://github.com/xishang0128/sparkle/blob/master/src/main/config/index.ts"
click node_node_main_sys "https://github.com/xishang0128/sparkle/blob/master/src/main/sys/interface.ts"
click node_node_main_service "https://github.com/xishang0128/sparkle/blob/master/src/main/service/manager.ts"
click node_node_main_resolve "https://github.com/xishang0128/sparkle/blob/master/src/main/resolve/menu.ts"
click node_node_main_tray "https://github.com/xishang0128/sparkle/blob/master/src/main/resolve/tray.ts"
click node_node_main_updater "https://github.com/xishang0128/sparkle/blob/master/src/main/resolve/autoUpdater.ts"
click node_node_main_proxy "https://github.com/xishang0128/sparkle/blob/master/src/main/sys/sysproxy.ts"
click node_node_preload "https://github.com/xishang0128/sparkle/blob/master/src/preload/index.ts"
click node_node_shared_types "https://github.com/xishang0128/sparkle/blob/master/src/shared/types/types.d.ts"
click node_node_renderer_app "https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/App.tsx"
click node_node_renderer_pages "https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/pages/profiles.tsx"
click node_node_renderer_hooks "https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/hooks/use-app-config.tsx"
click node_node_renderer_sider "https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/components/sider/profile-card.tsx"
click node_node_renderer_floating "https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/FloatingApp.tsx"
click node_node_renderer_traymenu "https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/TrayMenuApp.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main_entry,node_node_main_core,node_node_main_config,node_node_main_sys,node_node_main_service,node_node_main_resolve,node_node_main_tray,node_node_main_updater,node_node_main_proxy toneBlue
class node_node_renderer_app,node_node_renderer_pages,node_node_renderer_hooks,node_node_renderer_sider,node_node_renderer_floating,node_node_renderer_traymenu toneAmber
class node_node_preload,node_node_shared_types toneMint
```

## Components

### Main process

Privileged Electron control plane and desktop integration.

- [Main entry](https://github.com/xishang0128/sparkle/blob/master/src/main/index.ts): electron bootstrap · Starts the app and wires main-process subsystems. · `src/main/index.ts`
- [Core runtime](https://github.com/xishang0128/sparkle/blob/master/src/main/core/manager.ts): mihomo control · Owns Mihomo process control, startup sequencing, API access, and profile/runtime coordination. · `src/main/core/manager.ts`
- [Config domain](https://github.com/xishang0128/sparkle/blob/master/src/main/config/index.ts): app config · Manages app, profile, override, and controlled Mihomo configuration state. · `src/main/config/index.ts`
- [System layer](https://github.com/xishang0128/sparkle/blob/master/src/main/sys/interface.ts): os integration · Handles auto-start, system proxy, SSID, and other host OS interactions. · `src/main/sys/interface.ts`
- [Local service](https://github.com/xishang0128/sparkle/blob/master/src/main/service/manager.ts): privileged api · Exposes local service APIs, auth storage, fallback handling, and lifecycle coordination. · `src/main/service/manager.ts`
- [Feature wiring](https://github.com/xishang0128/sparkle/blob/master/src/main/resolve/menu.ts): ui orchestration · Connects trays, shortcuts, updates, deep links, windows, backups, and secondary integrations. · `src/main/resolve/menu.ts`
- [Tray system](https://github.com/xishang0128/sparkle/blob/master/src/main/resolve/tray.ts): desktop surface · Builds and updates the tray menu and tray-driven interactions. · `src/main/resolve/tray.ts`
- [Auto updater](https://github.com/xishang0128/sparkle/blob/master/src/main/resolve/autoUpdater.ts): delivery flow · Coordinates update checks and application update delivery. · `src/main/resolve/autoUpdater.ts`
- [Sysproxy](https://github.com/xishang0128/sparkle/blob/master/src/main/sys/sysproxy.ts): system proxy · Controls host proxy state and related bypass/PAC behavior. · `src/main/sys/sysproxy.ts`

### Renderer UI

React front end and feature pages.

- [Renderer app](https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/App.tsx): react shell · Top-level React application shell and route wiring. · `src/renderer/src/App.tsx`
- [Pages](https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/pages/profiles.tsx): ui screens · 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](https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/hooks/use-app-config.tsx): state binding · Binds app, profile, override, controlled Mihomo, groups, and rule state into the UI. · `src/renderer/src/hooks/use-app-config.tsx`
- [Side panels](https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/components/sider/profile-card.tsx): dashboard widgets · Compact controls and status cards for proxy, profile, log, DNS, traffic, TUN, and sysproxy. · `src/renderer/src/components/sider/profile-card.tsx`
- [Floating window](https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/FloatingApp.tsx): secondary ui · Dedicated compact renderer entry point for a floating operational view. · `src/renderer/src/FloatingApp.tsx`
- [Tray menu UI](https://github.com/xishang0128/sparkle/blob/master/src/renderer/src/TrayMenuApp.tsx): secondary 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](https://github.com/xishang0128/sparkle/blob/master/src/preload/index.ts): ipc bridge · Typed security boundary between renderer and main-process capabilities. · `src/preload/index.ts`
- [Shared types](https://github.com/xishang0128/sparkle/blob/master/src/shared/types/types.d.ts): ipc contracts · Defines shared renderer-main type contracts and controller shapes. · `src/shared/types/types.d.ts`

## Connections

- 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.
