EN Code Structure

中文 | English

Code Structure

Repository layout for contributors and downstream developers. For conventions see AGENTS.md in the repo root. FlowWeaver originates from SniShaper and shares some technical foundations (sing-tun data plane, uTLS/ECH handling), but the codebase evolves independently.

Tech Stack

Layer	Technology
Backend	Go 1.27+, Wails v3 bindings, module name flowweaver
Frontend	React 19 + TypeScript + MUI + Vite, @iconify/react icons (Material Symbols / MDI, bundled offline)
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

FlowWeaver/
├── 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_subscription.go #   Subscription APIs (import/switch/node selection) + node/service latency probes
│   ├── app_fragment.go     #   TLS fragmentation config API (get/set/reset)
│   ├── app_system.go       #   System proxy toggle (registry writes)
│   ├── autostart_*.go      #   Autostart (Windows: Task Scheduler)
│   ├── app_tray*.go        #   Tray: build, session watch, 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, subscription)
│   └── core_admin_*.go     #   Admin elevation
├── proxy/                  # Proxy server core logic
│   ├── proxy.go            #   HTTP + SOCKS5 mixed-port server
│   ├── mitm.go             #   MITM: local TLS termination, SNI-fake/ECH outbound replay
│   ├── dialer.go           #   Multi-protocol outbound dialer (ss/vmess/vless/trojan/tuic/hy2/wireguard/socks5/http)
│   ├── subscription_dialer.go  # Subscription-node dialing and UDP relay
│   ├── rules_merge.go      #   Merging subscription rules with built-in rules
│   ├── tun_flow.go         #   TUN traffic feeding into the proxy server
│   └── auto_routing.go     #   Auto-routing
├── pkg/                    # Standalone feature packages
│   ├── subscription/       #   Clash subscription parsing (nodes/groups/rules)
│   ├── singtun/            #   TUN NIC management (sing-tun integration, gVisor stack, UDP relay)
│   ├── netiface/           #   Physical NIC detection and outbound binding
│   ├── certmanager/        #   CA certificate generation and installation
│   ├── cfpool/             #   Cloudflare IP pool
│   ├── dohresolver/        #   DoH resolver (multi-node failover)
│   ├── rules/gfwlist.go    #   GFWList suffix matching (local cache only)
│   └── tlsfrag/            #   TLS-RF fragmentation implementation (records/segments/interval configurable)
├── 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, 11 pages
│                           #   Dashboard, Subscription, 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
├── config/settings.json    # App settings: ports, TUN (stack/adapter name), theme & appearance mode, TLS fragmentation, Cloudflare IPs, etc.
└── Platform.md / build.md  # Platform support and build matrix docs

Data Flow

Frontend (React HashRouter)
   │  Wails bindings: EventsOn subscriptions + async Go method calls
   ▼
App API (app/app_api.go)
   │
   ├──► pkg/subscription  Clash subscription parsing → nodes/groups/rules
   ├──► proxy/            Proxy server (mode dispatch, multi-protocol dialing, subscription UDP relay)
   ├──► 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.
• Subscription activation chain: sub use → subscription rules load through rules_merge.go and hide the built-in rules → node selections persist to the subscription store → subscription_dialer.go dials the selected node (TCP/UDP).
• TLS fragmentation settings fall back across three levels: per-rule frag > global fragment section in settings.json > tlsfrag.DefaultTLSRF* presets; NumRecords=1 with NumSegments>=2 means TCP-only fragmentation (bytes untouched, cut point moved before the SNI).
• WireGuard tunnels run on a userspace IP stack — no kernel NIC, no routing table changes; TUN UDP traffic goes through singtun's UDP relay via the currently selected subscription node.
• TUN data plane 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 (Linux/macOS: ./build.sh; 12-target matrix in build.md)
• 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.
• Any change that alters a file's purpose or adds new files must update this Wiki (zh + EN pages) in the same change.
• Changes to security-sensitive areas (certificates, TUN, system proxy, core RPC token) require maintainer review.