# wttr.in Zig Rewrite Documentation

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

## 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
- 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

### 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

### [TARGET_ARCHITECTURE.md](TARGET_ARCHITECTURE.md) ⭐ NEW
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.