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 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:

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