# Technical Context: hosts-go

## Technologies Used

### Core Language & Runtime
- **Go 1.21+**: Primary development language
- **Go Modules**: Dependency management (`go.mod`, `go.sum`)

### TUI Framework Stack
- **[Bubble Tea](https://github.com/charmbracelet/bubbletea)**: Core TUI framework
  - Event-driven architecture
  - Model-View-Update pattern
  - Cross-platform terminal support
- **[Bubbles](https://github.com/charmbracelet/bubbles)**: Pre-built components
  - Text inputs, viewports, spinners
  - List components, progress bars
  - Standardized interaction patterns
- **[Lip Gloss](https://github.com/charmbracelet/lipgloss)**: Styling and layout
  - CSS-like styling for terminal
  - Colors, borders, padding, margins
  - Responsive layout capabilities
- **[bubblezone](https://github.com/lrstanley/bubblezone)**: Mouse event handling
  - Click detection for TUI components
  - Mouse wheel support
  - Touch-friendly interactions

### Development Tools
- **golangci-lint**: Static analysis and linting
- **Go testing**: Built-in testing framework
- **testify**: Enhanced assertions and mocks
- **Go race detector**: Concurrency testing
- **Go build**: Cross-platform compilation

## Development Setup

### Prerequisites
```bash
# Go installation (1.21+)
go version

# Development tools
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```

### Project Initialization
```bash
# Initialize Go module
go mod init hosts-go

# Add core dependencies
go get github.com/charmbracelet/bubbletea@latest
go get github.com/charmbracelet/bubbles@latest
go get github.com/charmbracelet/lipgloss@latest
go get github.com/lrstanley/bubblezone@latest

# Testing dependencies
go get github.com/stretchr/testify@latest
```

### Build & Run
```bash
# Development run
go run ./cmd/hosts

# Build binary
go build -o hosts ./cmd/hosts

# Cross-platform builds
GOOS=linux GOARCH=amd64 go build -o hosts-linux ./cmd/hosts
GOOS=windows GOARCH=amd64 go build -o hosts.exe ./cmd/hosts
GOOS=darwin GOARCH=amd64 go build -o hosts-darwin ./cmd/hosts
```

## Technical Constraints

### System Requirements
- **Unix-like systems**: macOS, Linux (primary targets)
- **Terminal support**: 256+ colors, UTF-8 encoding
- **File permissions**: `/etc/hosts` read access (view mode)
- **Elevated permissions**: sudo access (edit mode)

### Performance Constraints
- **Memory**: Minimal footprint for terminal application
- **Startup time**: < 100ms launch time
- **File size**: Support hosts files up to 10MB
- **Responsiveness**: < 16ms UI update cycles

### Security Constraints
- **Privilege escalation**: Only when explicitly requested
- **File validation**: Prevent hosts file corruption
- **Input sanitization**: Validate all hostname/IP inputs
- **Backup strategy**: Atomic updates with rollback capability

## Dependencies

### Runtime Dependencies
```go
// Core TUI framework
github.com/charmbracelet/bubbletea v0.25.0
github.com/charmbracelet/bubbles v0.17.1
github.com/charmbracelet/lipgloss v0.9.1
github.com/lrstanley/bubblezone v0.0.0-20231228141418-c04f8a77c893

// Standard library usage
net          // DNS resolution, IP validation
os           // File operations, environment
os/exec      // Sudo command execution
path/filepath // Path manipulation
strings      // Text processing
regex        // Pattern matching
```

### Development Dependencies
```go
// Testing framework
github.com/stretchr/testify v1.8.4

// Optional: Enhanced development
github.com/golangci/golangci-lint // Linting
github.com/air-verse/air         // Live reload (dev only)
```

## Tool Usage Patterns

### Testing Workflow
```bash
# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific test package
go test ./internal/core

# Run tests with race detection
go test -race ./...

# Benchmark tests
go test -bench=. ./...
```

### Linting & Quality
```bash
# Run linter
golangci-lint run

# Format code
go fmt ./...

# Vet code
go vet ./...

# Check dependencies
go mod tidy
go mod verify
```

### Development Workflow
```bash
# Live reload during development
air

# Build and test
go build ./... && go test ./...

# Install locally
go install ./cmd/hosts
```

## Platform-Specific Considerations

### macOS
- **Hosts file location**: `/etc/hosts`
- **Permission model**: sudo required for editing
- **Terminal compatibility**: Terminal.app, iTerm2

### Linux
- **Hosts file location**: `/etc/hosts`
- **Permission model**: sudo/root required for editing
- **Terminal compatibility**: GNOME Terminal, Konsole, xterm

### Windows (Future)
- **Hosts file location**: `C:\Windows\System32\drivers\etc\hosts`
- **Permission model**: Administrator elevation required
- **Terminal compatibility**: Windows Terminal, Command Prompt

## Performance Optimizations

### Memory Management
- **Lazy loading**: Only load visible entries in large files
- **String interning**: Reuse common hostname strings
- **Garbage collection**: Minimize allocations in render loop

### UI Responsiveness
- **Background processing**: DNS resolution in goroutines
- **Debounced updates**: Batch rapid state changes
- **Efficient rendering**: Only update changed UI components

### File Operations
- **Streaming parser**: Handle large files without full memory load
- **Atomic writes**: Prevent corruption during updates
- **Change detection**: Only write when modifications exist

## Debugging & Profiling

### Debug Build
```bash
# Build with debug symbols
go build -gcflags="all=-N -l" ./cmd/hosts

# Run with debug logging
DEBUG=1 ./hosts
```

### Profiling
```bash
# CPU profiling
go test -cpuprofile=cpu.prof -bench=.

# Memory profiling  
go test -memprofile=mem.prof -bench=.

# Analyze profiles
go tool pprof cpu.prof
```

### Common Debug Patterns
- **TUI debugging**: Log to file instead of stdout
- **State inspection**: JSON marshal model state
- **Event tracing**: Log all Bubble Tea messages