wttr.in Zig Rewrite Documentation

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

Quick Start

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