# 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\config\local-singbox.json
C:\ProgramData\VpnProxy\state\singbox-subscription-cache.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.

Local sing-box install creates this optional runtime:

```text
C:\Program Files\VpnProxy\sing-box\sing-box.exe
C:\Program Files\VpnProxy\sing-box\VpnProxySingBox.exe
Windows service: VpnProxySingBox
```

The install flow downloads `sing-box` from `SagerNet/sing-box` releases and the
WinSW service wrapper from `winsw/winsw` releases, then writes a service config
that points at `C:\ProgramData\VpnProxy\generated\sing-box-config.json`. It
requires UAC confirmation. Uninstall is scoped to the configured
`VpnProxy\sing-box` install root.

The external proxy route remains independent from Local sing-box. Choosing
Local sing-box in the UI generates `sing-box-config.json`, ensures the
`local-singbox` SOCKS5 target at `127.0.0.1:1080`, and then applies ProxiFyre
to that local target.

## 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` and
`docs/goals/windows-local-singbox/EVIDENCE.md`.