# 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
- Basic uv project initialized with Python 3.13
- Minimal main.py with placeholder implementation
- ruff configured as dependency for code quality
- Project structure planned but not yet implemented

### Runtime Management
- **uv run hosts**: Planned command to execute the application
- **uv**: Handles all dependency management and virtual environment
- **Python 3.13**: Required minimum version for modern features

## 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 = [
    "ruff>=0.12.5",
]
```

### Planned Dependencies
- **textual**: TUI framework (to be added)
- **pytest**: Testing framework (to be added)
- **ipaddress**: Built-in Python module for IP validation
- **socket**: Built-in Python module for DNS resolution

## Tool Usage Patterns

### Development Workflow
1. **uv run**: Execute the application during development
2. **ruff check**: Lint code for style and potential issues
3. **ruff format**: Auto-format code to maintain consistency
4. **pytest**: Run test suite for validation
5. **uv add**: Add new dependencies as needed

### Code Quality
- **ruff configuration**: Enforce consistent Python style
- **Type hints**: Use modern Python typing for better code clarity
- **Docstrings**: Document all public APIs and complex logic
- **Test coverage**: Aim for high coverage on core business logic

## 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
- **Unit tests**: Test core logic in isolation
- **Integration tests**: Test TUI components with mocked file system
- **Snapshot testing**: Verify TUI rendering consistency
- **Mock external dependencies**: DNS resolution and file I/O