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
• Implements single-view layout with Gtk.Stack for smooth transitions
• Features system tray integration using pystray
• Uses GNOME-style theming with CSS styling for cards
• Includes advanced search functionality with wildcard support (*)
• HeaderBar for native GNOME look and feel
• Current location tracking and display

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 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
  • Active cards: Interactive buttons for customer services and full location details
  • Inactive cards: Read-only service lists and location activation buttons
• 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

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
• Automatic UI updates based on state changes with immediate feedback

Single-View UI Architecture with Stack Navigation:

• Uses Gtk.Stack for smooth view transitions with crossfade animation
• Normal mode: Shows only active locations (full detail view)
• Search mode: Shows only inactive locations (activation and current location setting)
• Clean visual separation with no overlapping or confusing dual-column layouts

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
• Current location is displayed prominently above the search bar
• 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 Single-View Design:

• HeaderBar with title and subtitle (GNOME HIG compliance)
• Current location display (centered, prominent)
• Search entry with comprehensive placeholder text (supports * wildcard)
• Single-view layout using Gtk.Stack for smooth transitions
• Normal mode: Active locations with full interaction (connections, services, infrastructure)
• Search mode: Inactive locations with activation and current location setting
• GNOME-style cards with CSS theming, proper spacing, and visual hierarchy
• System tray integration for minimize-to-tray behavior

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
    active: true|false          # Available for VPN management
    connected: true|false       # Current VPN connection status
    
    hosts:
      - name: Host Name
        ip_address: IP Address
        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_address: VM IP
            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