EN Code Structure

中文 | English

Code Structure

Repository layout for contributors and downstream developers. For conventions (naming, error handling, i18n rules) see AGENTS.md in the repo root and docs/CONTRIBUTING.md.

Tech Stack

Layer	Technology
Backend	Go 1.27+, Wails v3 bindings
Frontend	React 19 + TypeScript + MUI + Vite, @heroicons/react icons
Core	Mihomo-derived core process (built with the with_gvisor tag; TUN depends on gVisor)
Packaging	Windows MSIX (PFX-signed), 12-target cross-platform CLI matrix

Directory Layout

SniShaper/
├── main.go              # Entry point: Wails app assembly + tray setup
├── app/                 # Go backend application layer
│   ├── app_api.go       #   App struct and all frontend-bound APIs
│   ├── app_system.go    #   System proxy toggle (registry writes)
│   ├── autostart_*.go   #   Autostart (Windows: Task Scheduler; Linux/macOS: per-OS impls)
│   ├── app_tray*.go     #   Tray: build, session watch (unlock/Explorer-restart recovery), reshow
│   └── app_update*.go   #   Version check, download and self-update install
├── core/                # Core process management
│   ├── core_client.go   #   Core process launch, RPC client (token-authenticated)
│   ├── core_api.go      #   In-core RPC service (Ping/Shutdown require token match)
│   ├── core_runtime.go  #   Core runtime assembly (TUN, certificates, rules)
│   └── core_admin_*.go  #   Admin elevation
├── proxy/               # Proxy server core logic
│   ├── mitm.go          #   MITM: local TLS termination, SNI-fake/ECH outbound replay
│   ├── tun_flow.go      #   TUN traffic feeding into the proxy server
│   └── rules_*.go       #   Rule matching and auto-routing
├── pkg/                 # Standalone feature packages
│   ├── certmanager/     #   CA certificate generation and installation
│   ├── cfpool/          #   Cloudflare IP pool (speed test / health check / refresh)
│   ├── dohresolver/     #   DoH resolver (multi-node failover)
│   ├── rules/gfwlist.go #   GFWList suffix matching (local cache file only, no network updates)
│   ├── singtun/         #   TUN NIC management (sing-tun integration, gVisor stack)
│   └── tlsfrag/         #   TLS-RF fragmentation implementation
├── evolution/           # Rule evolution testing: tester, rule generator, result analysis
├── cli/                 # Headless CLI (build tag: headless)
│   ├── main.go          #   Entry + command dispatch
│   ├── catalog.go       #   Command catalog (single source of truth for help and TUI)
│   └── tui.go           #   Interactive panel
├── frontend/src/        # React SPA, 10 pages
│                        #   Dashboard, Proxies, Rules, Routing, DNS,
│                        #   Evolution, Logs, Settings, About, Welcome
├── common/              # Cross-platform helpers (open file/URL, paths, crash logs)
├── rules/config.json    # Site-group rules (~3800 lines): MITM/ECH/SNI-fake configs
├── config/settings.json # App settings: ports, TUN, theme, Cloudflare IPs, etc.
└── docs/                # build / Platform / contributing / collaborator agreement docs

Data Flow

Frontend (React HashRouter)
   │  Wails bindings: EventsOn subscriptions + async Go method calls
   ▼
App API (app/app_api.go)
   │
   ├──► proxy/  Proxy server (HTTP + SOCKS5 mixed port, mode dispatch, rule matching)
   ├──► core/   Core process (TUN, gVisor stack, auto-routing, DNS hijack)
   └──► pkg/    Certificates / DoH / CF IP pool / GFWList

• Frontend state sync: the backend emits app:state / app:state_changed events via emitFrontendState(); the frontend subscribes and refreshes.
• TUN data plane: TUN only sniffs domains for routing rebuild (reads the first packet for SNI when fake-ip reverse lookup fails) and never rewrites the ClientHello — the TLS transcript hash covers the entire handshake, and modifying bytes in transit causes bad record MAC errors. SNI masquerading happens only at the TLS endpoint (MITM outbound replay).
• Core RPC isolation: the core and its client authenticate with a one-shot token (Ping/Shutdown both verify it), so overlapping instances cannot kill a freshly started core.

Build and Test

• Full build: .\build_windows.ps1 -Build all -Silent (add -BuildMsix for an MSIX package)
• Backend / frontend only: -Build backend / -Build frontend
• Go build check: go build -tags with_gvisor ./...
• Frontend type check (authoritative): cd frontend && ./node_modules/.bin/tsc --noEmit
• Headless CLI: see the build section of the CLI Reference

Contributing Notes

• Commit messages in English, conventional-commit style (feat: / fix: / refactor: ...).
• New UI copy must be added to the zh / en / ru i18n JSON files in the same change, with matching placeholders.
• Changes to security-sensitive areas (certificates, TUN, system proxy, core RPC token) require maintainer review; collaborator terms are in docs/COLLABORATOR_AGREEMENT.md.