VortexiumWeather - Real-time Weather Alerts System

A comprehensive weather alerts system that synchronizes data from the National Weather Service (NWS) API and displays it on an interactive map in real-time.

Architecture Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
│   NWS API       │    │  Sync Service    │    │  PostgreSQL + Redis │
│  (weather.gov)  │◄──►│  (Node.js)       │◄──►│  (Docker Compose)   │
└─────────────────┘    └──────────────────┘    └─────────────────────┘
                                │                         ▲
                                ▼                         │
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
│  Next.js Web    │    │  REST API        │    │                     │
│  Application    │◄──►│  (Express.js)    │◄───┘                     │
└─────────────────┘    └──────────────────┘                          

Applications

1. weather-alerts-db 📊

PostgreSQL database with PostGIS for spatial weather data storage.

Features:

• PostGIS spatial database for weather alert polygons
• Redis caching layer
• Automated schema with indexes and triggers
• Data cleanup and maintenance functions

2. nws-alerts-sync 🔄

Background service that syncs weather alerts from NWS API to database.

Features:

• Real-time synchronization with NWS API
• Rate limiting and error handling
• Batch processing and deduplication
• Health monitoring and logging
• Automatic expired alerts cleanup

3. weather-alerts-api 🌐

REST API server providing weather alerts data to frontends.

Features:

• High-performance spatial queries
• Redis caching for fast responses
• Comprehensive filtering and pagination
• Interactive API documentation (Swagger)
• Rate limiting and CORS support

4. vortexium-weather-web 🗺️

Next.js web application with interactive map displaying weather alerts.

Features:

• Real-time weather alerts overlay on map
• Interactive alert popups with detailed information
• Spatial filtering based on map bounds
• Responsive design with modern UI
• Toggle alerts visibility

Quick Start

Prerequisites

• Node.js 18+ and npm
• Docker and Docker Compose
• Git

1. Start the Database

cd apps/weather-alerts-db
docker-compose up -d

2. Start the Sync Service

cd apps/nws-alerts-sync
npm install
cp .env.example .env
# Edit .env with your settings (especially NWS_USER_AGENT)
npm run dev

3. Start the API Server

cd apps/weather-alerts-api
npm install
cp .env.example .env
npm run dev

4. Start the Web Application

cd apps/vortexium-weather-web
npm install
cp .env.local.example .env.local
# Add your MapTiler API key to .env.local
npm run dev

-### 5. Access the Applications

• Web App: http://localhost:27002
• API Docs: http://localhost:27000/docs
• Sync Health: http://localhost:27001/health
• Database: localhost:5465 (PostgreSQL)

Environment Setup

NWS API Configuration

The NWS API requires a proper User-Agent header. Update your sync service .env:

NWS_USER_AGENT=YourAppName/1.0 (your-email@domain.com)

MapTiler API Key

Get a free API key from MapTiler and add to your web app .env.local:

NEXT_PUBLIC_MAPTILER_API_KEY=your_api_key_here

Features

Real-time Weather Alerts

• Automatic Sync: Alerts are fetched every 5 minutes from NWS API
• Spatial Data: Full polygon geometry for precise alert boundaries
• Rich Metadata: Severity, urgency, event types, affected zones
• Temporal Tracking: Onset, expiration, and effective times

Interactive Map

• Spatial Filtering: Only shows alerts in current map bounds
• Visual Hierarchy: Color-coded by severity (Extreme=red, Minor=yellow)
• Click Interactions: Detailed popup with alert information
• Performance: Cached data with smart loading

API Capabilities

• Geographic Queries: Find alerts by bounds or point coordinates
• Advanced Filtering: By severity, event type, urgency, zones
• Pagination: Efficient handling of large datasets
• Caching: Redis-powered response caching

Data Flow

1. NWS Sync Service fetches alerts from NWS API every 5 minutes
2. Database stores alerts with spatial geometry and metadata
3. API Server serves cached, filtered alert data to clients
4. Web App displays alerts on map with real-time updates
5. User Interaction allows exploring alerts with detailed popups

Monitoring & Health

Health Endpoints

• Sync Service: GET /health - Service and API connectivity
• API Server: GET /health - Database and Redis status
• Database: Standard PostgreSQL monitoring

Logging

All services provide structured logging:

• Request/response tracking
• Error reporting with stack traces
• Performance metrics
• Alert processing statistics

Metrics

• Alert processing counts and timing
• API response times and cache hit rates
• Database query performance
• System resource usage

Production Deployment

Docker Deployment

Each service includes Dockerfile for containerization:

# Build sync service
cd apps/nws-alerts-sync
docker build -t nws-sync .

# Build API server  
cd apps/weather-alerts-api
docker build -t weather-api .

# Deploy with docker-compose
docker-compose -f docker-compose.prod.yml up -d

Environment Variables

Key production settings:

• NODE_ENV=production
• DATABASE_URL with connection pooling
• REDIS_URL for distributed caching
• LOG_LEVEL=warn for production logging
• Rate limiting and CORS for security

Database Scaling

• Read replicas for API queries
• Connection pooling (default: 20 connections)
• Spatial indexes for fast geographic queries
• Regular cleanup of expired alerts

API Reference

Get Alerts

GET /api/v1/alerts?severity=Severe,Extreme&limit=50

Get Alerts by Geographic Bounds

GET /api/v1/alerts/bounds?minLat=40&minLon=-100&maxLat=45&maxLon=-90

Get Alerts by Point

GET /api/v1/alerts/point?lat=40.7128&lon=-74.0060

Get Summary Statistics

GET /api/v1/alerts/summary

Development

Database Schema

-- View active alerts with geographic bounds
SELECT * FROM active_alerts_with_bounds 
WHERE severity IN ('Severe', 'Extreme');

-- Cleanup expired alerts
SELECT cleanup_expired_alerts();

Custom Styling

Weather alerts are styled by severity:

• Extreme: Dark Red (#8B0000)
• Severe: Orange Red (#FF4500)
• Moderate: Orange (#FFA500)
• Minor: Yellow (#FFFF00)

Adding New Features

1. Database: Add columns/tables to init-scripts/01-init.sql
2. Sync: Update types in nws-alerts-sync/src/types.ts
3. API: Add endpoints in weather-alerts-api/src/routes/
4. Frontend: Create components in vortexium-weather-web/src/components/

Troubleshooting

Common Issues

Sync Service Not Working

• Check NWS_USER_AGENT format
• Verify internet connectivity to api.weather.gov
• Check rate limiting in logs

No Alerts Showing on Map

• Verify API server is running on port 27000
• Check NEXT_PUBLIC_WEATHER_ALERTS_API environment variable
• Check browser console for CORS errors

Database Connection Errors

• Ensure PostgreSQL container is running
• Check DATABASE_URL connection string
• Verify database credentials

Map Not Loading

• Check MapTiler API key in environment
• Verify internet connectivity
• Check browser console for errors

Logs Location

• Sync Service: logs/nws-sync.log
• API Server: logs/weather-alerts-api.log
• Database: Docker logs via docker-compose logs postgres

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT License - see individual app LICENSE files for details.

Support

For issues and questions:

• Check the individual app README files
• Review the troubleshooting section
• Open a GitHub issue with detailed information
• Check logs for error messages

---

Built with ❤️ for real-time weather awareness and safety