# 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 a two-column layout: active customers (left) vs inactive customers (right)
- Features system tray integration using `pystray`
- Uses GNOME-style theming with CSS styling for cards
- Includes search functionality across customers, locations, and hosts
- HeaderBar for native GNOME look and feel

**models.py** - 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
- `Host`: Physical/virtual machines with services and 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 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
- `initialize_example_customers()`: Creates example configuration files
- Robust parsing with enum conversion and error handling
- Falls back to demo data if no configuration files exist

**widgets/** - Modular UI components using PyGObject
- `customer_card.py`: `ActiveCustomerCard` and `InactiveCustomerCard` classes
- `location_card.py`: `ActiveLocationCard` and `InactiveLocationCard` classes
- `host_item.py`: `HostItem` class for displaying hosts and their services
- `__init__.py`: Widget exports for clean imports

**views/** - High-level UI view management
- `active_view.py`: `ActiveView` class for displaying active locations
- `inactive_view.py`: `InactiveView` class for search results (inactive locations)
- `__init__.py`: View exports for clean imports

**Configuration Files**
- `init_config.py`: Helper script to initialize user configuration
- `example_customer.yaml`: Complete example showing YAML schema
- 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 locations
- Each location has VPN configuration, connection state, and host infrastructure
- Hosts can have sub-hosts (VMs under hypervisors) and multiple services
- Services represent endpoints (SSH, Web GUI, RDP, etc.) that can be launched

**Active/Inactive Location Management**:
- Locations (not customers) are activated/deactivated individually
- Left column shows customers with active locations (full detail view)
- Right column shows customers with inactive locations (summary cards)
- UI automatically reorganizes based on location activation state

**Widget-Based UI Architecture**:
- Modular widget classes handle their own GTK widget creation
- Callback system for widget-to-main-window communication
- Clean separation between data models and UI representation

**Mock Implementation**: 
- 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 mock data includes hypervisors with VMs, various service types

### Data Flow
1. `data_loader.load_customers()` loads customer configurations from YAML files in `~/.vpntray/customers/`
2. Main window loads and filters data based on search terms (including `*` wildcard for all inactive)
3. View classes (`ActiveView`/`InactiveView`) manage display using widget components
4. User interactions trigger callbacks that update dataclass attributes
5. Changes can be persisted back to YAML files using `save_customer()`
6. UI re-renders to reflect state changes with smooth transitions via Gtk.Stack

### UI Layout Structure
- HeaderBar with title and subtitle (GNOME HIG compliance)
- Search entry with placeholder text for filtering (supports `*` wildcard)
- Single-view layout using Gtk.Stack for smooth transitions
- **Normal mode**: Shows only active locations (full detail view)
- **Search mode**: Shows only inactive locations matching search term (activation cards)
- GNOME-style cards with CSS theming and proper spacing
- System tray integration for minimize-to-tray behavior

### GTK3/PyGObject Specific Features
- CSS styling for GNOME-style cards with borders, shadows, and theming
- Native GTK widgets: HeaderBar, SearchEntry, ScrolledWindow, Stack
- Smooth view transitions using Gtk.Stack with crossfade animation
- Proper GNOME HIG compliance for spacing, margins, and layout
- Button styling with suggested-action and destructive-action classes
- Thread-safe system tray integration using GLib.idle_add

### Future Extensibility
- Implement actual VPN connection logic in placeholder methods
- Add real-time VPN status monitoring and automatic reconnection
- Extend YAML schema for additional VPN configuration options
- Add import/export functionality for customer configurations
- Implement configuration validation and error reporting
- Add support for additional VPN clients and protocols
- Extend widget system for additional UI components (settings, logs, etc.)

### YAML Configuration Schema
Customer files in `~/.vpntray/customers/` follow this structure:
```yaml
name: Customer Name
services:
  - name: Service Name
    url: https://service.url
    service_type: Service Category
    description: Optional description
locations:
  - name: Location Name
    vpn_type: OpenVPN|WireGuard|IPSec
    vpn_config: /path/to/config/file
    active: true|false
    connected: true|false
    hosts:
      - name: Host Name
        ip_address: IP Address
        host_type: Linux|Windows|etc
        description: Optional description
        services:
          - name: Service Name
            service_type: SSH|Web GUI|RDP|etc
            port: Port Number
        sub_hosts: # Optional VMs/containers
          - # Same structure as hosts
```