Core functionality stable | UI actively evolving | Live Demo
Self-hostable weather dashboard with AI-powered insights, 10-year climate analysis, and interactive radar maps.
Built by Michael Buckingham | Inspired by Weather Spark
Coming Soon - Full UI/UX redesign and refactor in progress.
Check out the live demo to see the current interface in action!
- 🤖 AI-First Interface - Ask weather questions in plain English ("Will it rain this weekend?")
- 📊 Deep Climate Analysis - Compare cities with 10 years of historical data
- 🌧️ Real-Time Radar - Interactive precipitation maps with 2-hour history
- ♿ Accessible to All - WCAG 2.1 Level AA compliant, full screen reader support
- 📚 Production-Grade Code - Learn from real-world React + Node.js patterns
- 🔐 Security First - 9.4/10 score, 0 vulnerabilities, automated scanning
- 🧪 Well-Tested - 476/476 tests passing, comprehensive coverage
- 📖 Comprehensive Docs - 80+ organized guides covering everything
- 🐳 Docker One-Command - Get running in 3 minutes
- 💰 Free to Run - $0/month with free API tiers (1,000 requests/day)
- 📉 Minimal Resources - Runs on $6/month VPS (2GB RAM, 1 CPU)
- 🔒 Your Data - No telemetry, no tracking, full control
Get up and running in 3 minutes with Docker:
# 1. Clone the repository
git clone https://github.com/mbuckingham74/meteo-weather.git
cd meteo-weather
# 2. Copy environment file and add your API keys
cp .env.example .env
# Edit .env - Add your FREE Visual Crossing API key
# 3. Start the application
docker-compose up
# 4. Open in browser
# Frontend: http://localhost:3000
# Backend API: http://localhost:5001That's it! The app starts with pre-populated data for 148 cities.
- Visual Crossing (required) - Sign up here - 1,000 records/day free
- OpenWeather (required for radar) - Sign up here - 1,000 calls/day free
- Anthropic Claude (optional, AI features) - Sign up here - Pay-as-you-go (~$0.01/query)
No API keys yet? The app works out of the box with cached data for major cities!
- 🌤️ Multi-day forecasts - 3, 7, or 14-day forecasts with hourly breakdowns
- 📊 15+ interactive charts - Temperature, precipitation, wind, UV, humidity, and more
⚠️ Real-time weather alerts - Severe weather warnings with map markers- 💨 Air quality monitoring - Live AQI with 6 pollutant measurements
- 🌧️ Interactive radar map - Real historical precipitation data with animation
- 🤖 AI Weather Assistant - Natural language queries powered by Claude Sonnet 4.5
- 🔍 Smart Universal Search - One input for locations AND AI questions
- 📈 10-year climate analysis - Historical trends and statistical insights
- 🌍 Location comparison - Compare weather across 2-4 cities side-by-side
- 🌍 Weather Twins - Find cities worldwide with similar current weather (NEW!)
- 🤖 AI location finder - Describe your ideal climate, get recommendations
- 🔐 User accounts - Cloud-synced favorites and preferences across devices
- 🎨 Theme system - Light, dark, and auto modes with full component coverage
- ♿ Fully accessible - WCAG 2.1 Level AA, keyboard navigation, screen readers
- 📱 Mobile responsive - Optimized for all device sizes
- 🔗 Shareable URLs - Direct links to any city's weather
- ⚙️ User preferences - Email notifications, report scheduling, customization
- ⚡ 99% cache hit rate - MySQL-based caching, 282x faster responses
- 🔒 Security score 9.4/10 - 0 vulnerabilities, automated scanning
- 🐳 Docker ready - One-command deployment
- 📉 Minimal footprint - Runs on $6/month VPS
→ Complete Feature List | Live Demo
All documentation is organized in the docs/ folder:
| Category | Description | Link |
|---|---|---|
| 🚀 Getting Started | Quickstart, architecture, onboarding | View → |
| 📡 API Reference | Complete API docs (3 formats) | View → |
| 🔧 Development | Code guides, conventions, branching | View → |
| 🚀 Deployment | Production deployment guides | View → |
| 🔐 Security | Security features & audits (9.4/10) | View → |
| ♿ Accessibility | WCAG Level AA compliance docs | View → |
| ⚙️ CI/CD | Pipeline optimization & guides | View → |
| 💾 Database | Schema, ERD, optimizations | View → |
| 🎨 UI/UX | Design system & guidelines | View → |
| Common issues & solutions | View → |
Most Popular:
- 🎯 3-Minute Quickstart
- 📡 API Reference (with OpenAPI & Postman)
- 🗺️ Product Roadmap
- 🤝 Contributing Guide
- 🔐 Security Policy
- ❓ FAQ & Support
APIs: Visual Crossing Weather, OpenWeather, RainViewer, Claude AI, Open-Meteo Air Quality
Recommended for development:
- CPU: 1-2 cores (2 GHz+)
- RAM: 2 GB minimum, 4 GB recommended
- Storage: 10 GB free space
- OS: Linux (Ubuntu 20.04+), macOS, or Windows with WSL2
Production: Successfully tested on DigitalOcean $6/month droplet (1 vCPU, 1 GB RAM)
What you need installed:
- Docker (20.10+) and Docker Compose (1.29+)
- Git - for cloning the repository
Security Score: 9.4/10 - Enterprise-grade security with 0 vulnerabilities
- ✅ Gitleaks Secret Scanning - Pre-commit hooks + GitHub Actions
- ✅ Dependabot Monitoring - Automated vulnerability detection & patching
- ✅ npm Security Audits - Regular dependency scanning
- ✅ CodeQL Analysis - Automated code security scanning
- ✅ Rate Limiting - Protects against abuse and API cost overruns
- ✅ Security Headers - CSP, HSTS, X-Frame-Options, etc.
Current Status:
- 0 vulnerabilities in production dependencies
- All 9 historical vulnerabilities patched
- Weekly automated security scans
- Automated Dependabot PRs for security updates
→ Security Documentation | Security Policy
Accessibility Score: 8.5-9/10 - Full WCAG 2.1 Level AA compliance
- ✅ WCAG 2.1 Level A - Foundation accessibility
- ✅ WCAG 2.1 Level AA - Enhanced accessibility (target standard)
- ✅ WCAG 2.1 Level AAA - Animation control (bonus)
- 🎯 Screen reader support - NVDA, JAWS, VoiceOver tested
- ⌨️ Complete keyboard navigation - All features accessible via keyboard
- 🎨 Color contrast - 4.5:1 minimum ratio throughout
- 🎬 Motion control - Respects prefers-reduced-motion
- 🔍 Focus indicators - Visible 3px purple outlines
- 💬 Error suggestions - 200+ contextual recovery hints
→ Accessibility Audit | WCAG Compliance
We welcome contributions! This project follows GitHub Flow for a simple, effective workflow.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'feat: add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request (CI must pass before merge)
- 🐛 Bug fixes
- ✨ New features
- 📚 Documentation improvements
- 🎨 UI/UX enhancements (especially needed!)
- ♿ Accessibility improvements
- 🧪 Test coverage increases
→ Contributing Guide | Branching Strategy | Code of Conduct
Good First Issues: View on GitHub
Recent Achievements:
- ✅ Express 4 → 5 migration (Nov 2025)
- ✅ WCAG 2.1 Level AA compliance (Nov 2025)
- ✅ CI/CD optimization - 50-70% faster (Nov 2025)
- ✅ Database performance - 20-50x faster queries (Nov 2025)
- ✅ User-managed API keys for 7 AI providers (Nov 2025)
Planned Features:
- 📧 Email notifications for weather alerts
- 📱 Mobile app (React Native)
- 🌐 Multi-language support (i18n)
- 📊 Extended historical data (20+ years)
- 🛰️ Satellite imagery overlays
- 🌾 Pollen and allergen forecasts
MIT License - See LICENSE for details.
Feel free to use this project for learning, development, and production!
Data Providers:
- Weather data: Visual Crossing Weather API
- Radar data: RainViewer API
- Map overlays: OpenWeather API
- Air quality: Open-Meteo Air Quality API
- AI: Anthropic Claude
Inspiration:
- Visualizations inspired by Weather Spark
Built with ❤️ by Michael Buckingham