vpn-proxy/docs/superpowers/specs/2026-05-21-windows-client-design.md

Windows Client Design

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.

Product Shape

The Windows mode is script-first and UI-assisted. The installer remains the durable entrypoint because Windows driver/service setup needs administrator rights and must stay easy to debug from PowerShell. The web UI is a local control surface on top of the same scripts, not a separate desktop app in the first version.

The installer supports two paths:

• Full install: install native sing-box.exe, configure a local SOCKS/HTTP proxy on 127.0.0.1:1080, install WinPacketFilter and ProxiFyre, then route selected Windows apps through the local proxy.
• ProxiFyre only: install WinPacketFilter and ProxiFyre, then point selected Windows apps to an existing proxy target such as 127.0.0.1:8080, 192.168.50.111:8080, or another reachable SOCKS5 endpoint.

The default UI direction is the approved cleaner mockup: one route status, profiles as the main object, selected profile details on the right, and a short recent activity/log section below. The first screen should answer: what is the active proxy target, whether services are running, and which profiles are currently enabled.

User Flows

Install

The user opens PowerShell 7 as Administrator and runs:

irm https://git.dokops.ru/dokril/vpn-proxy/raw/branch/master/scripts/install-windows-client.ps1 | iex

The installer checks administrator rights, PowerShell version, architecture, internet access, and required paths. It installs under C:\Tools\vpn-proxy-windows and keeps third-party runtime files in focused subdirectories:

• C:\Tools\vpn-proxy-windows\app for this project checkout or archive.
• C:\Tools\vpn-proxy-windows\runtime\node for portable Node.js when no suitable Node is installed.
• C:\Tools\vpn-proxy-windows\runtime\sing-box for sing-box.exe, config, and logs.
• C:\Tools\ProxiFyre for ProxiFyre, matching the legacy script path.

If the user chooses Full install, the installer asks for a subscription or VLESS link, parses it through the existing subscription logic where possible, lets the user select a server, writes the native sing-box config, installs a scheduled task for sing-box, and starts it.

If the user chooses ProxiFyre only, the installer asks for a SOCKS5 proxy target and verifies TCP connectivity before writing ProxiFyre config.

After setup, the installer starts the local control UI on http://127.0.0.1:3456 and prints recovery commands:

& "C:\Tools\vpn-proxy-windows\manage.ps1"
& "C:\Tools\vpn-proxy-windows\manage.ps1" -OpenUi
& "C:\Tools\vpn-proxy-windows\manage.ps1" -Status

Profile Management

Profiles are the central unit. A profile contains a name, enabled flag, proxy target, protocol list, and app items. Supported item types:

• process: process name such as Discord, Update, or Vesktop.
• folder: folder path; the system scans .exe files and converts them to routable entries.
• exe: explicit executable file path; the system resolves it to the executable name for ProxiFyre and keeps the full path for display and diagnostics.

Folder and exe entries are intentionally stored as user-facing source items, while the generated ProxiFyre config is derived. This keeps the UI understandable and makes future ProxiFyre/Proxifier adapter changes possible without changing the profile model.

When a profile changes, the UI marks it as pending. The user applies changes once. Apply regenerates ProxiFyre app-config.json, restarts the ProxiFyre service, then writes an activity entry showing what changed.

Runtime Operations

The UI exposes these actions:

• start, stop, restart sing-box when local mode is installed;
• start, stop, restart ProxiFyre;
• switch a profile between local-singbox and an external proxy target;
• add process, folder, or exe entries;
• scan folder entries again;
• copy diagnostics for support/debugging;
• open logs.

The UI does not auto-change global Windows proxy settings. Routing happens only through ProxiFyre profiles.

Architecture

The active project already has a plain Node API server, React/Vite UI, subscription parser, sing-box config generator, logs, traffic parsing, and client/gateway modes. Windows mode should reuse those pieces and add a Windows helper boundary.

App Mode

Add APP_MODE=windows. In Windows mode:

• the HTTP server binds to 127.0.0.1;
• the UI uses Windows labels and hides gateway-only TProxy/device controls;
• config generation is proxy-only like client mode, but it targets native sing-box.exe rather than Docker;
• service and driver actions go through the PowerShell helper, not direct Node assumptions.

Windows Helper Boundary

Create a PowerShell helper module that owns privileged Windows operations:

• install/update sing-box.exe;
• install/start/stop scheduled tasks;
• install/update WinPacketFilter;
• install/update ProxiFyre;
• write ProxiFyre config;
• query service/task status;
• read recent log files;
• test proxy connectivity;
• manage firewall rules for local proxy ports.

The Node server calls the helper with explicit command names and JSON input/output. The helper returns structured JSON for every operation:

{
  "success": true,
  "action": "proxies.apply",
  "changed": true,
  "message": "ProxiFyre config applied and service restarted"
}

Errors use the same shape with success: false, error, and optional details. The UI never parses raw PowerShell text.

Data Files

Windows mode stores state under C:\Tools\vpn-proxy-windows\data:

• windows-profiles.json for profile source data.
• proxy-targets.json for local-singbox and external proxy targets.
• windows-state.json for last applied profile revision and UI status.
• subscription-cache.json and state.json stay compatible with existing subscription/server selection logic.

Profile shape:

{
  "id": "discord-vesktop",
  "name": "Discord + Vesktop",
  "enabled": true,
  "proxyTargetId": "local-singbox",
  "protocols": ["TCP", "UDP"],
  "items": [
    { "type": "process", "value": "Discord" },
    { "type": "process", "value": "Update" },
    {
      "type": "folder",
      "value": "%LOCALAPPDATA%\\vesktop",
      "recursive": true
    },
    {
      "type": "exe",
      "value": "C:\\Games\\SomeGame\\game.exe"
    }
  ]
}

Generated ProxiFyre config is not edited directly. It is derived from enabled profiles and proxy targets, then written to C:\Tools\ProxiFyre\app-config.json.

API Surface

Add Windows-specific endpoints:

• GET /api/windows/status: returns install mode, sing-box status, ProxiFyre status, active target, pending changes, and recent activity.
• GET /api/windows/profiles: returns profile source data with resolved executable counts.
• PUT /api/windows/profiles: saves profiles without applying.
• POST /api/windows/profiles/apply: generates ProxiFyre config and restarts service.
• POST /api/windows/profiles/scan: resolves folder and exe entries for preview.
• GET /api/windows/targets: returns local-singbox and external proxy targets.
• PUT /api/windows/targets: saves external proxy targets after validation.
• POST /api/windows/service: start, stop, or restart sing-box, ProxiFyre, or the UI service.
• GET /api/windows/logs: returns recent helper, sing-box, and ProxiFyre logs.

Existing generic endpoints for subscription fetch, server selection, apply, logs, and config validation should be reused where the behavior matches Windows mode.

UI Design

The approved direction is a restrained operational UI:

• top bar: product name, restart/stop/add profile actions;
• left nav: Overview, Profiles, Targets, Logs, Settings;
• main status panel: one sentence describing the active route, plus a compact route line such as Selected apps -> ProxiFyre -> sing-box -> VPN;
• main workspace: profile list on the left, selected profile details on the right;
• profile details: target selector, add process/folder/exe input, resolved items list, save/apply controls;
• activity panel: recent traffic/service events, not a full noisy log dump.

Avoid duplicate status blocks. Avoid showing raw implementation concepts like WinPacketFilter unless the user is in diagnostics/settings. The primary terms should be Profile, Proxy target, Local sing-box, Existing proxy, App/folder/exe, and Apply changes.

Safety And Constraints

The UI binds only to 127.0.0.1. Windows actions that require elevation stay in the installer/helper path. The installer must not delete existing C:\Tools\vpn-proxy legacy folders without confirmation.

Folder and exe routing needs a clear diagnostic note: ProxiFyre routing ultimately depends on what the installed ProxiFyre version accepts. The first implementation should resolve folders and exe paths to executable names for compatibility, while preserving full paths in profile data and diagnostics. If direct path matching is verified in ProxiFyre, the adapter can emit full paths without changing the UI model.

The installer should be idempotent:

• re-running it updates project files;
• existing subscriptions and profiles are preserved unless the user chooses reset;
• existing ProxiFyre config is backed up before overwrite;
• failed applies leave the previous generated config available for rollback.

Testing And Verification

Use focused tests for pure logic:

• profile normalization;
• folder/exe item resolution;
• ProxiFyre config generation;
• proxy target validation;
• Windows helper JSON command contract;
• APP_MODE=windows public state and config generation.

Use manual Windows verification for privileged operations:

• fresh Full install;
• fresh ProxiFyre-only install;
• re-run installer over existing install;
• add process profile;
• add folder profile;
• add explicit exe profile;
• switch a profile from local sing-box to external proxy;
• restart ProxiFyre and verify service status;
• copy diagnostics after a failed proxy target check.

Local non-Windows development should still run npm test and npm run build. Windows-only helper commands should have dry-run or mockable modes so logic can be tested without installing drivers on the development machine.

Non-Goals For First Version

• No Electron or Tauri wrapper.
• No global Windows system proxy changes.
• No transparent routing without ProxiFyre.
• No remote multi-device management.
• No automatic uninstall of unrelated WinPacketFilter users.
• No Proxifier support until ProxiFyre behavior is stable.

Implementation Defaults

• The UI server runs when opened by manage.ps1 -OpenUi in the first version. An at-logon scheduled UI task can be added later after the helper and UI are stable.
• Full install uses portable Node/npm when the machine has no suitable Node.js. The installer builds the React UI locally for MVP; a prebuilt release artifact can replace that later without changing user-facing behavior.
• ProxiFyre generation emits process names in the first version for compatibility. Full folder and exe paths remain in profile data and diagnostics; the adapter can start emitting full paths later if ProxiFyre path matching is verified.