160 lines
7.4 KiB
Markdown
160 lines
7.4 KiB
Markdown
# 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
|
|
``` |