VPNTray/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Commands

Running the Application

• uv run python main.py - Start the VPN manager GUI application
• uv run python main.py & - Start the application in background for testing
• The application runs as a system tray application and can be minimized to the tray

Managing Running Instances

• ps aux | grep "python main.py" | grep -v grep - Check for running instances
• pkill -f "uv run python main.py" - Kill running instances (recommended)
• Note: KillBash only kills the shell, not the spawned uv process - use pkill instead

Development Environment

• This project uses uv for Python package management
• uv sync - Install dependencies from pyproject.toml
• Python 3.13+ required
• Dependencies: PyGObject (GTK3), pystray, Pillow, PyYAML

Configuration Management

• python init_config.py - Initialize configuration directory with examples
• python data_loader.py --init - Alternative way to create example files
• Configuration location: ~/.vpntray/customers/
• Each customer gets their own YAML file (e.g., customer_name.yaml)

Code Architecture

Core Components

main.py - Main GUI application entry point

• VPNManagerWindow class: Primary PyGObject/GTK3-based GUI application
• Two-column layout: active customers (left) vs inactive customers (right)
• Features system tray integration using pystray
• Uses GNOME-style theming with CSS card styling
• Includes comprehensive logging system with collapsible log view
• HeaderBar for native GNOME look and feel
• Current location tracking and enhanced display with network topology

models.py - Type-safe data model definitions using dataclasses and enums

• ServiceType: Enum for service types (SSH, Web GUI, RDP, VNC, SMB, Database, FTP)
• HostType: Enum for host types (Linux, Windows, Windows Server, Proxmox, ESXi, Router, Switch)
• VPNType: Enum for VPN types (OpenVPN, WireGuard, IPSec)
• Service: Individual services on hosts with type-safe enums and port numbers
• Host: Physical/virtual machines with multiple IP addresses, services, and recursive sub-hosts (VMs)
• Location: Customer locations with VPN configurations and host infrastructure
• CustomerService: Customer's cloud/web services (O365, CRM, etc.)
• Customer: Top-level entities containing services and locations
• Each model includes comprehensive helper methods for common operations

data_loader.py - YAML-based data management layer

• load_customers(): Loads customer configurations from ~/.vpntray/customers/*.yaml files
• save_customer(): Saves customer data back to YAML files with proper enum serialization
• initialize_example_customers(): Creates example configuration files
• Robust parsing with enum conversion, error handling, and graceful fallbacks
• Falls back to demo data if no configuration files exist
• Supports both .yaml and .yml file extensions

views/ - High-level UI view management (MVC pattern)

• active_view.py: ActiveView class for displaying active locations with full interaction
• inactive_view.py: InactiveView class for search results (inactive locations)
• Clean separation of concerns with dedicated view controllers
• __init__.py: View exports for clean imports

widgets/ - Modular UI components using PyGObject

• customer_card.py: ActiveCustomerCard and InactiveCustomerCard classes
  • Compact tree-like design: Hierarchical layout with expand/collapse arrows
  • Card styling: Customer cards contain location subcards with proper visual hierarchy
  • Multi-column layout: Fixed-width columns for proper alignment (name, IP, actions)
  • Service action icons: Direct access buttons for SSH, RDP, Web GUI with tooltips
  • Multiple IP support: Display primary IP with hover tooltip showing all addresses
  • Active cards: Full interaction with connection controls and infrastructure details
  • Inactive cards: Activation buttons and current location setting
• location_card.py: ActiveLocationCard and InactiveLocationCard classes
  • Active cards: Connection controls, deactivation (X button), and infrastructure details
  • Inactive cards: Current location setting and activation buttons
• host_item.py: HostItem class for displaying hosts and their services
  • Hierarchical display supporting hypervisors with sub-hosts (VMs)
  • Service buttons for direct access to SSH, Web GUI, RDP services
• __init__.py: Widget exports for clean imports

services/ - VPN and credential management (modular architecture)

• vpn_manager.py: NetworkManager (nmcli) integration with .ovpn file support
• passbolt_client.py: Passbolt CLI client for secure credential management
• connection_manager.py: High-level orchestrator combining VPN and credentials
• Support for flexible credential storage (direct username/password or Passbolt UUIDs)

views/ - Comprehensive logging system

• log_view.py: LogView class with collapsible interface
  • Command logging: Real-time capture of nmcli and system command output
  • Color-coded levels: Info, success, warning, error with visual distinction
  • Auto-scroll: Automatic scrolling to latest entries with manual override
  • Expandable/collapsible: Bottom panel that can be hidden to save space

Configuration Files

• init_config.py: Helper script to initialize user configuration with examples
• example_customer.yaml: Complete example showing YAML schema with all features
• User config: ~/.vpntray/customers/*.yaml - One file per customer

Key Architecture Patterns

Hierarchical Data Structure: Customer → Location → Host → Service

• Customers have cloud services (accessible anywhere) and multiple physical locations
• Each location has VPN configuration, connection state, and host infrastructure
• Hosts can have sub-hosts (VMs under hypervisors) with recursive nesting
• Services represent endpoints (SSH, Web GUI, RDP, etc.) with specific ports

Location State Management:

• Active/Inactive: Locations can be activated for VPN management
• Current Location: User's physical location (separate from VPN connections)
• Connection State: VPN connection status independent of location activation
• Network Topology: Each location includes internal networks and external endpoints
• Credential Management: Flexible credential storage (direct or Passbolt UUID)
• Automatic UI updates based on state changes with immediate feedback

Two-Column Layout Architecture:

• Left column: Active customers with full location details and infrastructure
• Right column: Inactive customers available for activation
• Compact design: Tree-like hierarchy with proper indentation and alignment
• Real-time filtering: Search affects both columns simultaneously
• Dynamic reorganization: Customers move between columns based on location state

Widget-Based Component System:

• Modular widget classes handle their own GTK widget creation and event handling
• Callback system for widget-to-main-window communication
• Clear separation between data models and UI representation
• Different widget behavior for active vs inactive states

Type-Safe Configuration System:

• Comprehensive enum usage for all categorical data
• YAML-based configuration with robust parsing and validation
• Graceful error handling and fallback mechanisms
• Easy extensibility for new service types, host types, and VPN protocols

Current Location Tracking

The application tracks two distinct location concepts:

• Current Location: Where the user physically is (set via "Set as Current" button)
• Active Locations: Locations available for VPN connections

Enhanced Current Location Display:

• Prominent info box with customer name, location, and VPN type
• Host count summary with VM breakdown (e.g., "3 hosts (7 total with VMs)")
• Collapsible infrastructure section with detailed host and VM information
• Network topology display: Internal networks and external endpoints
• Visual host type icons (🐧 Linux, 🪟 Windows, 📦 Proxmox, 🌐 Router, etc.)
• Hierarchical VM display with service counts and multiple IP addresses
• Multi-interface support: Hosts can have multiple IP addresses (firewalls, routers)
• Users can set current location from inactive location cards without activating VPN

Search and Discovery Features

Advanced Search Functionality:

• Real-time search across customers, locations, hosts, and services
• Wildcard support: Type * to show all inactive locations
• Smart filtering: Search includes IP addresses, service types, and port numbers
• Context switching: Empty search shows active view, any text shows search results
• Auto-clear: Activating a location automatically clears search and returns to active view

Data Flow

1. Initialization: data_loader.load_customers() loads configurations from YAML files in ~/.vpntray/customers/
2. UI Setup: Creates views and widgets using callback architecture
3. Search/Filter: Real-time filtering with wildcard support and smart matching
4. View Management: Gtk.Stack manages smooth transitions between active/inactive views
5. User Interactions: Callbacks update dataclass attributes with immediate UI feedback
6. Persistence: Changes can be saved back to YAML files using save_customer()
7. State Updates: Location activation, connection changes, and current location updates

UI Layout Structure

Modern Two-Column Design:

• HeaderBar with title and current location display
• Enhanced current location info box with network topology and collapsible infrastructure
• Search entry with real-time filtering across both columns
• Left column: Active customers with full interaction (connections, services, infrastructure)
• Right column: Inactive customers with activation and current location setting
• Compact tree-like cards with customer cards containing location subcards
• Fixed-width columns: Proper alignment of host names, IP addresses, and action icons
• Collapsible log view: Bottom panel for command output and system logs
• GNOME-style cards with CSS theming, proper spacing, and visual hierarchy
• System tray integration for minimize-to-tray behavior

Customer Card Features:

• Active cards: Start expanded, show full location details and services
• Inactive cards: Start collapsed to save space during search
• Location count badges: Show number of locations in parentheses
• Smooth expand/collapse: Click arrow buttons to toggle content visibility

GTK3/PyGObject Specific Features

• CSS styling: GNOME-style cards with borders, shadows, and adaptive theming
• Native widgets: HeaderBar, SearchEntry, ScrolledWindow, Stack with crossfade transitions
• Proper GNOME HIG compliance: Spacing, margins, typography, and layout
• Button styling: suggested-action and destructive-action classes for clear visual hierarchy
• Thread-safe integration: System tray using GLib.idle_add for thread safety
• Responsive design: Proper scrolling and adaptive layouts

Mock Implementation Status

• Currently a UI mockup with no actual VPN functionality
• All VPN operations (connect, disconnect, routes) are placeholder methods
• Button actions update UI state but don't perform real network operations
• Rich configuration system ready for real VPN client integration
• Comprehensive infrastructure modeling supports complex network topologies

YAML Configuration Schema

Customer files in ~/.vpntray/customers/ follow this structure:

name: Customer Name

# Cloud/web services (always accessible)
services:
  - name: Service Name
    url: https://service.url
    service_type: Service Category
    description: Optional description

# Physical locations with VPN and infrastructure
locations:
  - name: Location Name
    vpn_type: OpenVPN|WireGuard|IPSec
    vpn_config: /path/to/config/file
    
    # VPN credentials (three options):
    # Option 1: Dictionary with username/password
    vpn_credentials:
      username: vpnuser
      password: password123
    
    # Option 2: Passbolt UUID (for future implementation)
    # vpn_credentials: "550e8400-e29b-41d4-a716-446655440000"
    
    # Option 3: Omit or set to null if no credentials needed
    # vpn_credentials: null
    
    # Note: active and connected are runtime state (not stored in config)
    
    # Network topology information
    external_addresses: [vpn.domain.com, backup.domain.com]  # VPN endpoints
    networks: [192.168.1.0/24, 10.0.1.0/24]  # Internal networks
    
    hosts:
      - name: Host Name
        ip_addresses: [192.168.1.10, 10.0.1.10]  # Multiple interfaces supported
        host_type: Linux|Windows|Windows Server|Proxmox|ESXi|Router|Switch
        description: Optional description
        
        services:
          - name: Service Name
            service_type: SSH|Web GUI|RDP|VNC|SMB|Database|FTP
            port: Port Number
            
        sub_hosts: # Optional VMs/containers (recursive structure)
          - name: VM Name
            ip_addresses: [192.168.1.20]  # VMs can also have multiple IPs
            host_type: Linux|Windows|Windows Server
            services: # Same structure as parent host
              - name: Service Name
                service_type: SSH|Web GUI|RDP
                port: Port Number

Future Extensibility

VPN Integration Ready:

• Implement actual VPN connection logic in placeholder methods
• Add real-time VPN status monitoring and automatic reconnection
• Support for multiple VPN clients (OpenVPN, WireGuard, IPSec)
• Integration with system network management

Configuration Management:

• Import/export functionality for customer configurations
• Configuration validation with detailed error reporting
• Backup and restore capabilities
• Multi-user configuration support

UI Enhancements:

• Settings panel for application preferences
• Connection logs and monitoring
• Network diagnostics and troubleshooting tools
• Custom themes and layout preferences
• Notification system for connection status changes

Advanced Features:

• Auto-discovery of network services and hosts
• Integration with network monitoring tools
• SSH key management and authentication
• Bookmark system for frequently accessed services
• Connection history and analytics

Development Notes

Code Quality:

• Type hints throughout codebase for better IDE support
• Comprehensive error handling with graceful degradation
• Clean separation of concerns (MVC pattern)
• Extensive use of dataclasses and enums for type safety

Testing Strategy:

• Configuration can be tested with example YAML files
• UI components are modular and independently testable
• Mock data system allows UI testing without VPN dependencies

Performance Considerations:

• Efficient YAML loading with caching
• Minimal UI updates with smart re-rendering
• Background thread for system tray to prevent UI blocking
• Lazy loading of complex widget hierarchies