wttr/zig

wttr.in Zig Rewrite Documentation

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

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.