# Windows Tauri Proxy Client Implementation Plan **Intent:** Build a separate Windows desktop proxy management app using Tauri 2, React, TypeScript, and Rust. The app manages three independent components: Control App, Proxyfier Layer, and optional Local sing-box. **Current Behavior:** The repo contains a gateway/client Node + React web application and planning documents for a Windows mode inside that app. A newer product/technology brief now targets a standalone Windows desktop utility instead of extending the existing web control panel. **Expected Outcome:** A compact Windows desktop utility lets the user configure app-level proxy routing through external SOCKS5/HTTP targets first, then optionally install and use local sing-box. The app remains useful when sing-box is absent. **Target-Perspective Output:** A Windows user opens the desktop app, sees Overview, Profiles, Targets, Components, and Logs, adds Discord or another process/folder/exe profile, selects an external proxy target, applies changes to the proxyfier layer, and sees component status plus recent activity. Later, installing Local sing-box adds a local target without changing the profile model. **Truth Owner:** Source configuration lives in the Tauri app's Rust domain model and JSON files under `C:\ProgramData\VpnProxy`. Generated ProxiFyre and sing-box configs are derived artifacts. Privileged install/service operations are owned by explicit helper/installer flows, not by React UI state. **Contract Boundary:** React UI calls typed Tauri commands. Tauri Rust backend validates and persists profiles/targets/components. Proxy routing is behind a `ProxyRouterAdapter` boundary, with ProxiFyre as the first adapter. Privileged operations go through explicit helper/install commands returning structured JSON. **Cutover:** Supersede the prior Node `APP_MODE=windows` implementation direction. Keep existing gateway/client code intact. New Windows work lives under a separate Tauri app slice. **Displaced Path:** The old plan to add Windows mode into `src/server`/`src/web` is demoted to historical context. Do not add a third app mode to the current Node server for this product. **Value Density:** The smallest high-value slice is the desktop app MVP with external SOCKS5 target + ProxiFyre profile apply. Local sing-box is optional and comes after the proxyfier MVP is proven. **Evidence Gate:** Evidence must include target-perspective app proof: built Tauri app or dev window screenshot/state, generated proxyfier config artifact, mocked or real helper response, and manual Windows checklist when privileged components are involved. **Acceptance Evidence:** Automated tests pass for Rust/TypeScript domain logic, app build succeeds, the MVP can create a profile and generate/apply ProxiFyre config against an external target, and Windows manual evidence proves independent component behavior. **Evidence Lane:** Record command output, app screenshots/state payloads, generated configs, and manual verification in `docs/goals/windows-modular-client/EVIDENCE.md`. **Kill Criteria:** No Windows implementation inside current Node gateway/client server; no mandatory sing-box dependency; no generated config as source truth; no hidden installation during profile apply; no direct UI parsing of raw PowerShell/stdout. **Architecture Slice:** New standalone Tauri app under `apps/windows-client`, plus docs updates that point from older Windows plans to this plan. **Plan Review Gate:** Requires PRE review before implementation execution. ## Source Brief Product and technology source brief: - `docs/windows-client-product-tech-brief.md` This plan turns that brief into an execution-ready implementation sequence. ## Outcome Contract Plan title: Windows Tauri Proxy Client Intent: Build a native-feeling Windows utility that manages app-level proxy routing while keeping Control App, Proxyfier Layer, and Local sing-box separately installable and operable. Current behavior: - Existing runtime code is a Node HTTP server and Vite/React web UI for gateway and Mac-style client modes. - Earlier Windows docs describe adding Windows mode to that existing app. - The selected direction is now Tauri 2 + React/TypeScript + Rust as a separate Windows desktop app. Expected outcome: - `apps/windows-client` contains a Tauri 2 app. - The app has Overview, Profiles, Targets, Components, and Logs surfaces. - Profiles store process/folder/exe source items. - Targets store external proxy endpoints and optional local sing-box. - ProxiFyre is the first proxy router adapter. - Local sing-box is optional and never required for external target profiles. Target-perspective output: - User can install/run only the Control App. - User can see Proxyfier and Local sing-box as separate components. - User can add an external SOCKS5 target. - User can add a Discord process profile. - User can apply the profile to generated ProxiFyre config. - User sees activity confirming whether apply succeeded or why it was blocked. Truth owner: - Rust core domain crate owns normalized models and validation. - JSON source files under `C:\ProgramData\VpnProxy\config` own persisted profiles/targets/component preferences. - `ProxyRouterAdapter` owns conversion from source models to proxy-router generated config. - `SingBoxAdapter` owns generated local sing-box config and service contract. - React UI owns only transient UI state. Contract boundary: - UI -> Tauri commands with typed request/response DTOs. - Tauri commands -> Rust core services. - Core services -> adapter traits. - Adapter traits -> helper/install/service commands when privileged operations are needed. - Helper/install commands return structured JSON, never unstructured text for app logic. Cutover: - Add superseded notes to old Windows Node-mode docs. - Keep `docs/windows-client-product-tech-brief.md` as product brief. - Make this `PLAN.md` the execution plan. - Do not implement Windows by adding `APP_MODE=windows` to the current Node server. Displaced path: - Displace old "Windows mode in current web app" implementation. - Displace "full install vs ProxiFyre-only" as dominant architecture; those become recipes composed from separate components. Value density: - MVP must prove app-level routing with external proxy target and ProxiFyre before local sing-box work expands scope. Evidence gate: - Tests and build are not enough. - Capture app-visible state and generated config. - Capture Windows manual evidence for service/helper actions when those tasks execute. Acceptance evidence: - `cargo test` or equivalent Rust tests for domain/adapters. - frontend typecheck/test/build for React. - Tauri dev/build command result. - Screenshot or state dump showing Windows app surfaces. - Generated ProxiFyre config from a sample profile. - Manual Windows checklist when privileged components are present. Non-goals: - No Electron. - No extension of the current Node gateway/client UI for Windows MVP. - No global Windows system proxy changes. - No transparent routing without a proxy router. - No mandatory local sing-box. - No direct coupling of UI to ProxiFyre-specific config shape. Risk if wrong: - If built inside the current Node app, the product will inherit gateway/client assumptions and conflict with the selected Tauri direction. - If ProxiFyre is not behind an adapter, licensing or engine changes will force UI/data rewrites. - If privileged work is hidden behind apply, users lose control and failures become hard to diagnose. ## Architecture Slice Files/directories to create: - `apps/windows-client/package.json` - `apps/windows-client/vite.config.ts` - `apps/windows-client/tsconfig.json` - `apps/windows-client/src/main.tsx` - `apps/windows-client/src/app/App.tsx` - `apps/windows-client/src/app/routes.tsx` - `apps/windows-client/src/api/tauriCommands.ts` - `apps/windows-client/src/domain/types.ts` - `apps/windows-client/src/features/overview/*` - `apps/windows-client/src/features/profiles/*` - `apps/windows-client/src/features/targets/*` - `apps/windows-client/src/features/components/*` - `apps/windows-client/src/features/logs/*` - `apps/windows-client/src/styles/*` - `apps/windows-client/src-tauri/Cargo.toml` - `apps/windows-client/src-tauri/tauri.conf.json` - `apps/windows-client/src-tauri/capabilities/default.json` - `apps/windows-client/src-tauri/src/main.rs` - `apps/windows-client/src-tauri/src/commands.rs` - `apps/windows-client/src-tauri/src/models.rs` - `apps/windows-client/src-tauri/src/storage.rs` - `apps/windows-client/src-tauri/src/activity.rs` - `apps/windows-client/src-tauri/src/adapters/proxy_router.rs` - `apps/windows-client/src-tauri/src/adapters/proxifyre.rs` - `apps/windows-client/src-tauri/src/adapters/singbox.rs` - `apps/windows-client/src-tauri/src/helper.rs` - `apps/windows-client/src-tauri/tests/*` - `apps/windows-client/scripts/install-control-app.ps1` - `apps/windows-client/scripts/install-proxyfier.ps1` - `apps/windows-client/scripts/install-singbox.ps1` Files to modify: - `README.md` - `docs/roadmap.md` - `docs/superpowers/specs/2026-05-21-windows-client-design.md` - `docs/superpowers/plans/2026-05-21-windows-client.md` - `docs/goals/windows-modular-client/GOAL.md` - `docs/goals/windows-modular-client/EVIDENCE.md` Files to avoid: - `src/server/*` except if a later explicit migration asks for shared code extraction. - `src/web/*` for Windows MVP. - Docker, entrypoint, and compose files. - macOS installer. Source of truth: - `C:\ProgramData\VpnProxy\config\profiles.json` - `C:\ProgramData\VpnProxy\config\targets.json` - `C:\ProgramData\VpnProxy\config\components.json` - `C:\ProgramData\VpnProxy\state\activity.json` Derived artifacts: - `C:\ProgramData\VpnProxy\generated\proxifyre-app-config.json` - `C:\ProgramData\VpnProxy\generated\sing-box-config.json` - ProxiFyre runtime config copied/backed up by helper/apply operation. Read path: - React UI calls Tauri commands. - Tauri commands read JSON source via Rust storage service. - Component status combines source preferences, filesystem checks, service checks, and helper responses. Write path: - React UI sends typed mutations. - Rust validates with domain models. - Rust writes source JSON atomically with backups. - Apply generates derived config and invokes adapter/helper. Integration points: - ProxiFyre adapter emits `app-config.json` compatible output. - Local sing-box adapter emits `sing-box` JSON config and validates via `sing-box check` when binary exists. - Tauri sidecar/helper permissions are declared explicitly. - Installer scripts may be launched or displayed explicitly, never silently during apply. Migration/cutover: - Older Windows docs point to this plan and source brief. - Existing Node app remains gateway/client only. - If shared subscription parsing is needed later, extract it intentionally into a shared package rather than importing server internals. Acceptance evidence gate: - MVP evidence must show external-target flow works without local sing-box. - Optional sing-box evidence must show the same profile model can switch targets after installing sing-box. ## Task Board ### Task 1: Supersede Old Windows Node Plan Owner: main agent Input: - `docs/windows-client-product-tech-brief.md` - old Windows docs/plans Files allowed: - `docs/superpowers/specs/2026-05-21-windows-client-design.md` - `docs/superpowers/plans/2026-05-21-windows-client.md` - `docs/roadmap.md` - `README.md` Files forbidden: - Runtime source files. Output: - Old Windows documents clearly point to this Tauri plan and no longer read as implementation authority. Evidence: - `rg -n "Tauri|superseded|windows-client-product-tech-brief|apps/windows-client" README.md docs` Depends on: none Parallel safe: yes ### Task 2: Scaffold Tauri App Shell Owner: main agent Input: - Tauri 2 app structure - Product brief UI surfaces Files allowed: - `apps/windows-client/package.json` - `apps/windows-client/vite.config.ts` - `apps/windows-client/tsconfig.json` - `apps/windows-client/index.html` - `apps/windows-client/src/*` - `apps/windows-client/src-tauri/*` Files forbidden: - Current root `src/server/*` - Current root `src/web/*` Output: - Tauri app starts with empty shell and five navigation surfaces. - No business logic yet. Evidence: - `cd apps/windows-client && npm install && npm run build` - `cd apps/windows-client/src-tauri && cargo test` if Rust tests exist Depends on: Task 1 Parallel safe: no ### Task 3: Define Domain Models And Validation Owner: main agent Input: - Profile/Target/Component models from brief Files allowed: - `apps/windows-client/src-tauri/src/models.rs` - `apps/windows-client/src-tauri/src/validation.rs` - `apps/windows-client/src/domain/types.ts` - `apps/windows-client/src-tauri/tests/domain_tests.rs` Files forbidden: - Adapter/helper code except trait references. Output: - Typed Rust models for `Profile`, `ProfileItem`, `Target`, `ComponentStatus`, `ActivityEntry`. - TypeScript DTOs mirror Rust command responses. - Validation rejects malformed ports/protocols but allows missing local sing-box. Evidence: - Rust tests showing process/folder/exe normalization and external target validation. Depends on: Task 2 Parallel safe: no ### Task 4: Implement JSON Storage And Activity Log Owner: main agent Input: - Domain models from Task 3 Files allowed: - `apps/windows-client/src-tauri/src/storage.rs` - `apps/windows-client/src-tauri/src/activity.rs` - `apps/windows-client/src-tauri/tests/storage_tests.rs` Files forbidden: - UI screens except command wiring stubs. Output: - Atomic JSON read/write for profiles, targets, components, and activity. - Backups before overwriting source files. - Config root defaults to `C:\ProgramData\VpnProxy`, with test override. Evidence: - Tests prove roundtrip, invalid JSON fallback behavior, backup creation, activity cap/sort. Depends on: Task 3 Parallel safe: no ### Task 5: Add Proxy Router Adapter Boundary And ProxiFyre Adapter Owner: main agent Input: - Domain models and storage Files allowed: - `apps/windows-client/src-tauri/src/adapters/proxy_router.rs` - `apps/windows-client/src-tauri/src/adapters/proxifyre.rs` - `apps/windows-client/src-tauri/tests/proxifyre_adapter_tests.rs` Files forbidden: - Direct UI coupling to ProxiFyre config fields. Output: - `ProxyRouterAdapter` trait. - `ProxiFyreAdapter` generates config from enabled profiles and targets. - External target flow does not require sing-box. Evidence: - Test generates ProxiFyre config for Discord + external SOCKS5 target. - Test blocks local-singbox target only when target requires missing component. Depends on: Task 4 Parallel safe: no ### Task 6: Add Tauri Commands Owner: main agent Input: - Storage and adapter services Files allowed: - `apps/windows-client/src-tauri/src/commands.rs` - `apps/windows-client/src-tauri/src/main.rs` - `apps/windows-client/src/api/tauriCommands.ts` - `apps/windows-client/src-tauri/tests/command_tests.rs` Files forbidden: - Full UI implementation beyond command call wrappers. Output: - Commands for status, profiles, targets, components, scan/resolve preview, apply, logs. - Commands return structured responses only. Evidence: - Command tests or integration tests prove apply generates derived config and records activity using a mock adapter/helper. Depends on: Task 5 Parallel safe: no ### Task 7: Build MVP UI Owner: main agent Input: - Tauri command API - Product brief layout Files allowed: - `apps/windows-client/src/app/*` - `apps/windows-client/src/features/overview/*` - `apps/windows-client/src/features/profiles/*` - `apps/windows-client/src/features/targets/*` - `apps/windows-client/src/features/components/*` - `apps/windows-client/src/features/logs/*` - `apps/windows-client/src/styles/*` Files forbidden: - Rust adapter behavior except fixing DTO mismatches. Output: - Compact utility UI with Overview, Profiles, Targets, Components, Logs. - User can create/edit profile, external target, and trigger apply. - Missing sing-box is shown as valid optional state. Evidence: - `npm run build` - Screenshot or browser/app state showing missing sing-box and usable external target flow. Depends on: Task 6 Parallel safe: no ### Task 8: Implement Helper And Explicit Installer Boundary Owner: main agent Input: - Component model - Security model from brief Files allowed: - `apps/windows-client/src-tauri/src/helper.rs` - `apps/windows-client/src-tauri/capabilities/default.json` - `apps/windows-client/scripts/install-control-app.ps1` - `apps/windows-client/scripts/install-proxyfier.ps1` - `apps/windows-client/scripts/install-singbox.ps1` - `apps/windows-client/src-tauri/tests/helper_tests.rs` Files forbidden: - Hidden installer invocation inside profile apply. Output: - Helper command abstraction for status/service/apply. - Installer scripts are explicit and idempotent. - Tauri sidecar/shell permissions are narrow and documented. Evidence: - Helper tests with mock command runner. - PowerShell parser checks for installer scripts. - Capability file shows limited sidecar permissions. Depends on: Task 6 Parallel safe: partly, after command DTOs are stable ### Task 9: Add Optional Local Sing-Box Adapter Owner: main agent Input: - sing-box target model - service/helper boundary Files allowed: - `apps/windows-client/src-tauri/src/adapters/singbox.rs` - `apps/windows-client/src-tauri/tests/singbox_adapter_tests.rs` - `apps/windows-client/src/features/components/*` - `apps/windows-client/src/features/targets/*` Files forbidden: - Making sing-box mandatory for external targets. Output: - Generate local sing-box config. - Validate via `sing-box check` when binary exists. - Local target appears only when installed/configured or as an explicit install prompt. Evidence: - Tests show external target apply works without sing-box. - Tests show local-singbox target requires installed/running component. Depends on: Tasks 5 and 8 Parallel safe: no ### Task 10: Package, Verify, And Record Evidence Owner: main agent Input: - Completed MVP implementation Files allowed: - `apps/windows-client/*` - `README.md` - `docs/roadmap.md` - `docs/goals/windows-modular-client/EVIDENCE.md` Files forbidden: - Unrelated app code. Output: - Build/test commands documented. - README explains separate Control App, Proxyfier, and Local sing-box install flows. - Evidence file captures automated and target-perspective proof. Evidence: - `npm run build` - Rust tests - Tauri build/dev proof - generated ProxiFyre config summary - UI screenshot/state - Windows manual checklist, or clearly mark `implemented but unproven` for Windows-only service behavior if not run on a Windows host. Depends on: all previous tasks Parallel safe: no ## Manual Windows Verification Checklist 1. Install/run only Control App. 2. Verify Proxyfier and Local sing-box show missing as separate components. 3. Add external SOCKS5 target. 4. Add Discord process profile. 5. Apply profile; verify generated ProxiFyre config and activity entry. 6. Install Proxyfier separately; verify status changes. 7. Apply profile to real Proxyfier service. 8. Install Local sing-box separately. 9. Import subscription or config, select outbound, and start Local sing-box. 10. Switch existing profile from external target to Local sing-box and apply. 11. Stop/restart Proxyfier and Local sing-box separately. 12. Copy diagnostics and verify secrets are redacted.