# VPN Shield — Windows Conversion Checklist

> Quick-reference checklist. For detailed instructions, see [WINDOWS_SETUP_GUIDE.md](./WINDOWS_SETUP_GUIDE.md).
> For native code files and integration steps, see [windows_implementation/README.md](./windows_implementation/README.md).

---

## Phase 1: Install Development Tools

- [ ] **Install Git for Windows**
  - Download: https://git-scm.com/download/win
  - Verify: `git --version` → shows `git version 2.x.x`

- [ ] **Install Flutter SDK**
  - Download: https://docs.flutter.dev/get-started/install/windows/desktop
  - Extract to `C:\flutter` (NO spaces in path!)
  - Add `C:\flutter\bin` to system PATH
  - Verify: `flutter --version` → shows Flutter 3.27+

- [ ] **Install Visual Studio 2022 Community**
  - Download: https://visualstudio.microsoft.com/downloads/
  - Select workload: **"Desktop development with C++"**
  - Ensure components: MSVC v143 build tools + Windows 10/11 SDK
  - Verify: `flutter doctor` → [✓] Visual Studio

- [ ] **Install WireGuard for Windows**
  - Download: https://www.wireguard.com/install/
  - Verify: `dir "C:\Program Files\WireGuard\tunnel.dll"` → file exists

- [ ] **Run full diagnostics**
  - `flutter doctor -v` → all 4 checkmarks green:
    - [✓] Flutter
    - [✓] Windows Version
    - [✓] Visual Studio
    - [✓] Connected device

---

## Phase 2: Generate Windows Platform

- [ ] **Enable Windows desktop**
  - `flutter config --enable-windows-desktop`

- [ ] **Generate windows/ directory**
  - `flutter create --platforms=windows .`
  - Verify: `windows/` folder exists with `runner/` subfolder

- [ ] **Test basic build**
  - `flutter build windows --debug` → compiles without errors
  - `flutter run -d windows` → app launches, login screen shows

---

## Phase 3: Add WireGuard Libraries

- [ ] **Copy tunnel.dll**
  - `mkdir windows\runner\libs`
  - `copy "C:\Program Files\WireGuard\tunnel.dll" windows\runner\libs\`

- [ ] **Update CMakeLists.txt**
  - Add `add_custom_command` to copy tunnel.dll to build output
  - (See WINDOWS_SETUP_GUIDE.md Phase 3, Step 3.3)

---

## Phase 4: Integrate Native C++ Code

- [ ] **Back up original files**
  - `copy windows\runner\flutter_window.h windows\runner\flutter_window.h.bak`
  - `copy windows\runner\flutter_window.cpp windows\runner\flutter_window.cpp.bak`
  - `copy windows\runner\runner.exe.manifest windows\runner\runner.exe.manifest.bak`

- [ ] **Replace flutter_window.h**
  - Copy from `windows_implementation/flutter_window.h`
  - Verify: file contains `wireguard_channel_` member

- [ ] **Replace flutter_window.cpp**
  - Copy from `windows_implementation/flutter_window.cpp`
  - Verify: file contains `"com.primio.vpnshield/wireguard"` channel registration
  - Verify: file handles `establishTunnel`, `tearDownTunnel`, `getTunnelStats`

- [ ] **Replace runner.exe.manifest**
  - Copy from `windows_implementation/runner.exe.manifest`
  - Verify: contains `level="requireAdministrator"`

- [ ] **Verify tunnel.dll API compatibility**
  - Run: `dumpbin /exports tunnel.dll`
  - Check exported function names match the code
  - Adjust `typedef` and `GetProcAddress` calls if needed

---

## Phase 5: Build & Test

- [ ] **Clean build**
  - `flutter clean && flutter pub get && flutter build windows --debug`

- [ ] **Run as Administrator**
  - Open PowerShell as Admin
  - `flutter run -d windows --verbose`

- [ ] **Test login flow**
  - Enter credentials → authenticates with API ✓

- [ ] **Test server list**
  - Servers load and display with load indicators ✓

- [ ] **Test VPN connect**
  - Select server → Connect → status changes to "Connected" ✓
  - Check tunnel: `Get-NetAdapter | Where-Object { $_.InterfaceDescription -like "*WireGuard*" }`

- [ ] **Test VPN stats**
  - Duration timer counting up ✓
  - Bytes up/down updating ✓

- [ ] **Test VPN disconnect**
  - Disconnect → status returns to "Disconnected" ✓
  - WireGuard adapter removed ✓

- [ ] **Test IP verification**
  - While connected: `Invoke-WebRequest "https://api.ipify.org"` → shows VPN IP
  - After disconnect: same command → shows real IP

---

## Phase 6: Release Build

- [ ] **Build release**
  - `flutter build windows --release`

- [ ] **Verify output**
  - `build\windows\x64\runner\Release\` contains:
    - [ ] vpnshield.exe (or runner.exe)
    - [ ] flutter_windows.dll
    - [ ] tunnel.dll
    - [ ] data/ folder with flutter_assets

- [ ] **Test release build**
  - Double-click .exe → UAC prompt appears → app runs correctly

---

## Common Issues Quick Reference

| Symptom | Fix |
|---|---|
| `flutter doctor` shows [✗] Visual Studio | Install "Desktop development with C++" workload |
| Build fails with CMake errors | Run from Developer PowerShell for VS 2022 |
| tunnel.dll not found at runtime | Check `add_custom_command` in CMakeLists.txt |
| Access Denied on tunnel create | Run app as Administrator |
| MissingPluginException | Channel name mismatch — must be `com.primio.vpnshield/wireguard` |
| App won't launch from flutter run | Run terminal as Administrator (manifest requires elevation) |
| 0xc000007b error | Architecture mismatch — ensure 64-bit tunnel.dll |

---

*Checklist version 1.0 — May 2026*
