# Technical Context: hosts

## Technologies Used

### Core Technologies
- **Python 3.13+**: Modern Python with latest features and performance improvements
- **Textual**: Rich TUI framework for building terminal applications with modern UI components
- **uv**: Fast Python package manager and runtime for dependency management and execution

### Development Tools
- **ruff**: Lightning-fast Python linter and formatter for code quality
- **pytest**: Testing framework for comprehensive test coverage
- **textual.testing**: Built-in testing utilities for TUI components

## Development Setup

### Project Structure
```
hosts/
├── pyproject.toml          # uv-managed project configuration
├── README.md
├── main.py                 # Current entry point (temporary)
├── src/hosts/              # Main package (planned)
│   ├── __init__.py
│   ├── main.py            # Application entry point
│   ├── tui/               # UI components
│   ├── core/              # Business logic
│   └── utils.py
└── tests/                 # Test suite
```

### Current State
- ✅ **Complete uv project**: Python 3.13 with full dependency management
- ✅ **Production application**: Fully functional TUI with advanced features and professional interface
- ✅ **Perfect code quality**: All ruff checks passing with zero issues
- ✅ **Proper project structure**: Well-organized src/hosts/ package with core and tui modules
- ✅ **Comprehensive testing**: 97 tests covering all functionality including new features
- ✅ **Entry point configured**: `hosts` command launches application perfectly
- ✅ **Configuration system**: Complete settings management with JSON persistence
- ✅ **Modal interface**: Professional configuration dialogs with keyboard bindings
- ✅ **Advanced features**: Sorting, filtering, and rich visual interface

### Runtime Management
- ✅ **uv run hosts**: Command executes application instantly
- ✅ **uv**: Handles all dependency management and virtual environment flawlessly
- ✅ **Python 3.13**: Modern features working excellently throughout codebase
- ✅ **Development workflow**: Smooth uv-based development experience

## Technical Constraints

### System Integration
- **Root access required**: Must handle `/etc/hosts` file modifications
- **Sudo permission management**: Request permissions only in edit mode
- **File integrity**: Must preserve existing hosts file structure and comments
- **Cross-platform compatibility**: Focus on Unix-like systems (Linux, macOS)

### Performance Requirements
- **Fast startup**: TUI should load quickly even with large hosts files
- **Responsive UI**: No blocking operations in the main UI thread
- **Memory efficient**: Handle large hosts files without excessive memory usage

### Security Considerations
- **Privilege escalation**: Only request sudo when entering edit mode
- **Input validation**: Validate all IP addresses and hostnames before writing
- **Backup strategy**: Consider creating backups before modifications
- **Permission dropping**: Release sudo permissions when exiting edit mode

## Dependencies

### Current Dependencies
```toml
[project]
requires-python = ">=3.13"
dependencies = [
    "textual>=5.0.1",
    "pytest>=8.4.1",
    "ruff>=0.12.5",
]

[project.scripts]
hosts = "hosts.main:main"
```

### Production Dependencies
- ✅ **textual**: Rich TUI framework providing excellent reactive UI components, DataTable, and modal system
- ✅ **pytest**: Comprehensive testing framework with 97 passing tests
- ✅ **ruff**: Lightning-fast linter and formatter with perfect compliance
- ✅ **ipaddress**: Built-in Python module for robust IP validation and sorting
- ✅ **json**: Built-in Python module for configuration persistence
- ✅ **pathlib**: Built-in Python module for cross-platform path handling
- ✅ **socket**: Built-in Python module for DNS resolution (planned for Phase 5)

## Tool Usage Patterns

### Development Workflow
1. ✅ **uv run hosts**: Execute the application - launches instantly
2. ✅ **uv run ruff check**: Lint code - all checks passing perfectly
3. ✅ **uv run ruff format**: Auto-format code - consistent style maintained
4. ✅ **uv run pytest**: Run test suite - 42 tests passing with 100% success rate
5. ✅ **uv add**: Add dependencies - seamless dependency management

### Code Quality Achieved
- ✅ **ruff configuration**: Perfect compliance with zero issues across all modules
- ✅ **Type hints**: Complete type coverage throughout entire codebase including new components
- ✅ **Docstrings**: Comprehensive documentation for all public APIs and classes
- ✅ **Test coverage**: Excellent coverage on all core business logic and new features (97 tests)
- ✅ **Architecture**: Clean separation of concerns with extensible and maintainable structure
- ✅ **Configuration management**: Robust JSON handling with proper error recovery
- ✅ **Modal system**: Professional dialog implementation with proper lifecycle management

## Architecture Decisions

### Separation of Concerns
- **TUI layer**: Handle user interface and input/output
- **Core layer**: Business logic for hosts file management
- **Utils layer**: Shared utilities and helper functions

### Error Handling
- **Graceful degradation**: Handle missing permissions or file access issues
- **User feedback**: Clear error messages in the TUI
- **Recovery mechanisms**: Allow users to retry failed operations

### Testing Strategy Implemented
- ✅ **Unit tests**: 97 comprehensive tests covering all core logic and new features
- ✅ **Integration tests**: TUI components tested with mocked file system and configuration
- ✅ **Edge case testing**: Comprehensive coverage of parsing, configuration, and modal edge cases
- ✅ **Mock external dependencies**: File I/O, system operations, and configuration properly mocked
- ✅ **Test fixtures**: Realistic hosts file samples and configuration scenarios for thorough testing
- ✅ **Configuration testing**: Complete coverage of JSON persistence, error handling, and defaults
- ✅ **Modal testing**: Comprehensive testing of dialog lifecycle and user interactions
- 🔄 **Snapshot testing**: Planned for Phase 4 TUI visual regression testing
- 🔄 **Performance testing**: Planned for Phase 3 large file optimization