107 lines
5.0 KiB
Markdown
107 lines
5.0 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
|
|
|
|
## 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 |