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

