Clarify active Windows client architecture

2026-07-07 21:19:41 +03:00
parent a0f41baa36
commit 59f2264a2e
55 changed files with 19554 additions and 8 deletions
--- a/docs/goals/windows-modular-client/EVIDENCE.md
+++ b/docs/goals/windows-modular-client/EVIDENCE.md
--- a/docs/goals/windows-modular-client/GOAL.md
+++ b/docs/goals/windows-modular-client/GOAL.md
@@ -0,0 +1,16 @@
+# Goal: Windows Tauri Proxy Client
+
+Use Krypton Execution to execute `docs/goals/windows-modular-client/PLAN.md`.
+
+Core rules:
+- Treat `PLAN.md` as the source plan.
+- Preserve intent, ownership, contract, cutover, evidence, and kill criteria.
+- Build a separate Tauri 2 Windows desktop app under `apps/windows-client`.
+- Do not implement Windows by extending the current Node gateway/client server.
+- Keep Control App, Proxyfier Layer, and Local sing-box separately installable and operable.
+- Make external proxy target + ProxiFyre profile apply the MVP.
+- Keep Local sing-box optional; it must not be required for external target profiles.
+- Keep generated ProxiFyre and sing-box configs derived from source models.
+- Capture acceptance evidence from the target user's perspective and record it in `EVIDENCE.md`.
+- Say "implemented but unproven" if Windows-only privileged evidence cannot be captured.
+
--- a/docs/goals/windows-modular-client/PLAN.md
+++ b/docs/goals/windows-modular-client/PLAN.md
@@ -0,0 +1,506 @@
+# 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.
+
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -8,7 +8,7 @@
 | --- | --- | --- | --- |
 | `gateway` | LXC/VPS как gateway для роутера и всей сети | Docker `network_mode: host` + TProxy | делаем первым |
 | `desktop-proxy` | Mac/Linux локальный HTTP/SOCKS proxy с fallback | Docker bridged ports | позже переносим из старой реализации |
-| `windows-gaming` | Windows для игр/Discord/Vesktop | native `sing-box.exe` + ProxiFyre | позже приводим в порядок |
+| `windows-gaming` | Windows для игр/Discord/Vesktop | standalone Tauri 2 app + ProxiFyre adapter + optional native `sing-box.exe` | активное направление: `docs/goals/windows-modular-client/PLAN.md` |

 ## Gateway mode

@@ -84,15 +84,32 @@

 ## Windows gaming mode

-Цель: сохранить сценарий для Discord/Vesktop/игр.
+Цель: отдельное Windows desktop-приложение для Discord/Vesktop/игр, где Control App, Proxyfier Layer и Local sing-box являются независимыми компонентами.
+
+Current checkpoint:
+
+- MVP slice exists under `apps/windows-client`.
+- Frontend build passes with `npm run build`.
+- Rust/Tauri native verification requires installing Rust/rustup and Visual Studio Build Tools with MSVC/Windows SDK.
+- Local sing-box is optional; external SOCKS5 targets remain the first verified path.

 Требования:

- Native `sing-box.exe`.
- Scheduled task или Windows service.
- ProxiFyre + WinPacketFilter для приложений, которые не умеют proxy.
- Управление из PowerShell helper.
- Позже можно сделать Electron/Tauri UI поверх privileged helper.
+- Standalone Tauri 2 + React/TypeScript + Rust app under `apps/windows-client`.
+- Profiles for process/folder/exe app routing.
+- External SOCKS5/HTTP targets first; local `sing-box` is optional.
+- Proxyfier adapter boundary with ProxiFyre as the first engine.
+- Explicit installers for Control App, Proxyfier Layer, and Local sing-box.
+- Privileged helper/install operations return structured JSON.
+
+Source docs:
+
+- Product/tech brief: `docs/windows-client-product-tech-brief.md`.
+- Execution plan: `docs/goals/windows-modular-client/PLAN.md`.
+
+Superseded:
+
+- The old Node `APP_MODE=windows` plan in `docs/superpowers/plans/2026-05-21-windows-client.md` is historical context, not the active implementation path.

 ## Рабочий порядок

@@ -102,4 +119,4 @@
 4. Реализовать Vite + React UI для subscription -> server select -> apply.
 5. Добавить gateway docs/install script.
 6. Потом переносить desktop-proxy.
-7. Потом приводить Windows mode к новой архитектуре.
+7. Потом реализовать standalone Windows Tauri client по `docs/goals/windows-modular-client/PLAN.md`.
--- a/docs/superpowers/plans/2026-05-21-windows-client.md
+++ b/docs/superpowers/plans/2026-05-21-windows-client.md
@@ -1,5 +1,12 @@
 # Windows Client Implementation Plan

+> Superseded: do not execute this Node `APP_MODE=windows` plan as the current
+> Windows implementation path. The active plan is the standalone Tauri 2 desktop
+> app in `docs/goals/windows-modular-client/PLAN.md`, based on
+> `docs/windows-client-product-tech-brief.md`.
+> Content below is retained for historical context and may contradict the active
+> Tauri plan.
+
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

 **Goal:** Restore the Windows proxy workflow as a script-first product with two install modes: full local `sing-box` + ProxiFyre, or ProxiFyre-only routing to an existing proxy, controlled by a clean local web UI.
--- a/docs/superpowers/specs/2026-05-21-windows-client-design.md
+++ b/docs/superpowers/specs/2026-05-21-windows-client-design.md
@@ -1,5 +1,12 @@
 # Windows Client Design

+> Superseded: this document describes the earlier Node/web-control Windows direction.
+> The active Windows direction is a standalone Tauri 2 desktop app under
+> `apps/windows-client`, driven by `docs/windows-client-product-tech-brief.md`
+> and `docs/goals/windows-modular-client/PLAN.md`.
+> Content below is retained for historical context and may contradict the active
+> Tauri plan.
+
 ## Goal

 Restore the old Windows workflow in a cleaner product shape: a one-command PowerShell installer can install either a full local `sing-box` + ProxiFyre setup or ProxiFyre-only routing to an existing proxy, then expose a small local web UI for profiles, folders, executable files, status, and logs.
--- a/docs/windows-client-product-tech-brief.md
+++ b/docs/windows-client-product-tech-brief.md
@@ -0,0 +1,635 @@
+# Windows Proxy Client: Product And Technology Brief
+
+Дата: 2026-07-03
+
+Цель документа: описать, как должно выглядеть и работать Windows-приложение для управления proxy/VPN-маршрутизацией приложений, и какой стек лучше использовать для реализации.
+
+Этот документ можно отдать другой модели или команде как исходное ТЗ.
+
+## Коротко
+
+Нужно Windows-приложение, которое разделяет систему на три независимые части:
+
+1. **Control App**: маленькое desktop-приложение для настройки, статуса, профилей, логов и запуска операций.
+2. **Proxyfier Layer**: отдельный компонент, который заставляет выбранные Windows-приложения ходить через SOCKS5/HTTP proxy, даже если они сами не умеют proxy.
+3. **Local sing-box**: опциональный локальный VPN/proxy runtime. Его можно установить, не устанавливать, остановить, заменить внешним proxy target.
+
+Главный принцип: пользователь не обязан ставить все сразу. Если у него уже есть proxy, ему нужны только Control App + Proxyfier. Если нужен локальный VPN-клиент, он отдельно ставит `sing-box`.
+
+## Как это должно выглядеть
+
+Приложение должно выглядеть как компактная системная утилита, а не как сайт.
+
+Главный экран:
+
+- верхняя строка: общий статус маршрута;
+- три карточки компонентов: `Control App`, `Proxyfier`, `Local sing-box`;
+- список активных профилей;
+- кнопка `Apply changes`;
+- короткая лента последних событий.
+
+Пример главного статуса:
+
+```text
+Selected apps -> ProxiFyre -> Local sing-box 127.0.0.1:1080 -> VPN
+```
+
+или:
+
+```text
+Selected apps -> ProxiFyre -> Existing proxy 192.168.50.111:8080
+```
+
+Если `sing-box` не установлен, это не ошибка. Карточка должна показывать:
+
+```text
+Local sing-box
+Not installed
+Install if you want this PC to run its own local VPN proxy.
+```
+
+Если Proxyfier не установлен, профили можно редактировать, но apply должен быть заблокирован:
+
+```text
+Proxyfier is required to route selected apps.
+Install Proxyfier
+```
+
+## Основные экраны
+
+### 1. Overview
+
+Показывает:
+
+- текущий route line;
+- статус Control App;
+- статус Proxyfier;
+- статус Local sing-box;
+- активный proxy target;
+- сколько приложений сейчас включено в routing;
+- последние 5-10 событий.
+
+Действия:
+
+- restart Proxyfier;
+- restart local sing-box, если установлен;
+- open logs;
+- copy diagnostics.
+
+### 2. Profiles
+
+Профиль - главный объект настройки.
+
+Профиль содержит:
+
+- название;
+- enabled/disabled;
+- proxy target;
+- протоколы: TCP, UDP;
+- список приложений.
+
+Типы элементов:
+
+- `process`: имя процесса, например `Discord`, `Telegram`, `Code`;
+- `folder`: папка, приложение сканирует `.exe` внутри;
+- `exe`: конкретный путь к `.exe`.
+
+UI профиля:
+
+- слева список профилей;
+- справа детали выбранного профиля;
+- поле выбора target;
+- кнопки добавления: `Process`, `Folder`, `EXE`;
+- preview resolved apps;
+- `Save`;
+- `Apply changes`.
+
+Важно: пользователь должен видеть понятные исходные элементы, а не только сгенерированный конфиг Proxyfier.
+
+### 3. Targets
+
+Proxy target - это куда Proxyfier отправляет трафик выбранных приложений.
+
+Типы targets:
+
+- `Local sing-box`: `127.0.0.1:1080`, доступен только если local sing-box установлен и запущен;
+- `Existing SOCKS5 proxy`: например `127.0.0.1:8080` или `192.168.50.111:8080`;
+- `Existing HTTP proxy`, если выбранный proxyfier поддерживает HTTP.
+
+На экране targets:
+
+- список targets;
+- проверка соединения;
+- имя, host, port, protocol;
+- статус last checked;
+- кнопка set default.
+
+### 4. Components
+
+Отдельный экран или часть Overview.
+
+Компоненты:
+
+- Control App;
+- Proxyfier;
+- Local sing-box.
+
+Для каждого:
+
+- installed / not installed;
+- running / stopped;
+- version;
+- path;
+- service/task status;
+- actions.
+
+Actions должны быть явными:
+
+- `Install`;
+- `Repair`;
+- `Start`;
+- `Stop`;
+- `Restart`;
+- `Open folder`;
+- `View logs`.
+
+Нельзя делать скрытую установку `sing-box` при сохранении профиля.
+
+### 5. Logs / Diagnostics
+
+Должно быть две зоны:
+
+- activity: действия пользователя и результат apply;
+- runtime logs: proxyfier logs, sing-box logs, helper logs.
+
+Кнопка `Copy diagnostics` должна собирать:
+
+- версии компонентов;
+- paths;
+- running status;
+- активные profiles;
+- targets без секретов;
+- последние ошибки;
+- путь к сгенерированному proxyfier config.
+
+## Пользовательские сценарии
+
+### Сценарий A: у пользователя уже есть proxy
+
+1. Пользователь устанавливает Control App.
+2. Открывает приложение.
+3. Видит, что Proxyfier не установлен, а sing-box отсутствует.
+4. Нажимает `Install Proxyfier`.
+5. Добавляет target `192.168.50.111:8080`.
+6. Создает профиль `Discord`.
+7. Добавляет process `Discord`.
+8. Нажимает `Apply changes`.
+9. Приложение генерирует config для Proxyfier и перезапускает proxyfier service.
+
+Результат: Discord ходит через внешний proxy. Local sing-box не нужен.
+
+### Сценарий B: пользователь хочет локальный VPN proxy
+
+1. Пользователь устанавливает Control App.
+2. Устанавливает Proxyfier.
+3. Устанавливает Local sing-box.
+4. Вводит subscription/VLESS link.
+5. Выбирает сервер.
+6. Local sing-box поднимает SOCKS5/HTTP endpoint на `127.0.0.1:1080`.
+7. Профили используют target `Local sing-box`.
+
+Результат: выбранные приложения ходят через локальный sing-box.
+
+### Сценарий C: временно отключить VPN
+
+1. Пользователь открывает профиль.
+2. Меняет target с `Local sing-box` на внешний proxy или `Direct/Disabled`.
+3. Нажимает `Apply changes`.
+
+Результат: Proxyfier перегенерирован, local sing-box можно остановить отдельно.
+
+## Рекомендуемый стек
+
+### Desktop shell: Tauri 2
+
+Рекомендация: **Tauri 2 + React + TypeScript + Rust backend**.
+
+Почему:
+
+- Tauri ориентирован на маленькие desktop-приложения и использует системный web renderer, поэтому приложение легче Electron.
+- Можно писать UI на обычном web stack: React/TypeScript/Vite.
+- Backend-часть на Rust хорошо подходит для Windows APIs, файлов, процессов, sidecar binaries и безопасных команд.
+- Tauri поддерживает sidecar binaries, но требует явно выдать permissions на запуск sidecar, что полезно для security boundary.
+
+Frontend:
+
+- React;
+- TypeScript;
+- Vite;
+- TanStack Query для загрузки/кэша status/API;
+- Zustand или Jotai для локального UI state;
+- Zod для валидации JSON-моделей;
+- CSS modules или Tailwind. Для этой утилиты лучше сдержанный Windows-like UI, без тяжелой дизайн-системы.
+
+Backend внутри Tauri:
+
+- Rust commands для простых операций;
+- отдельный `core` crate с доменной логикой;
+- отдельный `windows-helper` binary для elevated/privileged действий.
+
+Не рекомендую начинать с Electron, если нет жесткой причины. Electron проще для web-команды, но тяжелее по размеру и памяти. Для маленькой системной утилиты Tauri подходит лучше.
+
+### Privileged helper
+
+Нужно отделить обычное приложение от операций администратора.
+
+Рекомендуемая модель:
+
+```text
+Tauri UI
+  -> Rust app backend
+    -> unprivileged status/read operations
+    -> explicit elevated helper for install/repair/service operations
+```
+
+Privileged helper может быть:
+
+- Rust CLI, который запускается elevated только для конкретной операции;
+- Rust Windows service/helper, если нужен постоянный privileged agent;
+- PowerShell scripts только как thin installer layer, не как основная бизнес-логика.
+
+Для MVP можно сделать проще:
+
+- installers запускаются отдельно от имени администратора;
+- Control App работает обычным пользователем;
+- service start/stop/restart идет через helper command;
+- helper возвращает JSON, UI не парсит текст PowerShell.
+
+Контракт helper:
+
+```json
+{
+  "action": "proxyfier.apply",
+  "payload": {
+    "configPath": "C:\\Tools\\ProxiFyre\\app-config.json",
+    "config": {}
+  }
+}
+```
+
+Ответ:
+
+```json
+{
+  "success": true,
+  "action": "proxyfier.apply",
+  "changed": true,
+  "message": "Proxyfier config applied and service restarted"
+}
+```
+
+Ошибки:
+
+```json
+{
+  "success": false,
+  "action": "proxyfier.apply",
+  "error": "Proxyfier service is not installed",
+  "details": {}
+}
+```
+
+### Service/runtime management
+
+Для `sing-box` как background runtime:
+
+- использовать `sing-box check` перед применением config;
+- хранить config отдельно;
+- запускать как Windows service или scheduled task;
+- для service wrapper можно использовать WinSW, если не хочется писать собственный Windows service wrapper.
+
+Практичный вариант:
+
+- v1: WinSW wraps `sing-box.exe`;
+- v2: собственный Rust service/helper, если понадобится полный контроль.
+
+Control App не должен напрямую владеть процессом `sing-box`. Он должен управлять service/task через helper.
+
+### Local sing-box
+
+`sing-box` - опциональный runtime.
+
+Его роль:
+
+- принять subscription/VLESS/sing-box config;
+- поднять локальный mixed SOCKS/HTTP inbound;
+- слушать только `127.0.0.1`, например `127.0.0.1:1080`;
+- маршрутизировать трафик через выбранный outbound.
+
+Config генерируется из source state приложения и проверяется:
+
+```powershell
+sing-box check -c C:\Tools\VpnProxy\sing-box\config.json
+```
+
+Local sing-box не должен быть обязательным. Если profile target указывает на внешний proxy, `sing-box` может отсутствовать.
+
+### Proxyfier layer
+
+Рекомендуемый стартовый backend: **ProxiFyre**.
+
+Почему:
+
+- open-source;
+- Windows-focused;
+- маршрутизирует TCP и UDP;
+- работает per-application;
+- использует `app-config.json`;
+- может работать как Windows Service.
+
+Важное ограничение: ProxiFyre лицензируется как AGPL-3.0. Если продукт должен быть закрытым коммерческим приложением, нужно заранее решить юридический вопрос или сделать adapter layer, чтобы можно было заменить engine на:
+
+- коммерческий Proxifier;
+- ProxyBridge;
+- собственный WinDivert/NDIS/WFP-based engine;
+- другой per-app proxy router.
+
+Интерфейс должен называться не `ProxiFyreConfig`, а шире:
+
+```text
+ProxyRouterAdapter
+```
+
+Первый adapter:
+
+```text
+ProxiFyreAdapter
+```
+
+Это позволит поменять engine без переделки UI и профилей.
+
+### Data storage
+
+Для MVP лучше использовать простые JSON-файлы с schema validation.
+
+Причина:
+
+- настройки легко читать и бэкапить;
+- можно быстро отлаживать;
+- config portable;
+- подходит для profile/target/source state.
+
+Рекомендуемые файлы:
+
+```text
+C:\ProgramData\VpnProxy\config\profiles.json
+C:\ProgramData\VpnProxy\config\targets.json
+C:\ProgramData\VpnProxy\config\components.json
+C:\ProgramData\VpnProxy\state\activity.json
+C:\ProgramData\VpnProxy\state\last-status.json
+C:\ProgramData\VpnProxy\generated\proxifyre-app-config.json
+C:\ProgramData\VpnProxy\generated\sing-box-config.json
+```
+
+Если нужна большая история событий, статистика трафика или сложные миграции, тогда добавить SQLite:
+
+- `rusqlite` или `sqlx` в Rust;
+- миграции;
+- таблицы `activity`, `component_status`, `traffic_events`.
+
+Но source of truth для профилей можно оставить JSON даже при наличии SQLite.
+
+### Installer strategy
+
+Нужны три явных installer entrypoints:
+
+```text
+Install Control App
+Install Proxyfier Layer
+Install Local sing-box
+```
+
+Они могут быть кнопками в UI, но каждая операция должна быть отдельной и понятной.
+
+CLI/script names:
+
+```text
+install-control-app.ps1
+install-proxyfier.ps1
+install-singbox.ps1
+```
+
+Или в packaged app:
+
+```text
+VpnProxySetup.exe /component control-app
+VpnProxySetup.exe /component proxyfier
+VpnProxySetup.exe /component sing-box
+```
+
+Каждый installer:
+
+- idempotent;
+- делает backup перед overwrite;
+- не удаляет чужие файлы без подтверждения;
+- проверяет admin rights;
+- пишет machine-readable install result;
+- не трогает остальные компоненты без явного выбора.
+
+### Security model
+
+Правила:
+
+- UI работает без admin rights.
+- Admin elevation только для install/repair/service/config apply, если это реально нужно.
+- Local API, если будет, слушает только `127.0.0.1`.
+- Лучше использовать Tauri commands / named pipe, чем открытый HTTP port.
+- Если нужен loopback HTTP, включить token или origin check.
+- Секреты subscription URLs не показывать в diagnostics.
+- Generated configs не редактируются вручную из UI.
+- Every apply creates backup.
+
+## Архитектура
+
+```text
+-------------------------------+
+| Tauri Control App              |
+| React/TypeScript UI            |
+---------------+---------------+
+                |
+                v
+-------------------------------+
+| Rust App Backend               |
+| profiles, targets, validation  |
+| component status aggregation   |
+-------+---------------+-------+
+        |               |
+        v               v
+---------------+   +-------------------+
+| Proxy Router  |   | Local sing-box     |
+| Adapter       |   | Adapter            |
+| ProxiFyre v1  |   | config + service   |
+-------+-------+   +---------+---------+
+        |                     |
+        v                     v
+---------------+   +-------------------+
+| ProxiFyre     |   | sing-box.exe       |
+| Windows svc   |   | Windows svc/task   |
+---------------+   +-------------------+
+```
+
+## Модель данных
+
+### Profile
+
+```json
+{
+  "id": "discord",
+  "name": "Discord",
+  "enabled": true,
+  "targetId": "local-singbox",
+  "protocols": ["TCP", "UDP"],
+  "items": [
+    { "type": "process", "value": "Discord" },
+    { "type": "folder", "value": "%LOCALAPPDATA%\\Discord", "recursive": true },
+    { "type": "exe", "value": "C:\\Games\\Game\\game.exe" }
+  ]
+}
+```
+
+### Target
+
+```json
+{
+  "id": "local-singbox",
+  "name": "Local sing-box",
+  "type": "local",
+  "protocol": "socks5",
+  "host": "127.0.0.1",
+  "port": 1080,
+  "requiresComponent": "singbox"
+}
+```
+
+External target:
+
+```json
+{
+  "id": "home-gateway",
+  "name": "Home gateway",
+  "type": "external",
+  "protocol": "socks5",
+  "host": "192.168.50.111",
+  "port": 8080
+}
+```
+
+### Component status
+
+```json
+{
+  "id": "proxyfier",
+  "name": "Proxyfier",
+  "installed": true,
+  "running": true,
+  "version": "2.3.0",
+  "path": "C:\\Tools\\ProxiFyre",
+  "serviceName": "ProxiFyreService",
+  "problems": [],
+  "actions": ["restart", "repair", "openLogs"]
+}
+```
+
+## Apply behavior
+
+Apply должен делать одно понятное действие:
+
+1. Прочитать profiles.
+2. Прочитать targets.
+3. Проверить, что выбранные targets доступны.
+4. Проверить, что Proxyfier установлен.
+5. Разрешить folder/exe в process names.
+6. Сгенерировать proxyfier config.
+7. Сделать backup старого config.
+8. Записать новый config.
+9. Перезапустить Proxyfier service.
+10. Записать activity entry.
+
+Если profile использует `local-singbox`, дополнительно:
+
+- проверить, что `sing-box` установлен;
+- проверить, что service running;
+- проверить, что `127.0.0.1:1080` отвечает.
+
+Если `local-singbox` не установлен, но profile target внешний, apply должен работать.
+
+## Что не делать
+
+- Не делать глобальную смену Windows proxy settings.
+- Не делать `sing-box` обязательным.
+- Не смешивать installer и profile apply.
+- Не хранить generated ProxiFyre config как source of truth.
+- Не привязывать UI напрямую к ProxiFyre, нужен adapter layer.
+- Не запускать privileged операции без явного согласия пользователя.
+- Не делать большой dashboard с лишней статистикой в первой версии.
+
+## MVP
+
+Самый правильный первый slice:
+
+1. Tauri app shell.
+2. Profiles UI.
+3. Targets UI.
+4. Component status UI.
+5. ProxiFyre adapter.
+6. External SOCKS5 target.
+7. Apply profile -> generate ProxiFyre config -> restart service.
+
+В MVP `sing-box` может быть только карточкой `Not installed / Install`.
+
+После этого добавить:
+
+1. Local sing-box installer.
+2. Subscription import.
+3. Server selection.
+4. Generate sing-box config.
+5. Start/stop/restart local sing-box service.
+
+## Acceptance criteria
+
+Приложение считается успешным, если:
+
+- можно установить только Control App;
+- можно установить Proxyfier отдельно;
+- можно не устанавливать sing-box;
+- можно добавить внешний SOCKS5 target;
+- можно создать профиль для Discord;
+- можно применить профиль;
+- generated ProxiFyre config не редактируется пользователем вручную;
+- UI показывает, что local sing-box отсутствует, но это не ломает внешний proxy flow;
+- после установки sing-box появляется target `Local sing-box`;
+- пользователь может переключить профиль с внешнего target на local sing-box.
+
+## Prompt For Another AI
+
+Build a Windows desktop proxy management app.
+
+Use Tauri 2 with React, TypeScript, Vite, and a Rust backend. The app must manage three independent components: the Control App, a proxyfier layer, and optional local sing-box. Do not make sing-box mandatory.
+
+The UI must be a compact Windows utility with these screens: Overview, Profiles, Targets, Components, Logs. Profiles contain process/folder/exe entries and choose a proxy target. Targets can be local sing-box or external SOCKS5/HTTP proxies. Proxyfier is the layer that routes selected apps through the chosen target.
+
+Start with ProxiFyre as the first proxy router adapter, but design an adapter boundary so it can later be replaced. Store source configuration as JSON with schema validation. Generated ProxiFyre and sing-box configs are derived artifacts, not source truth.
+
+Privileged operations must be isolated in an explicit helper/installer flow. The main UI should run without admin rights. Install Control App, Install Proxyfier, and Install Local sing-box must be separate operations. Applying a profile must not silently install missing components.
+
+MVP: external SOCKS5 target + ProxiFyre profile apply. Then add optional local sing-box installation, subscription import, server selection, and local sing-box service control.
+
+## References
+
+- Tauri 2: https://v2.tauri.app/
+- Tauri sidecar permissions: https://v2.tauri.app/develop/sidecar/
+- sing-box configuration: https://sing-box.sagernet.org/configuration/
+- ProxiFyre repository: https://github.com/wiresock/proxifyre
+- WinSW service wrapper: https://github.com/winsw/winsw
+- Microsoft Windows Service with Worker Service: https://learn.microsoft.com/en-us/dotnet/core/extensions/windows-service
+