gmarth/VPNTray
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

stuff

Browse Source
This commit is contained in:
Alexander Thiess
2025-09-06 16:54:45 +02:00
parent a4bf07a3b6
commit d918f1e497
8 changed files with 1157 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

224
CLAUDE.md
View File

@@ -32,129 +32,229 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
**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)
- 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 search functionality across customers, locations, and hosts
- Includes advanced search functionality with wildcard support (`*`)
- HeaderBar for native GNOME look and feel
- Current location tracking and display
**models.py** - Data model definitions using dataclasses and enums
**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
- `Host`: Physical/virtual machines with services and sub-hosts (VMs)
- `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 helper methods for common operations
- 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
- `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 and error handling
- 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
**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
- `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 locations
- 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) and multiple services
- Services represent endpoints (SSH, Web GUI, RDP, etc.) that can be launched
- Hosts can have sub-hosts (VMs under hypervisors) with recursive nesting
- Services represent endpoints (SSH, Web GUI, RDP, etc.) with specific ports
**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
**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
**Widget-Based UI Architecture**:
- Modular widget classes handle their own GTK widget creation
**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
- Clean separation between data models and UI representation
- Clear separation between data models and UI representation
- Different widget behavior for active vs inactive states
**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
**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. `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
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)
- Search entry with placeholder text for filtering (supports `*` wildcard)
- Current location display (centered, prominent)
- Search entry with comprehensive placeholder text (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
- **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 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.)
- **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
connected: true|false
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|etc
host_type: Linux|Windows|Windows Server|Proxmox|ESXi|Router|Switch
description: Optional description
services:
- name: Service Name
service_type: SSH|Web GUI|RDP|etc
service_type: SSH|Web GUI|RDP|VNC|SMB|Database|FTP
port: Port Number
sub_hosts: # Optional VMs/containers
- # Same structure as hosts
```
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