108 lines
2.8 KiB
Markdown
108 lines
2.8 KiB
Markdown
# wttr.in Zig Rewrite Documentation
|
|
|
|
This directory contains comprehensive documentation for rewriting wttr.in in Zig.
|
|
|
|
## 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.
|