hosts-go/memory-bank/systemPatterns.md

System Patterns: hosts-go

Architecture Overview

The hosts-go application follows a layered architecture with clear separation of concerns:

┌─────────────────────┐
│     TUI Layer       │  ← Bubble Tea models, views, styles
├─────────────────────┤
│   Business Logic    │  ← Core domain logic, validation
├─────────────────────┤
│   System Interface  │  ← File I/O, DNS, permissions
└─────────────────────┘

Key Technical Decisions

1. Bubble Tea Framework

• Why: Provides mature TUI framework with event-driven architecture
• Pattern: Model-View-Update (MVU) pattern for state management
• Components: Main model orchestrates sub-components (list, detail, modal)

2. Internal Package Structure

internal/
├── tui/      # UI layer - Bubble Tea components
├── core/     # Business logic - domain models and operations  
└── utils/    # Shared utilities - helpers and common functions

3. Permission Model

• View mode default: Read-only access, no sudo required
• Edit mode explicit: User must explicitly enter edit mode
• Sudo on demand: Only request elevated permissions when entering edit mode
• Graceful fallback: Handle permission denied gracefully

Design Patterns in Use

1. Model-View-Update (MVU)

• Model: Application state (entries, selection, mode)
• View: Rendering logic (two-pane layout, styles)
• Update: State transitions based on user input

2. Command Pattern

• Edit operations: Encapsulate modifications as commands
• Undo support: Commands can be reversed
• Validation: Commands validate before execution

3. Repository Pattern

• HostsRepository: Abstract file operations
• MockRepository: In-memory implementation for testing
• FileRepository: Actual /etc/hosts file operations

4. Observer Pattern

• DNS resolution: Background updates to IP addresses
• File watching: Detect external changes to hosts file
• Status updates: Notify UI of operation progress

Component Relationships

TUI Components

MainModel
├── ListModel (left pane)
│   ├── Entry selection
│   ├── Sorting controls
│   └── Status indicators
├── DetailModel (right pane)
│   ├── Entry editing
│   ├── Form validation
│   └── DNS resolution
└── ModalModel (overlays)
    ├── Configuration
    ├── Confirmations
    └── Error dialogs

Core Business Logic

Manager
├── HostsParser (read/write hosts file)
├── DNSResolver (hostname to IP resolution)
├── Validator (entry validation)
└── ConfigManager (user preferences)

Critical Implementation Paths

1. File Operations

// Atomic file updates with backup
1. Read current /etc/hosts → backup
2. Parse entries → validate changes
3. Write to temporary file → verify
4. Atomic move temp → /etc/hosts
5. Remove backup on success

2. State Management

// Bubble Tea update cycle
1. User input → Command
2. Command → State change
3. State change → View update
4. View update → Screen render

3. DNS Resolution

// Background IP resolution
1. Extract hostnames from entries
2. Resolve in background goroutines  
3. Compare resolved vs current IPs
4. Update UI with resolution status
5. User chooses whether to update

4. Edit Mode Transition

// Permission elevation
1. User requests edit mode
2. Check current permissions
3. Request sudo if needed
4. Validate file write access
5. Enable editing controls

Error Handling Strategy

1. Graceful Degradation

• No sudo: Continue in view-only mode
• File locked: Show warning, allow retry
• DNS failure: Show cached/manual IP options

2. Validation Layers

• Input validation: Real-time feedback on forms
• Business rules: Validate complete entries
• System constraints: Check file permissions, IP formats

3. Recovery Mechanisms

• Backup restoration: Automatic rollback on write failures
• State recovery: Restore UI state after errors
• User guidance: Clear error messages with suggested actions

Testing Architecture

1. Unit Tests

• Pure functions: Parser, validator, DNS resolver
• Mocked dependencies: File system, network calls
• Edge cases: Malformed files, network errors

2. Integration Tests

• TUI workflows: Complete user interactions
• File operations: Real file system operations (in temp dirs)
• Permission scenarios: Test sudo/non-sudo paths

3. Test Patterns

• Table-driven tests: Multiple input scenarios
• Mock interfaces: Controllable external dependencies
• Golden files: Expected output comparisons