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

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

• Service: Individual services (Web GUI, SSH, RDP, etc.) on hosts
• 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 - Data management layer

• load_customers(): Returns comprehensive mock data with realistic infrastructure
• save_customers(): Placeholder for future persistence
• Isolates data loading logic from UI components

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

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() provides initial customer data with full infrastructure
2. Main window loads and filters data based on search terms
3. Widget classes create GTK components for customers, locations, and hosts
4. User interactions trigger callbacks that update dataclass attributes
5. UI re-renders to reflect state changes

UI Layout Structure

• HeaderBar with title and subtitle (GNOME HIG compliance)
• Search entry with placeholder text for filtering
• Two-column main area with independent scrolling containers
• Left column: Active locations with full infrastructure details
• Right column: Inactive locations with summary cards and activation buttons
• 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
• 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

• Replace load_customers() with real data source (database, config files, API)
• Implement actual VPN connection logic in placeholder methods
• Add persistence through save_customers() implementation
• Extend widget system for additional UI components
• Add configuration management for VPN client integration