VPNTray/CLAUDE.md

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