# VPN Shield

## Overview
A Windows desktop VPN client that connects to a WireGuard backend API at vpnendpoints.abacusai.app. Users authenticate with email/password, browse server locations, and establish encrypted VPN tunnels. Designed as a single-platform Windows app with deep space aesthetic.

## Tech Stack & Key Decisions
- Dio for HTTP with interceptor-based JWT auto-refresh on 401 responses
- flutter_secure_storage for persisting access/refresh tokens securely on Windows
- MethodChannel `com.primio.vpnshield/wireguard` for native WireGuard tunnel management via wireguard.dll — Flutter side gracefully handles MissingPluginException when native code isn't built yet
- Provider + ChangeNotifier for state — simple enough for this app's scope
- No go_router — auth gating handled via widget-level conditional rendering since navigation is sidebar-based, not deep-linked

## Architecture
- Auth flow: AuthRepository handles API calls + secure storage → AuthService adds validation + creates authenticated Dio instances with refresh interceptor → AuthProvider manages login state
- VPN flow: ServerRepository + SessionRepository use the authenticated Dio → VpnService orchestrates server fetch + tunnel establishment via MethodChannel → VpnProvider manages connection state + polling
- _AuthGate widget in main.dart conditionally renders LoginScreen or HomeScreen with VPN-scoped providers — VPN providers only exist when authenticated
- Stats polling: 1s timer for duration display, 3s timer for native tunnel byte stats via MethodChannel

## Conventions
- Repositories are app-global; services and providers are scoped to authenticated session via _AuthGate MultiProvider
- MethodChannel calls wrapped in try/catch for MissingPluginException — allows full Flutter development without native build
- Settings screen toggles are UI-only placeholders — persistence requires SharedPreferences wiring
- Server load < 40% = green, 40-75% = yellow, 75%+ = red

## Key Patterns & Gotchas
- AuthProvider.authenticatedDio is nullable — only non-null after successful login; _AuthGate uses `auth.authenticatedDio!` safely because it's gated behind `auth.isAuthenticated`
- The AnimatedBuilder in connection_panel.dart is a custom AnimatedWidget subclass (not the framework's AnimatedBuilder which doesn't exist) — used for the pulsing orb effect
- VPN disconnect calls both native teardown AND server-side disconnect; native failure is caught silently so server session always cleans up

## Design System
- Deep space theme: #08081A navy background creates immersive dark environment appropriate for a security/privacy tool
- Gradient accents (violet #7C3AED → purple #A855F7) for primary actions and branding — signals premium security product
- Electric cyan #06B6D4 for secondary elements and data visualization — provides contrast against warm violet
- Inter font throughout for clean technical readability on desktop screens
- 8px spacing grid; 12px card radius; cards use subtle borders (#1E1E3A) rather than elevation for depth
