hosts/memory-bank/systemPatterns.md

# System Patterns: hosts

## System Architecture

### Layered Architecture
```
┌─────────────────────────────────────┐
│             TUI Layer               │  ← User Interface (Textual)
├─────────────────────────────────────┤
│           Manager Layer             │  ← Orchestration & Operations
├─────────────────────────────────────┤
│            Core Layer               │  ← Business Logic
├─────────────────────────────────────┤
│           System Layer              │  ← File I/O & DNS
└─────────────────────────────────────┘
```

### Component Relationships

#### TUI Layer (`src/hosts/main.py` and `src/hosts/tui/`)
- ✅ **HostsManagerApp**: Complete Textual application with reactive state management and DataTable interface
- ✅ **ConfigModal**: Professional modal dialog for configuration management
- ✅ **Responsibilities**: User interaction, display logic, event handling, navigation, configuration UI
- ✅ **Dependencies**: Core models, parser, and config for data operations
- ✅ **Implementation**: Two-pane layout with DataTable, modal system, and rich visual styling

#### Core Layer (`src/hosts/core/`)
- ✅ **models.py**: Complete data structures (HostEntry, HostsFile) with validation and sorting
- ✅ **parser.py**: Robust hosts file parsing, serialization, and file operations
- ✅ **config.py**: Configuration management with JSON persistence and default handling
- ✅ **Responsibilities**: Pure business logic, data validation, file integrity, settings management
- ✅ **Implementation**: Comprehensive validation, error handling, and configuration persistence

#### System Layer (Implemented)
- ✅ **File I/O**: Atomic file operations with backup support
- ✅ **Permission checking**: Validation of file access permissions
- 🔄 **DNS Resolution**: Planned for Phase 5 advanced features
- 🔄 **Permission Management**: Sudo handling planned for Phase 3 edit mode

## Key Technical Decisions

### Data Model Design (Implemented)
```python
@dataclass
class HostEntry:
    ip_address: str
    hostnames: list[str]
    comment: str | None = None
    is_active: bool = True
    dns_name: str | None = None  # For CNAME-like functionality
    
    # Implemented methods:
    def to_hosts_line(self) -> str
    @classmethod
    def from_hosts_line(cls, line: str) -> "HostEntry | None"
    def __post_init__(self) -> None  # Validation
    
@dataclass
class HostsFile:
    entries: list[HostEntry] = field(default_factory=list)
    header_comments: list[str] = field(default_factory=list)
    footer_comments: list[str] = field(default_factory=list)
    
    # Implemented methods:
    def add_entry(self, entry: HostEntry) -> None
    def remove_entry(self, index: int) -> None
    def toggle_entry(self, index: int) -> None
    def get_active_entries(self) -> list[HostEntry]
    def get_inactive_entries(self) -> list[HostEntry]
    def sort_by_ip(self) -> None
    def sort_by_hostname(self) -> None
    def find_entries_by_hostname(self, hostname: str) -> list[HostEntry]
    def find_entries_by_ip(self, ip: str) -> list[HostEntry]

# Configuration Management (Implemented)
class Config:
    def __init__(self):
        self.config_dir = Path.home() / ".config" / "hosts-manager"
        self.config_file = self.config_dir / "config.json"
        self._settings = self._load_default_settings()
    
    # Implemented methods:
    def load(self) -> None
    def save(self) -> None
    def get(self, key: str, default: Any = None) -> Any
    def set(self, key: str, value: Any) -> None
    def is_default_entry(self, ip_address: str, hostname: str) -> bool
    def should_show_default_entries(self) -> bool
    def toggle_show_default_entries(self) -> None
```

### State Management (Implemented)
- ✅ **Reactive state**: Using Textual's reactive attributes for complex UI updates
- ✅ **Configuration state**: Persistent settings with JSON storage and graceful error handling
- ✅ **Sorting state**: Reactive sort column and direction with visual indicators
- ✅ **Validation pipeline**: All data validated in models, parser, and configuration
- ✅ **File integrity**: Atomic operations preserve file structure
- ✅ **Error handling**: Graceful degradation for all error conditions
- ✅ **Modal state**: Professional modal dialog lifecycle management
- 🔄 **Undo/Redo capability**: Planned for Phase 4 with command pattern
- 🔄 **Dirty state tracking**: Will be implemented in Phase 3 edit mode

### Permission Model (Planned for Phase 3)
```python
# Current implementation (read-only mode)
class HostsManagerApp:
    edit_mode: reactive[bool] = reactive(False)  # Always False in Phase 1
    
    def update_status(self):
        mode = "Edit mode" if self.edit_mode else "Read-only mode"
        # Status bar shows current mode

# Planned for Phase 3:
class PermissionManager:
    def __init__(self):
        self.edit_mode = False
        self.sudo_acquired = False
    
    def enter_edit_mode(self) -> bool:
        # Request sudo permissions
        # Set edit_mode = True only if successful
    
    def exit_edit_mode(self):
        # Release sudo permissions
        # Set edit_mode = False
```

## Design Patterns in Use

### Reactive Pattern (Implemented)
```python
class HostsManagerApp(App):
    # Reactive attributes automatically update UI
    hosts_file: reactive[HostsFile] = reactive(HostsFile())
    selected_entry_index: reactive[int] = reactive(0)
    edit_mode: reactive[bool] = reactive(False)
    sort_column: reactive[str] = reactive("")  # "ip" or "hostname"
    sort_ascending: reactive[bool] = reactive(True)
    
    def on_data_table_row_highlighted(self, event):
        # Automatic UI updates when selection changes
        self.selected_entry_index = event.cursor_row
        self.update_entry_details()
    
    def on_data_table_header_selected(self, event):
        # Interactive column sorting
        if "IP Address" in str(event.column_key):
            self.action_sort_by_ip()
        elif "Canonical Hostname" in str(event.column_key):
            self.action_sort_by_hostname()
```

### Data Validation Pattern (Implemented)
```python
@dataclass
class HostEntry:
    def __post_init__(self):
        # Comprehensive validation on creation
        if not self.ip_address or not self.hostnames:
            raise ValueError("IP address and hostnames required")
        
        # Validate IP address format
        try:
            ipaddress.ip_address(self.ip_address)
        except ValueError as e:
            raise ValueError(f"Invalid IP address: {e}")
```

### Command Pattern (Planned for Phase 4)
```python
# Will be implemented for undo/redo functionality
class Command(ABC):
    @abstractmethod
    def execute(self) -> HostsFile:
        pass
    
    @abstractmethod
    def undo(self) -> HostsFile:
        pass
```

### Factory Pattern (Implemented)
```python
class HostsParser:
    def __init__(self, file_path: str = "/etc/hosts"):
        # Single parser handles all hosts file formats
        self.file_path = file_path

# Configuration Factory Pattern (Implemented)
class Config:
    def _load_default_settings(self) -> Dict[str, Any]:
        # Factory method for default configuration
        return {
            "show_default_entries": False,
            "default_entries": [
                {"ip": "127.0.0.1", "hostname": "localhost"},
                {"ip": "255.255.255.255", "hostname": "broadcasthost"},
                {"ip": "::1", "hostname": "localhost"},
            ],
            "window_settings": {
                "last_sort_column": "",
                "last_sort_ascending": True,
            }
        }
```

### Modal Pattern (Implemented)
```python
class ConfigModal(ModalScreen):
    def __init__(self, config: Config):
        super().__init__()
        self.config = config
    
    def action_save(self) -> None:
        # Save configuration and close modal
        checkbox = self.query_one("#show-defaults-checkbox", Checkbox)
        self.config.set("show_default_entries", checkbox.value)
        self.config.save()
        self.dismiss(True)
    
    def action_cancel(self) -> None:
        # Cancel changes and close modal
        self.dismiss(False)
```

## Critical Implementation Paths

### Application Startup (✅ Implemented)
1. ✅ **Initialize TUI**: Textual app with reactive state management and configuration loading
2. ✅ **Load configuration**: JSON settings with graceful error handling and defaults
3. ✅ **Load hosts file**: Robust parsing with error handling and filtering
4. ✅ **Build UI**: Two-pane layout with DataTable, details, and modal system
5. ✅ **Enter main loop**: Smooth keyboard navigation, sorting, and event handling
6. ✅ **Error handling**: Graceful degradation for file access and configuration issues

### Entry Navigation (✅ Implemented)
1. ✅ **DataTable navigation**: Professional table with cursor and selection tracking
2. ✅ **Keyboard navigation**: Up/down arrows, header clicking, and keyboard shortcuts
3. ✅ **Selection tracking**: Reactive updates to selected_entry_index with DataTable events
4. ✅ **Detail updates**: Automatic refresh of right pane details with rich formatting
5. ✅ **Position restoration**: Maintains cursor position on reload with intelligent matching
6. ✅ **Visual feedback**: Color-coded entries with clear active/inactive indication

### File Operations (✅ Implemented)
1. ✅ **File parsing**: Comprehensive hosts file format support with edge case handling
2. ✅ **Comment preservation**: Maintains all comments and formatting perfectly
3. ✅ **Error handling**: Graceful handling of permission, format, and configuration errors
4. ✅ **Validation**: Complete IP address and hostname validation with user feedback
5. ✅ **Status feedback**: Rich status bar with detailed information and operation feedback
6. ✅ **Configuration integration**: Settings-aware parsing and display

### Configuration Management (✅ Implemented)
1. ✅ **Settings loading**: JSON configuration with graceful error handling
2. ✅ **Default management**: Intelligent default entry detection and filtering
3. ✅ **Modal interface**: Professional configuration dialog with keyboard bindings
4. ✅ **Persistence**: Automatic saving to ~/.config/hosts-manager/ directory
5. ✅ **Live updates**: Immediate application of configuration changes
6. ✅ **Error recovery**: Fallback to defaults on configuration errors

### Sorting and Filtering (✅ Implemented)
1. ✅ **Interactive sorting**: Click column headers to sort by IP or hostname
2. ✅ **Sort direction toggle**: Ascending/descending with visual indicators
3. ✅ **Keyboard shortcuts**: Sort by IP (i) and hostname (n) keys
4. ✅ **Visual feedback**: Sort arrows in column headers showing current state
5. ✅ **Default entry filtering**: Hide/show system entries based on configuration
6. ✅ **Intelligent IP sorting**: Proper IPv4/IPv6 numerical sorting

### Edit Mode Activation (🔄 Planned for Phase 3)
1. 🔄 **User triggers edit mode**: Keyboard shortcut implementation
2. 🔄 **Request sudo**: Secure password prompt
3. 🔄 **Validate permissions**: Ensure write access to `/etc/hosts`
4. 🔄 **Update UI state**: Enable edit operations and visual indicators
5. 🔄 **Maintain permissions**: Keep sudo active until explicit exit

### Entry Modification (🔄 Planned for Phase 3-4)
1. 🔄 **User action**: Toggle, reorder, or edit entry operations
2. 🔄 **Create command**: Command pattern for undo/redo support
3. 🔄 **Validate operation**: Real-time validation of changes
4. 🔄 **Execute command**: Apply changes to in-memory state
5. 🔄 **Update UI**: Immediate visual feedback
6. 🔄 **Track dirty state**: Mark file as needing save

### File Persistence (🔄 Planned for Phase 3)
1. 🔄 **User saves**: Explicit save command or auto-save option
2. 🔄 **Validate entire file**: Comprehensive syntax checking
3. 🔄 **Create backup**: Automatic backup before modifications
4. 🔄 **Write atomically**: Safe temporary file + rename operation
5. 🔄 **Verify write**: Confirm successful file write

### DNS Resolution Flow (🔄 Planned for Phase 5)
1. 🔄 **User requests resolution**: For entries with DNS names
2. 🔄 **Resolve hostname**: Async DNS resolution
3. 🔄 **Compare IPs**: Current IP vs resolved IP comparison
4. 🔄 **Present choice**: User dialog for IP selection
5. 🔄 **Update entry**: Apply user's choice with validation
6. 🔄 **Mark dirty**: Flag file for saving

## Error Handling Patterns

### Graceful Degradation
- **Permission denied**: Fall back to read-only mode with clear status indication
- **Configuration errors**: Use defaults and continue with warning
- **File corruption**: Load what's possible, warn user, maintain functionality
- **DNS resolution failure**: Show error but continue (planned for Phase 5)
- **Network unavailable**: Disable DNS features (planned for Phase 5)

### User Feedback
- **Rich status bar**: Show current mode, entry counts, file path, and operation status
- **Modal dialogs**: Professional configuration interface with proper keyboard handling
- **Color-coded entries**: Visual distinction between active/inactive entries
- **Sort indicators**: Visual arrows showing current sort column and direction
- **Interactive headers**: Click feedback and hover states for column sorting
- **Progress indicators**: For long-running operations (planned for Phase 3)

### Recovery Mechanisms
- **Configuration fallback**: Automatic fallback to defaults on configuration errors
- **Position restoration**: Intelligent cursor position maintenance on reload
- **Error isolation**: Configuration errors don't affect core functionality
- **Undo operations**: Allow reverting recent changes (planned for Phase 4)
- **File restoration**: Restore from backup if available (planned for Phase 3)
- **Safe mode**: Minimal functionality if errors occur
- **Graceful exit**: Always attempt to save valid changes and configuration