153 lines
4.3 KiB
Markdown
153 lines
4.3 KiB
Markdown
# 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.
|