System Architecture & Design Principles

Neutron is designed with a strictly decoupled architecture where all networking, security, and state logic exist in pure Rust modules that can be driven by any UI frontend (CLI, TUI, or GUI).

High-Level Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                            User Interface Layer                             │
│  ┌───────────────────────┐  ┌───────────────────────┐  ┌─────────────────┐  │
│  │     CLI (clap)        │  │     GUI (Adwaita)     │  │   TUI (ratatui) │  │
│  │ (Scripting & Headless)│  │ (GNOME Desktop Window)│  │ (Terminal UI)   │  │
│  └───────────┬───────────┘  └───────────┬───────────┘  └────────┬────────┘  │
└──────────────┼──────────────────────────┼───────────────────────┼───────────┘
               └──────────────────────────┼───────────────────────┘
                                          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            Core Decoupled Engine                            │
│  ┌─────────────────────────┐  ┌─────────────────────────┐  ┌─────────────┐  │
│  │   NetworkManager (nm/)  │  │  Firewall (firewall/)   │  │ NAT-PMP     │  │
│  │ • Profile Discovery     │  │ • Lockdown Netfilter    │  │ (portforward│  │
│  │ • Policy Kill Switch    │  │ • Surgical Teardown     │  │ • UDP Lease │  │
│  │ • Split Tunnel Routes   │  │ • pkexec Orchestration  │  │ • Auto-Renew│  │
│  └─────────────────────────┘  └─────────────────────────┘  └─────────────┘  │
│  ┌─────────────────────────┐  ┌─────────────────────────┐                   │
│  │    Config (config/)     │  │    Service (service/)   │                   │
│  │ • Atomic Persistence    │  │ • Random Boot Selector  │                   │
│  │ • Unix Mode 0600        │  │ • Autostart Unit        │                   │
│  └─────────────────────────┘  └─────────────────────────┘                   │
└─────────────────────────────────────────────────────────────────────────────┘

Subsystem Responsibilities

1. nm/ — NetworkManager Control Plane

• Trait NmClient provides an abstract interface for listing, connecting, disconnecting, switching profiles, setting kill-switch properties, and applying split-tunneling routes.
• CliNmClient interacts with NetworkManager via nmcli with a strict 30-second execution deadline.
• Submodule nm::split_tunnel validates and normalizes CIDRs, resolves domain names to IP addresses, and formats ipv4.routes / ipv6.routes / never-default arguments.
• Submodule nm::kill_switch configures kernel policy routing (wireguard.ip4-auto-default-route) and negative DNS priorities (-1500).

2. firewall/ — Always-On Lockdown Netfilter Engine

• Trait FirewallClient manages permanent direct OUTPUT chain rules in firewalld.
• Uses mangle OUTPUT allow-list rules and a final DROP before filter-table established accepts; see Security & Kill Switch.
• All rules are tagged with a unique comment (neutron-lockdown) ensuring surgical removal without modifying user-defined firewall rules.
• Privilege escalation is consolidated into one pkexec shell batch, with permanent fail-closed guards during rebuilds.

3. portforward/ — NAT-PMP Dynamic Port Leasing & App Integrations

• Implements RFC 6886 NAT-PMP client directly over std::net::UdpSocket.
• Derives the gateway address from the local tunnel IPv4 address (10.x.x.x / 100.x.x.x).
• Acquires dynamic UDP/TCP port mappings and schedules automatic lease renewals before expiration.
• Integrates portforward::qbittorrent Web API bridge to automatically synchronize dynamic listening ports to qBittorrent (native, Flatpak, containerized).

4. config/ — Configuration & State Persistence

• Manages AppConfig serialized as TOML in ~/.config/neutron/config.toml.
• Implements atomic file writes (fs::rename with fallback across filesystem boundaries) with strict 0o600 permissions.
• Stores policy intent, startup eligibility, favorites, theme settings, and integration settings. Narrow updates are serialized by a sidecar file lock.

5. service/ — Boot-Time Automation

• Implements the one-shot random profile selector for login / boot.
• Manages XDG desktop autostart entries (~/.config/autostart/io.github.pandabytez.neutron.desktop).
• Prevents immediate profile repeats and respects user-defined eligibility exclusion sets.

Frontend & Resource Comparison Matrix