ProxyWarden/docs/agent/ARCHITECTURE-NOTES.md

ProxyWarden Architecture Notes for Agents

Current design

ProxyWarden is a local Windows control app. It does not proxy traffic by itself. It orchestrates:

1. ProxiFyre for per-app routing.
2. Optional local sing-box for subscription-based outbound routing.
3. External SOCKS5 target for direct proxy routing.

Route modes

External SOCKS5:

selected Windows apps -> ProxiFyre -> external SOCKS5

Local sing-box:

selected Windows apps -> ProxiFyre -> 127.0.0.1:1080 -> sing-box selected outbound

Main risks

• Large orchestration files: commands.rs and App.tsx.
• Security-sensitive elevated operations.
• Secrets in subscription/proxy config.
• Non-atomic writes to generated configs.
• Stale component status.
• Duplicate sing-box server tags.
• UI/business logic entanglement.

Desired direction

Backend:

• Thin Tauri command handlers.
• Use-case modules.
• Testable pure functions.
• Structured errors.
• Atomic writes and hardened temp/elevation handling.

Frontend:

• Smaller App.tsx.
• Extracted hooks/components.
• Typed API boundary.
• Testable readiness/snapshot/proxy parsing logic.
• Clear UX for pending changes and service state.

Security:

• CSP enabled.
• Minimal Tauri capabilities.
• No broad shell permission.
• Redacted secrets.
• Safe deletion.
• Explicit Windows service control.