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:

```yaml
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