harbor-net/docs/goals/windows-modular-client/PLAN.md

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.