# 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