wttr/README.md

# wttr.in Zig Rewrite Documentation

This directory contains comprehensive documentation for rewriting wttr.in in Zig.

## Quick Start

```bash
# Minimal setup (uses defaults)
./wttr

# With IP2Location fallback (optional)
IP2LOCATION_API_KEY=your_key_here ./wttr

# Custom cache location
WTTR_CACHE_DIR=/var/cache/wttr ./wttr
```

See [CACHE_CONFIGURATION.md](CACHE_CONFIGURATION.md) for detailed configuration options.

## External Services & API Keys

### Required Services (No API Key)
- **Met.no Weather API** - Primary weather data provider
  - Free, open API from Norwegian Meteorological Institute
  - No registration required
  - Rate limit: Be respectful, use caching (built-in)

### Optional Services
- **IP2Location.io** - Fallback IP geolocation
  - **API Key Required:** Sign up at https://www.ip2location.io/
  - Free tier: 30,000 requests/month
  - Only used when MaxMind GeoIP database lookup fails
  - Set via `IP2LOCATION_API_KEY` environment variable

### Database Files (Auto-Downloaded)
- **MaxMind GeoLite2 City** - IP geolocation database
  - Free database, automatically downloaded if missing
  - No API key required
  - Stored in `~/.cache/wttr/GeoLite2-City.mmdb` by default

## Current Implementation Status

### Implemented Features
- HTTP server with routing and middleware
- Rate limiting
- Caching system
- GeoIP database integration (libmaxminddb)
- Location resolver with multiple input types
- Weather provider (Met.no) with timezone-aware forecasts; core data structures use zeit.Time/zeit.Date for type-safe date/time handling
- Output formats: ANSI, line (1-4), JSON (j1), v2 data-rich, custom (%)
- Query parameter parsing
- Static help pages (/:help, /:translation)
- Error handling (404/500 status codes)
- Configuration from environment variables
- **Imperial units auto-detection**: Automatically uses imperial units (°F, mph) for US IP addresses and `lang=us`, with explicit `?u` and `?m` overrides
- **IP2Location fallback**: Optional fallback geolocation service with persistent cache

### Missing Features (To Be Implemented Later)

1. **Prometheus Metrics Format** (format=p1)
   - Export weather data in Prometheus metrics format
   - See API_ENDPOINTS.md for format specification

2. **PNG Generation**
   - Render weather reports as PNG images
   - Support transparency and custom styling
   - Requires image rendering library integration

3. **Multiple Locations Support**
   - Handle colon-separated locations (e.g., `London:Paris:Berlin`)
   - Process and display weather for multiple cities in one request

4. **Language/Localization**
   - Accept-Language header parsing
   - lang query parameter support
   - Translation of weather conditions and text (54 languages)

5. **Moon Phase Calculation**
   - Real moon phase computation based on date
   - Moon phase emoji display
   - Moonday calculation

6. **Astronomical Times**
   - Calculate dawn, sunrise, zenith, sunset, dusk times
   - Based on location coordinates and timezone
   - Display in custom format output

## Documentation Files

### [CACHE_CONFIGURATION.md](CACHE_CONFIGURATION.md) ⭐ NEW
Complete cache and external services documentation:
- External services (Met.no, IP2Location, MaxMind GeoLite2)
- API key requirements
- Cache locations and policies
- Expiration and eviction strategies
- Environment variables
- Configuration examples

### [TARGET_ARCHITECTURE.md](TARGET_ARCHITECTURE.md)
Target architecture for Zig rewrite:
- Single binary design
- Simplified caching (one layer)
- Pluggable weather provider interface
- Rate limiting middleware
- Module structure
- Testing strategy
- Performance targets

### [ARCHITECTURE.md](ARCHITECTURE.md)
Current system architecture documentation:
- Component breakdown (Go proxy, Python backend, static assets)
- Request flow diagrams
- API endpoints
- External dependencies
- Caching strategy
- Configuration
- Known issues

### [API_ENDPOINTS.md](API_ENDPOINTS.md)
Complete API reference:
- All endpoints with examples
- Query parameters
- Output formats
- Language support
- HTTP headers
- Rate limits
- Usage examples

### [DATA_FLOW.md](DATA_FLOW.md)
Detailed request processing flow:
- Step-by-step request handling
- Location resolution process
- Weather data fetching
- Rendering pipeline
- Caching mechanisms
- Error handling
- Performance optimizations

### [REWRITE_STRATEGY.md](REWRITE_STRATEGY.md)
Comprehensive rewrite plan:
- Goals and non-goals
- Phase-by-phase breakdown (10-11 weeks)
- Module organization
- Testing strategy
- Risk mitigation
- Success criteria
- Alternative approaches

## Quick Start

1. **Read ARCHITECTURE.md** - Understand the current system
2. **Read DATA_FLOW.md** - Understand how requests are processed
3. **Read REWRITE_STRATEGY.md** - Understand the rewrite plan
4. **Refer to API_ENDPOINTS.md** - When implementing specific endpoints

## Current System Summary

**Architecture:** Hybrid Python/Go
- Go proxy (port 8082): LRU caching, prefetching
- Python backend (port 8002): Weather logic, rendering
- External binaries: wego (Go), pyphoon (Python)
- External services: Geolocator (port 8004)

**Key Stats:**
- ~5000 lines of Python
- ~400 lines of Go
- 54 languages supported
- 12,800 entry LRU cache
- 1000-2000s cache TTL
- Zero unit tests (only integration tests)

**Main Challenges:**
1. ANSI weather rendering (currently done by wego)
2. PNG image generation (PIL + pyte)
3. GeoIP database parsing (MaxMind format)
4. 54 language translations
5. Multiple output formats (ANSI, HTML, PNG, JSON, Prometheus)

## Recommended Approach

**Option A: Incremental (Recommended)**
1. Replace Go proxy with Zig (2 weeks)
2. Test and deploy
3. Replace Python backend with Zig (8-9 weeks)
4. Full cutover

**Option B: Full Rewrite**
- All at once (10-11 weeks)
- Higher risk, but cleaner result

## Next Steps

1. Review documentation
2. Choose rewrite strategy
3. Set up Zig project structure
4. Begin implementation (start with HTTP server or Go proxy)

## Questions?

See REWRITE_STRATEGY.md "Questions to Answer" section for key decisions needed.