79 lines
3.5 KiB
Markdown
79 lines
3.5 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
|
|
|
|
## Code Architecture
|
|
|
|
### Core Components
|
|
|
|
**main.py** - Main GUI application entry point
|
|
- `VPNManagerWindow` class: Primary tkinter-based GUI application
|
|
- Implements a two-column layout: active customers (left) vs inactive customers (right)
|
|
- Features system tray integration using `pystray`
|
|
- Uses a modern dark theme with predefined color scheme
|
|
- Includes search functionality across customers, locations, and hosts
|
|
|
|
**models.py** - Data model definitions using dataclasses
|
|
- `Host`: Individual services/endpoints (SSH, Web, SMB, etc.)
|
|
- `Location`: Customer locations (headquarters, branch offices) with VPN configurations
|
|
- `Customer`: Top-level entities containing multiple locations
|
|
- Each model includes helper methods for common operations
|
|
|
|
**data_loader.py** - Data management layer
|
|
- `load_customers()`: Currently returns mock data, designed to be replaceable
|
|
- `save_customers()`: Placeholder for future persistence
|
|
- Isolates data loading logic from UI components
|
|
|
|
### Key Architecture Patterns
|
|
|
|
**Hierarchical Data Structure**: Customer → Location → Host
|
|
- Customers can have multiple locations (e.g., headquarters, branches)
|
|
- Each location has its own VPN configuration and connection state
|
|
- Locations contain multiple hosts/services that become accessible when VPN is connected
|
|
|
|
**Active/Inactive Location Management**:
|
|
- Locations (not customers) are activated/deactivated individually
|
|
- Left column shows customers with at least one active location (displaying only their active locations)
|
|
- Right column shows customers with at least one inactive location (displaying only their inactive locations)
|
|
- UI automatically reorganizes based on location activation state
|
|
|
|
**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
|
|
|
|
### Data Flow
|
|
1. `data_loader.load_customers()` provides initial customer data
|
|
2. Main window loads and filters data based on search terms
|
|
3. UI renders two-column layout based on location active states
|
|
4. User interactions update dataclass attributes directly
|
|
5. UI re-renders to reflect state changes
|
|
|
|
### UI Layout Structure
|
|
- Header: Search bar and application title
|
|
- Two-column main area with independent scrolling
|
|
- Left column shows full location details with hosts for active locations
|
|
- Right column shows summary cards with activation buttons for inactive locations
|
|
- System tray integration for minimize-to-tray behavior
|
|
|
|
### 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 |