Clarify active Windows client architecture

apps/windows-client/README.md

@@ -0,0 +1,116 @@
+# VPN Proxy Windows Client
+
+Standalone Windows desktop utility for app-level proxy routing. This app is
+separate from the current Docker gateway/client runtime and must not be wired
+through `APP_MODE=windows`.
+
+## Components
+
+- Control App: Tauri 2 + React/TypeScript UI and Rust command layer.
+- Proxyfier Layer: ProxiFyre adapter for per-application routing.
+- Local sing-box: optional local runtime, used only by targets that explicitly
+  require `singbox`.
+
+External SOCKS5 targets are the MVP path and do not require Local sing-box.
+
+## Source And Generated Files
+
+Source configuration is owned by Rust domain models and JSON files under:
+
+```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
+```
+
+Generated artifacts are derived and can be recreated:
+
+```text
+C:\ProgramData\VpnProxy\generated\proxifyre-app-config.json
+C:\ProgramData\VpnProxy\generated\sing-box-config.json
+```
+
+## Development
+
+```powershell
+cd apps/windows-client
+npm install
+npm run build
+```
+
+Run the browser preview shell:
+
+```powershell
+npm run dev -- --host 127.0.0.1
+```
+
+Run Tauri checks when the native Windows toolchain is installed:
+
+```powershell
+npm run tauri -- info
+npm run tauri -- dev
+npm run tauri -- build
+```
+
+Run Rust tests when Rust/Cargo are installed:
+
+```powershell
+cd apps/windows-client/src-tauri
+cargo test
+```
+
+Native Tauri build requires WebView2, Rust via rustup, and Visual Studio Build
+Tools with MSVC and Windows SDK components.
+
+## Explicit Installer Boundaries
+
+Installer scripts are explicit per component and return structured JSON in
+`-PlanOnly` mode:
+
+```powershell
+& .\scripts\install-control-app.ps1 -PlanOnly
+& .\scripts\install-proxyfier.ps1 -PlanOnly
+& .\scripts\install-singbox.ps1 -PlanOnly
+```
+
+Installers must be launched intentionally by the user or by a future narrow
+helper permission. Profile apply must not silently install Control App,
+Proxyfier, or Local sing-box.
+
+## Existing Proxyfier Detection
+
+The app detects an already installed Proxyfier layer before showing component
+status or applying profiles. Detection checks:
+
+- uninstall registry entries for `ProxiFyre` and `Proxifier`;
+- common install folders such as `C:\Tools\ProxiFyre`,
+  `%ProgramFiles%\ProxiFyre`, and `%ProgramFiles%\Proxifier`;
+- running `ProxiFyre` / `Proxifier` processes and the `ProxiFyreService`
+  service.
+
+For portable installs, set an override before launching the app:
+
+```powershell
+$env:VPN_PROXY_PROXIFYRE_ROOT = 'D:\Tools\ProxiFyre'
+npm run tauri -- dev
+```
+
+`ProxiFyre` installs are compatible with the current generated
+`app-config.json` apply path. Plain `Proxifier` installs are detected and shown,
+but automatic profile apply is not enabled for them yet because they use a
+different profile format.
+
+## MVP Verification Flow
+
+1. Start the Control App or browser preview.
+2. Confirm Components shows Control App, Proxyfier Layer, and optional Local
+   sing-box separately.
+3. Add or keep an external SOCKS5 target.
+4. Add a process/folder/exe profile such as Discord.
+5. Apply profiles and verify generated ProxiFyre config plus activity entry.
+6. Install Proxyfier separately before applying to a real service.
+7. Install and start Local sing-box only when using a local target.
+
+Task evidence is recorded in
+`docs/goals/windows-modular-client/EVIDENCE.md`.