wttr/README.md

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

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

7. Online GeoIP Fallback

   • When local GeoIP database lookup fails, fallback to online service
   • Requires API key configuration
   • Persistent cache for online lookup results
   • Legacy system uses ip2location or similar service

Documentation Files

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

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

Complete API reference:

• All endpoints with examples
• Query parameters
• Output formats
• Language support
• HTTP headers
• Rate limits
• Usage examples

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

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.