# 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`)
- ✅ **HostsManagerApp**: Complete Textual application with reactive state management
- ✅ **Responsibilities**: User interaction, display logic, event handling, navigation
- ✅ **Dependencies**: Core models and parser for data operations
- ✅ **Implementation**: Two-pane layout with ListView and reactive updates

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

#### 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]
```

### State Management (Implemented)
- ✅ **Reactive state**: Using Textual's reactive attributes for UI updates
- ✅ **Validation pipeline**: All data validated in models and parser
- ✅ **File integrity**: Atomic operations preserve file structure
- ✅ **Error handling**: Graceful degradation for all error conditions
- 🔄 **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)
    
    def on_list_view_highlighted(self, event):
        # Automatic UI updates when selection changes
        self.selected_entry_index = event.list_view.index or 0
        self.update_entry_details()
```

### 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
```

## Critical Implementation Paths

### Application Startup (✅ Implemented)
1. ✅ **Initialize TUI**: Textual app with reactive state management
2. ✅ **Load hosts file**: Robust parsing with error handling
3. ✅ **Build UI**: Two-pane layout with ListView and details
4. ✅ **Enter main loop**: Smooth keyboard navigation and event handling
5. ✅ **Error handling**: Graceful degradation for file access issues

### Entry Navigation (✅ Implemented)
1. ✅ **Keyboard navigation**: Up/down arrows navigate entries
2. ✅ **Selection tracking**: Reactive updates to selected_entry_index
3. ✅ **Detail updates**: Automatic refresh of right pane details
4. ✅ **Position restoration**: Maintains cursor position on reload
5. ✅ **Visual feedback**: Clear indication of current selection

### File Operations (✅ Implemented)
1. ✅ **File parsing**: Comprehensive hosts file format support
2. ✅ **Comment preservation**: Maintains all comments and formatting
3. ✅ **Error handling**: Graceful handling of permission and format errors
4. ✅ **Validation**: Complete IP address and hostname validation
5. ✅ **Status feedback**: Clear user feedback for all operations

### 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
- **DNS resolution failure**: Show error but continue
- **File corruption**: Load what's possible, warn user
- **Network unavailable**: Disable DNS features

### User Feedback
- **Status bar**: Show current mode and operation status
- **Modal dialogs**: For errors requiring user attention
- **Inline validation**: Real-time feedback on input
- **Progress indicators**: For long-running operations

### Recovery Mechanisms
- **Undo operations**: Allow reverting recent changes
- **File restoration**: Restore from backup if available
- **Safe mode**: Minimal functionality if errors occur
- **Graceful exit**: Always attempt to save valid changes