Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
1349 lines (1098 loc) · 39.4 KB

ARCHITECTURE.md

File metadata and controls

1349 lines (1098 loc) · 39.4 KB

IntelliWeather API - Complete Architecture

Version: 3.0.0
Last Updated: December 1, 2025
Phase: 4 (LEVEL 2 Complete, LEVEL 3 In Progress)
Status: Production Ready

System Architecture Diagram

graph TB
    subgraph "Client Layer"
        UI[Web UI<br/>static/index.html]
        API_CLIENT[API Clients<br/>curl, Postman, etc.]
    end

    subgraph "Load Balancer"
        NGINX[NGINX<br/>Port 80]
    end

    subgraph "Application Layer"
        APP1[FastAPI App Instance 1<br/>Port 8000]
        APP2[FastAPI App Instance 2<br/>Port 8001]
        APP3[FastAPI App Instance 3<br/>Port 8002]
    end

    subgraph "Middleware Layer"
        CORS[CORS Middleware<br/>Cross-Origin Support]
        RATE[Rate Limiter<br/>60 req/min per IP]
        SESSION[Session Middleware<br/>Cookie-based Auth]
        METRICS[Metrics Middleware<br/>Request Tracking]
    end

    subgraph "Route Handlers"
        AUTH[Auth Routes<br/>/auth/*]
        WEATHER_V1[Weather V1<br/>/weather, /hourly, /forecast]
        WEATHER_V2[Weather V2<br/>/weather/hourly, /weather/daily]
        FORECAST_V3[Forecast V3 ✅<br/>/api/v3/forecast/*]
        INSIGHTS[Weather Insights ✅<br/>/api/v3/insights/*]
        POLLEN[Pollen Forecast ✅ L2<br/>/api/v3/pollen/*]
        SOLAR[Solar & Energy ✅ L2<br/>/api/v3/solar/*]
        AQI_V2[Air Quality V2 ✅ L2<br/>/api/v3/air-quality/*]
        MARINE[Marine Weather ✅ L2<br/>/api/v3/marine/*]
        GEOCODE[Geocoding V2 ✅<br/>/geocode/*]
        ALERTS[Alerts<br/>/alerts/*]
        DOWNLOADS[Downloads<br/>/downloads/*]
        APIKEYS[API Keys<br/>/api-keys/*]
        PREDICT[ML Predictions<br/>/predict]
        ADMIN[Admin Dashboard<br/>/admin/*]
        I18N[Internationalization<br/>/i18n/*]
    end

    subgraph "Core Services"
        CACHE[Cache Service<br/>In-Memory TTL Cache]
        STORAGE[Storage Service<br/>CSV-based Persistence]
        AUTH_SERVICE[Auth Service<br/>JWT + Bcrypt]
        METRICS_SERVICE[Metrics Service<br/>Counters & Timers]
        INSIGHTS_ENGINE[✅ Weather Insights Engine<br/>Proprietary Algorithms]
        POLLEN_ENGINE[✅ Pollen Analysis Engine<br/>L2 Feature]
        SOLAR_ENGINE[✅ Solar/PV Calculator<br/>L2 Feature]
        AQI_ENGINE[✅ Air Quality Analyzer<br/>L2 Feature]
        MARINE_ENGINE[✅ Marine Conditions Processor<br/>L2 Feature]
    end

    subgraph "External APIs"
        OPEN_METEO[Open-Meteo API<br/>Primary Weather Source]
        OPEN_METEO_AQ[Open-Meteo Air Quality<br/>Pollen + AQI Data]
        OPEN_METEO_MARINE[Open-Meteo Marine<br/>Ocean Conditions]
        WEATHER_API[WeatherAPI.com<br/>Fallback Source]
    end

    subgraph "Data Storage"
        CSV_USERS[users.csv]
        CSV_SESSIONS[sessions.csv]
        CSV_HISTORY[search_history.csv]
        CSV_CACHE[cached_weather.csv]
    end

    subgraph "Monitoring & Observability"
        LOGS[Structured Logging<br/>JSON Format]
        PROMETHEUS[Prometheus Metrics<br/>/metrics/prometheus]
        HEALTH[Health Checks<br/>/healthz]
        SENTRY[Sentry<br/>Error Tracking]
    end

    UI --> NGINX
    API_CLIENT --> NGINX
    NGINX --> APP1
    NGINX --> APP2
    NGINX --> APP3
    
    APP1 --> CORS
    APP1 --> RATE
    APP1 --> SESSION
    APP1 --> METRICS
    
    CORS --> AUTH
    CORS --> WEATHER_V1
    CORS --> WEATHER_V2
    CORS --> FORECAST_V3
    CORS --> INSIGHTS
    CORS --> GEOCODE
    CORS --> ALERTS
    CORS --> DOWNLOADS
    CORS --> APIKEYS
    CORS --> PREDICT
    CORS --> ADMIN
    CORS --> I18N
    
    WEATHER_V1 --> CACHE
    WEATHER_V2 --> CACHE
    FORECAST_V3 --> CACHE
    INSIGHTS --> INSIGHTS_ENGINE
    INSIGHTS_ENGINE --> CACHE
    AUTH --> AUTH_SERVICE
    AUTH --> STORAGE
    
    CACHE --> OPEN_METEO
    CACHE --> WEATHER_API
    WEATHER_V1 --> AIR_QUALITY
    
    STORAGE --> CSV_USERS
    STORAGE --> CSV_SESSIONS
    STORAGE --> CSV_HISTORY
    STORAGE --> CSV_CACHE
    
    APP1 --> LOGS
    APP1 --> PROMETHEUS
    APP1 --> HEALTH
    APP1 --> SENTRY
Loading

Request Flow Architecture

sequenceDiagram
    participant Client
    participant NGINX
    participant FastAPI
    participant RateLimiter
    participant Cache
    participant OpenMeteo
    participant WeatherAPI
    participant Storage

    Client->>NGINX: GET /weather?lat=40.71&lon=-74.01
    NGINX->>FastAPI: Forward Request
    FastAPI->>RateLimiter: Check Rate Limit
    
    alt Rate Limit Exceeded
        RateLimiter-->>Client: 429 Too Many Requests
    else Within Limit
        RateLimiter->>Cache: Check Cache
        
        alt Cache Hit
            Cache-->>FastAPI: Return Cached Data
            FastAPI-->>Client: 200 OK (source: cache)
        else Cache Miss
            Cache->>OpenMeteo: Fetch Weather Data
            
            alt OpenMeteo Success
                OpenMeteo-->>Cache: Weather Data
                Cache->>Storage: Save to CSV
                Cache-->>FastAPI: Fresh Data
                FastAPI-->>Client: 200 OK (source: live)
            else OpenMeteo Fails
                OpenMeteo-->>Cache: Error/Timeout
                Cache->>WeatherAPI: Try Fallback
                
                alt Fallback Success
                    WeatherAPI-->>Cache: Weather Data
                    Cache->>Storage: Save to CSV
                    Cache-->>FastAPI: Fallback Data
                    FastAPI-->>Client: 200 OK (source: fallback)
                else Fallback Fails
                    WeatherAPI-->>Cache: Error
                    Cache-->>FastAPI: Error
                    FastAPI-->>Client: 503 Service Unavailable
                end
            end
        end
    end
Loading

Caching Architecture

graph LR
    subgraph "Cache Layers"
        L1[L1: In-Memory Cache<br/>TTL: 30min-1hr<br/>Max: 1000 items]
        L2[L2: CSV Storage<br/>Persistent Cache]
        L3[L3: Database<br/>PostgreSQL<br/>Optional]
    end

    subgraph "Cache Keys"
        KEY1[weather:current:lat:lon]
        KEY2[weather:hourly_v2:lat:lon:hours]
        KEY3[weather:daily_v2:lat:lon:days]
        KEY4[geocode:search:query]
    end

    subgraph "Cache Operations"
        GET[Get]
        SET[Set with TTL]
        DELETE[Delete]
        CLEANUP[Periodic Cleanup<br/>Every 5 min]
    end

    REQUEST[Incoming Request] --> GET
    GET --> L1
    L1 -->|Hit| RESPONSE[Return Data]
    L1 -->|Miss| L2
    L2 -->|Hit| SET
    L2 -->|Miss| API[External API]
    API --> SET
    SET --> L1
    SET --> L2
    
    CLEANUP --> L1
Loading

Authentication Flow

sequenceDiagram
    participant User
    participant UI
    participant API
    participant Auth
    participant Storage
    participant Session

    User->>UI: Enter Credentials
    UI->>API: POST /auth/signup
    API->>Auth: Hash Password (bcrypt)
    Auth->>Storage: Save User to users.csv
    Storage-->>API: User Created
    API-->>UI: Success

    User->>UI: Login
    UI->>API: POST /auth/login
    API->>Storage: Get User by Email
    Storage-->>API: User Data
    API->>Auth: Verify Password
    
    alt Password Valid
        Auth->>Session: Create Session
        Session->>Storage: Save to sessions.csv
        Session-->>API: Session ID
        API-->>UI: Set-Cookie: session_id
        UI-->>User: Redirect to Dashboard
    else Password Invalid
        Auth-->>API: Invalid
        API-->>UI: 401 Unauthorized
        UI-->>User: Show Error
    end

    User->>UI: Access Protected Route
    UI->>API: GET /auth/me (with session cookie)
    API->>Session: Validate Session
    Session->>Storage: Check sessions.csv
    
    alt Session Valid
        Storage-->>Session: Session Data
        Session-->>API: User Info
        API-->>UI: 200 OK + User Data
    else Session Invalid/Expired
        Session-->>API: Invalid
        API-->>UI: 401 Unauthorized
        UI-->>User: Redirect to Login
    end
Loading

Fallback System Architecture

graph TD
    START[Weather Request] --> CACHE_CHECK{Cache<br/>Available?}
    
    CACHE_CHECK -->|Yes| CACHE_HIT[Return Cached Data<br/>source: cache]
    CACHE_CHECK -->|No| PRIMARY[Call Open-Meteo API]
    
    PRIMARY --> PRIMARY_CHECK{Success?}
    
    PRIMARY_CHECK -->|Yes| CACHE_SAVE[Save to Cache<br/>TTL: 30-60 min]
    CACHE_SAVE --> PRIMARY_RETURN[Return Data<br/>source: live]
    
    PRIMARY_CHECK -->|No| FALLBACK_ENABLED{Fallback<br/>Enabled?}
    
    FALLBACK_ENABLED -->|No| ERROR_503[503 Service<br/>Unavailable]
    
    FALLBACK_ENABLED -->|Yes| FALLBACK[Call WeatherAPI.com]
    
    FALLBACK --> FALLBACK_CHECK{Success?}
    
    FALLBACK_CHECK -->|Yes| CONVERT[Convert Data Format<br/>WeatherAPI → Internal]
    CONVERT --> FALLBACK_CACHE[Save to Cache]
    FALLBACK_CACHE --> FALLBACK_RETURN[Return Data<br/>source: fallback]
    
    FALLBACK_CHECK -->|No| BOTH_FAILED[Both APIs Failed]
    BOTH_FAILED --> ERROR_503
    
    style CACHE_HIT fill:#90EE90
    style PRIMARY_RETURN fill:#90EE90
    style FALLBACK_RETURN fill:#FFD700
    style ERROR_503 fill:#FF6B6B
Loading

Data Models & Storage

classDiagram
    class User {
        +string user_id
        +string username
        +string email
        +string hashed_password
        +datetime created_at
        +create()
        +to_csv_row()
        +from_csv_row()
    }

    class Session {
        +string session_id
        +string user_id
        +datetime created_at
        +datetime expires_at
        +bool is_valid
        +create()
        +is_expired()
    }

    class SearchHistory {
        +string search_id
        +string user_id
        +string location_name
        +float latitude
        +float longitude
        +datetime searched_at
        +create()
    }

    class CachedWeather {
        +string cache_id
        +float latitude
        +float longitude
        +string location_name
        +string data_type
        +string data
        +datetime cached_at
        +create()
    }

    class WeatherResponse {
        +float latitude
        +float longitude
        +string timezone
        +string source
        +datetime generated_at
    }

    class HourlyDataPoint {
        +string time
        +float temperature
        +float feels_like
        +int humidity
        +float precipitation
        +int precipitation_probability
        +float wind_speed
    }

    class DailyDataPoint {
        +string date
        +float temperature_max
        +float temperature_min
        +float precipitation_sum
        +int precipitation_probability_max
        +string sunrise
        +string sunset
    }

    User "1" --> "N" Session : has
    User "1" --> "N" SearchHistory : creates
    WeatherResponse "1" --> "N" HourlyDataPoint : contains
    WeatherResponse "1" --> "N" DailyDataPoint : contains
Loading

Rate Limiting Algorithm

graph TB
    START[Incoming Request] --> EXTRACT[Extract Client IP]
    EXTRACT --> WINDOW[Get Sliding Window<br/>for IP]
    
    WINDOW --> COUNT{Count Requests<br/>in Last 60s}
    
    COUNT -->|< 60 requests| ALLOW[Allow Request]
    ALLOW --> ADD[Add Timestamp<br/>to Window]
    ADD --> PROCESS[Process Request]
    PROCESS --> HEADERS[Add Headers<br/>X-RateLimit-Limit<br/>X-RateLimit-Remaining]
    
    COUNT -->|>= 60 requests| REJECT[429 Too Many<br/>Requests]
    REJECT --> RETRY[Add Header<br/>Retry-After: 60s]
    
    CLEANUP[Background Task<br/>Every 60s] --> PURGE[Remove Old<br/>Timestamps]
    
    style ALLOW fill:#90EE90
    style REJECT fill:#FF6B6B
Loading

Metrics & Observability

graph TB
    subgraph "Metrics Collection"
        COUNTER[Counters<br/>total_requests<br/>cache_hits<br/>cache_misses<br/>fallback_attempts]
        GAUGE[Gauges<br/>active_sessions<br/>cache_size]
        TIMER[Timers<br/>request_duration<br/>api_response_time]
    end

    subgraph "Metrics Endpoints"
        JSON[/metrics<br/>JSON Format]
        PROM[/metrics/prometheus<br/>Prometheus Format]
    end

    subgraph "Monitoring Tools"
        GRAFANA[Grafana<br/>Dashboards]
        PROMETHEUS_SERVER[Prometheus<br/>Time-Series DB]
        ALERTS[Alert Manager<br/>Alerts & Notifications]
    end

    subgraph "Logging"
        STRUCTURED[Structured Logs<br/>JSON Format]
        LOG_LEVELS[Levels:<br/>DEBUG, INFO,<br/>WARNING, ERROR]
    end

    COUNTER --> JSON
    GAUGE --> JSON
    TIMER --> JSON
    
    COUNTER --> PROM
    GAUGE --> PROM
    TIMER --> PROM
    
    PROM --> PROMETHEUS_SERVER
    PROMETHEUS_SERVER --> GRAFANA
    PROMETHEUS_SERVER --> ALERTS
    
    STRUCTURED --> LOG_LEVELS
    LOG_LEVELS --> SENTRY[Sentry<br/>Error Tracking]
Loading

Deployment Architecture

graph TB
    subgraph "Development"
        DEV[Local Development<br/>python app.py<br/>Port 8000]
    end

    subgraph "Docker Single Container"
        DOCKER[Docker Container<br/>Dockerfile<br/>Port 8000]
    end

    subgraph "Docker Compose"
        DC_NGINX[NGINX Load Balancer<br/>Port 80]
        DC_APP1[App Instance 1<br/>Port 8000]
        DC_APP2[App Instance 2<br/>Port 8001]
        DC_APP3[App Instance 3<br/>Port 8002]
    end

    subgraph "Kubernetes"
        K8S_INGRESS[Ingress<br/>nginx-ingress]
        K8S_SERVICE[Service<br/>LoadBalancer]
        K8S_DEPLOY[Deployment<br/>3 Replicas]
        K8S_POD1[Pod 1]
        K8S_POD2[Pod 2]
        K8S_POD3[Pod 3]
        K8S_CONFIG[ConfigMap<br/>Environment]
        K8S_SECRET[Secrets<br/>API Keys]
    end

    DC_NGINX --> DC_APP1
    DC_NGINX --> DC_APP2
    DC_NGINX --> DC_APP3

    K8S_INGRESS --> K8S_SERVICE
    K8S_SERVICE --> K8S_DEPLOY
    K8S_DEPLOY --> K8S_POD1
    K8S_DEPLOY --> K8S_POD2
    K8S_DEPLOY --> K8S_POD3
    K8S_CONFIG --> K8S_POD1
    K8S_SECRET --> K8S_POD1
Loading

Feature Toggle System

graph LR
    CONFIG[config.py<br/>Settings] --> FEATURES[Feature Flags]
    
    FEATURES --> F1[FEATURE_WEATHER_V2<br/>Enhanced Endpoints]
    FEATURES --> F2[FEATURE_GEOCODING<br/>Location Search]
    FEATURES --> F3[FEATURE_ALERTS<br/>Weather Alerts]
    FEATURES --> F4[FEATURE_DOWNLOADS<br/>PDF/Excel Reports]
    FEATURES --> F5[FEATURE_API_KEYS<br/>API Key Management]
    FEATURES --> F6[FEATURE_ML_PREDICTIONS<br/>ML Forecasts]
    FEATURES --> F7[FEATURE_ADMIN<br/>Admin Dashboard]
    FEATURES --> F8[FEATURE_I18N<br/>Multi-language]
    FEATURES --> F9[ENABLE_FALLBACK<br/>API Fallback]
    
    subgraph "Phase 3 Features 🆕"
        F10[FEATURE_NOWCAST<br/>High-res 2hr Forecast]
        F11[FEATURE_EXTENDED_HOURLY<br/>Up to 168 hours]
        F12[FEATURE_EXTENDED_DAILY<br/>Up to 16 days]
        F13[FEATURE_HYBRID_FORECAST<br/>Multi-source Blend]
        F14[FEATURE_HEAT_INDEX<br/>Proprietary Calc]
        F15[FEATURE_FIRE_RISK<br/>0-100 Scoring]
        F16[FEATURE_UV_EXPOSURE<br/>UV Assessment]
        F17[FEATURE_TRAVEL_DISRUPTION<br/>Multi-modal Risk]
        F18[FEATURE_AUTOCOMPLETE<br/>Typeahead Search]
    end
    
    FEATURES --> F10
    FEATURES --> F11
    FEATURES --> F12
    FEATURES --> F13
    FEATURES --> F14
    FEATURES --> F15
    FEATURES --> F16
    FEATURES --> F17
    FEATURES --> F18
    
    F1 -->|True| MOUNT1[Mount /weather/* routes]
    F2 -->|True| MOUNT2[Mount /geocode/* routes]
    F3 -->|True| MOUNT3[Mount /alerts/* routes]
    F4 -->|True| MOUNT4[Mount /downloads/* routes]
    F5 -->|True| MOUNT5[Mount /api-keys/* routes]
    F6 -->|True| MOUNT6[Mount /predict route]
    F7 -->|True| MOUNT7[Mount /admin/* routes]
    F8 -->|True| MOUNT8[Mount /i18n/* routes]
    F9 -->|True| FALLBACK[Enable Fallback Logic]
    
    F10 -->|True| MOUNT10[Mount Nowcast Endpoint]
    F14 -->|True| MOUNT14[Enable Heat Index Calc]
    F15 -->|True| MOUNT15[Enable Fire Risk Calc]
    F18 -->|True| MOUNT18[Enable Autocomplete]
    
    style F1 fill:#90EE90
    style F2 fill:#90EE90
    style F9 fill:#90EE90
    style F10 fill:#87CEEB
    style F11 fill:#87CEEB
    style F12 fill:#87CEEB
    style F13 fill:#87CEEB
    style F14 fill:#87CEEB
    style F15 fill:#87CEEB
Loading

Phase 3: Weather Insights Architecture 🆕

Insights Calculation Flow

sequenceDiagram
    participant Client
    participant API
    participant Cache
    participant OpenMeteo
    participant InsightsEngine
    participant Algorithms

    Client->>API: GET /api/v3/insights/current
    API->>Cache: Check Cache (15min TTL)
    
    alt Cache Hit
        Cache-->>API: Cached Insights
        API-->>Client: 200 OK (cached)
    else Cache Miss
        Cache->>OpenMeteo: Fetch Current Weather
        OpenMeteo-->>Cache: Raw Weather Data
        Cache->>InsightsEngine: Calculate Insights
        
        InsightsEngine->>Algorithms: Heat Index Calc
        Algorithms-->>InsightsEngine: Heat Index Value
        
        InsightsEngine->>Algorithms: Fire Risk Calc
        Algorithms-->>InsightsEngine: Fire Risk Score
        
        InsightsEngine->>Algorithms: UV Exposure Calc
        Algorithms-->>InsightsEngine: UV Assessment
        
        InsightsEngine->>Algorithms: Travel Disruption Calc
        Algorithms-->>InsightsEngine: Disruption Risk
        
        InsightsEngine->>Algorithms: Comfort Index Calc
        Algorithms-->>InsightsEngine: Comfort Score
        
        InsightsEngine->>Algorithms: Rain Confidence Calc
        Algorithms-->>InsightsEngine: Confidence Score
        
        InsightsEngine-->>Cache: All Insights
        Cache->>Cache: Store (15min TTL)
        Cache-->>API: Fresh Insights
        API-->>Client: 200 OK (live)
    end
Loading

Proprietary Algorithms Module

classDiagram
    class WeatherInsights {
        +calculate_all_insights(weather_data)
    }
    
    class TemperatureFeels {
        +calculate_heat_index(temp, humidity)
        +calculate_wind_chill(temp, wind_speed)
        +calculate_wet_bulb_temperature(temp, humidity, pressure)
    }
    
    class RiskScoring {
        +calculate_fire_risk_score(temp, humidity, wind, precip, days_dry)
        +calculate_uv_exposure_score(uv_index, cloud_cover)
        +calculate_travel_disruption_risk(precip, wind, visibility, temp, weather_code)
    }
    
    class ConfidenceMetrics {
        +calculate_rain_confidence(precip_prob, precip_mm, cloud_cover, humidity)
        +calculate_comfort_index(temp, humidity, wind)
    }
    
    WeatherInsights --> TemperatureFeels
    WeatherInsights --> RiskScoring
    WeatherInsights --> ConfidenceMetrics
    
    note for TemperatureFeels "NWS-approved formulas\nRothfusz regression\nStull's formula"
    note for RiskScoring "Proprietary 4-factor algorithms\n0-100 scoring\nMulti-modal analysis"
    note for ConfidenceMetrics "Multi-factor assessment\nComposite scoring"
Loading

Fire Risk Scoring Algorithm

graph TD
    START[Fire Risk Request] --> INPUTS[Gather Inputs]
    
    INPUTS --> TEMP[Temperature Factor<br/>0-30 points]
    INPUTS --> HUMID[Humidity Factor<br/>0-30 points]
    INPUTS --> WIND[Wind Factor<br/>0-20 points]
    INPUTS --> DRY[Dryness Factor<br/>0-20 points]
    
    TEMP --> TEMP_CHECK{Temp > 35°C?}
    TEMP_CHECK -->|Yes| TEMP_30[+30 points]
    TEMP_CHECK -->|30-35°C| TEMP_25[+25 points]
    TEMP_CHECK -->|25-30°C| TEMP_15[+15 points]
    TEMP_CHECK -->|20-25°C| TEMP_5[+5 points]
    TEMP_CHECK -->|< 20°C| TEMP_0[+0 points]
    
    HUMID --> HUMID_CHECK{Humidity < 20%?}
    HUMID_CHECK -->|Yes| HUMID_30[+30 points]
    HUMID_CHECK -->|20-30%| HUMID_25[+25 points]
    HUMID_CHECK -->|30-40%| HUMID_15[+15 points]
    HUMID_CHECK -->|40-50%| HUMID_5[+5 points]
    HUMID_CHECK -->|> 50%| HUMID_0[+0 points]
    
    WIND --> WIND_CHECK{Wind > 40 km/h?}
    WIND_CHECK -->|Yes| WIND_20[+20 points]
    WIND_CHECK -->|30-40| WIND_15[+15 points]
    WIND_CHECK -->|20-30| WIND_10[+10 points]
    WIND_CHECK -->|10-20| WIND_5[+5 points]
    WIND_CHECK -->|< 10| WIND_0[+0 points]
    
    DRY --> DRY_CHECK{Days Since Rain?}
    DRY_CHECK -->|> 14 days| DRY_20[+20 points]
    DRY_CHECK -->|7-14 days| DRY_15[+15 points]
    DRY_CHECK -->|3-7 days| DRY_10[+10 points]
    DRY_CHECK -->|Recent rain| DRY_NEG[-10 points]
    
    TEMP_30 --> SUM[Sum All Points]
    TEMP_25 --> SUM
    TEMP_15 --> SUM
    TEMP_5 --> SUM
    TEMP_0 --> SUM
    HUMID_30 --> SUM
    HUMID_25 --> SUM
    HUMID_15 --> SUM
    HUMID_5 --> SUM
    HUMID_0 --> SUM
    WIND_20 --> SUM
    WIND_15 --> SUM
    WIND_10 --> SUM
    WIND_5 --> SUM
    WIND_0 --> SUM
    DRY_20 --> SUM
    DRY_15 --> SUM
    DRY_10 --> SUM
    DRY_NEG --> SUM
    
    SUM --> CATEGORY{Score?}
    CATEGORY -->|81-100| EXTREME[Extreme Risk<br/>No outdoor burning]
    CATEGORY -->|61-80| VERY_HIGH[Very High Risk<br/>Avoid open flames]
    CATEGORY -->|41-60| HIGH[High Risk<br/>Exercise caution]
    CATEGORY -->|21-40| MODERATE[Moderate Risk<br/>Be cautious]
    CATEGORY -->|0-20| LOW[Low Risk<br/>Normal precautions]
    
    EXTREME --> RESULT[Return Result]
    VERY_HIGH --> RESULT
    HIGH --> RESULT
    MODERATE --> RESULT
    LOW --> RESULT
    
    style EXTREME fill:#8B0000
    style VERY_HIGH fill:#FF4500
    style HIGH fill:#FFA500
    style MODERATE fill:#FFD700
    style LOW fill:#90EE90
Loading

Forecast V3 Architecture

graph TB
    subgraph "Forecast V3 Endpoints"
        NOWCAST[/api/v3/forecast/nowcast<br/>15-min intervals, 2 hours]
        HOURLY[/api/v3/forecast/hourly<br/>Up to 168 hours]
        DAILY[/api/v3/forecast/daily<br/>Up to 16 days]
        COMPLETE[/api/v3/forecast/complete<br/>All-in-one package]
    end
    
    subgraph "Data Sources"
        OM_NOWCAST[Open-Meteo<br/>minutely_15 endpoint]
        OM_HOURLY[Open-Meteo<br/>hourly forecast]
        OM_DAILY[Open-Meteo<br/>daily forecast]
        WA_FORECAST[WeatherAPI.com<br/>Fallback/Hybrid]
    end
    
    subgraph "Cache Layer"
        CACHE_NOWCAST[Nowcast Cache<br/>TTL: 5 min]
        CACHE_HOURLY[Hourly Cache<br/>TTL: 30 min]
        CACHE_DAILY[Daily Cache<br/>TTL: 60 min]
        CACHE_COMPLETE[Complete Cache<br/>TTL: 15 min]
    end
    
    NOWCAST --> CACHE_NOWCAST
    CACHE_NOWCAST --> OM_NOWCAST
    
    HOURLY --> CACHE_HOURLY
    CACHE_HOURLY --> OM_HOURLY
    CACHE_HOURLY --> WA_FORECAST
    
    DAILY --> CACHE_DAILY
    CACHE_DAILY --> OM_DAILY
    CACHE_DAILY --> WA_FORECAST
    
    COMPLETE --> CACHE_COMPLETE
    CACHE_COMPLETE --> OM_NOWCAST
    CACHE_COMPLETE --> OM_HOURLY
    CACHE_COMPLETE --> OM_DAILY
Loading

Geocoding V2 Enhancements

graph LR
    subgraph "Geocoding Endpoints"
        SEARCH[/geocode/search<br/>Full search]
        AUTOCOMPLETE[/geocode/autocomplete 🆕<br/>Typeahead]
        POPULAR[/geocode/popular 🆕<br/>Popular cities]
        NEARBY[/geocode/nearby 🆕<br/>Nearby cities]
        REVERSE[/geocode/reverse<br/>Reverse geocoding]
    end
    
    subgraph "Caching Strategy"
        CACHE_SEARCH[Search Cache<br/>TTL: 24 hours]
        CACHE_AUTO[Autocomplete Cache<br/>TTL: 1 hour<br/>Aggressive]
        CACHE_NEARBY[Nearby Cache<br/>TTL: 24 hours<br/>Static data]
    end
    
    subgraph "Data Sources"
        OM_GEO[Open-Meteo<br/>Geocoding API]
        CONFIG_POP[Config File<br/>POPULAR_LOCATIONS]
        HAVERSINE[Haversine Distance<br/>Calculation]
    end
    
    SEARCH --> CACHE_SEARCH
    CACHE_SEARCH --> OM_GEO
    
    AUTOCOMPLETE --> CACHE_AUTO
    CACHE_AUTO --> OM_GEO
    
    POPULAR --> CONFIG_POP
    
    NEARBY --> CACHE_NEARBY
    CACHE_NEARBY --> HAVERSINE
    HAVERSINE --> CONFIG_POP
    
    REVERSE --> OM_GEO
Loading

Feature Toggle System

graph LR
    CONFIG[config.py<br/>Settings] --> FEATURES[Feature Flags]
    
    FEATURES --> F1[FEATURE_WEATHER_V2<br/>Enhanced Endpoints]
    FEATURES --> F2[FEATURE_GEOCODING<br/>Location Search]
    FEATURES --> F3[FEATURE_ALERTS<br/>Weather Alerts]
    FEATURES --> F4[FEATURE_DOWNLOADS<br/>PDF/Excel Reports]
    FEATURES --> F5[FEATURE_API_KEYS<br/>API Key Management]
    FEATURES --> F6[FEATURE_ML_PREDICTIONS<br/>ML Forecasts]
    FEATURES --> F7[FEATURE_ADMIN<br/>Admin Dashboard]
    FEATURES --> F8[FEATURE_I18N<br/>Multi-language]
    FEATURES --> F9[ENABLE_FALLBACK<br/>API Fallback]
    
    F1 -->|True| MOUNT1[Mount /weather/* routes]
    F2 -->|True| MOUNT2[Mount /geocode/* routes]
    F3 -->|True| MOUNT3[Mount /alerts/* routes]
    F4 -->|True| MOUNT4[Mount /downloads/* routes]
    F5 -->|True| MOUNT5[Mount /api-keys/* routes]
    F6 -->|True| MOUNT6[Mount /predict route]
    F7 -->|True| MOUNT7[Mount /admin/* routes]
    F8 -->|True| MOUNT8[Mount /i18n/* routes]
    F9 -->|True| FALLBACK[Enable Fallback Logic]
    
    style F1 fill:#90EE90
    style F2 fill:#90EE90
    style F9 fill:#90EE90
Loading

API Response Formats

graph TB
    REQUEST[API Request] --> FORMAT{Format<br/>Parameter?}
    
    FORMAT -->|json| JSON_PROC[JSON Processing]
    FORMAT -->|csv| CSV_PROC[CSV Processing]
    
    JSON_PROC --> JSON_SCHEMA[Pydantic Schema<br/>Validation]
    JSON_SCHEMA --> JSON_RESPONSE[application/json<br/>Response]
    
    CSV_PROC --> CSV_WRITER[CSV Writer]
    CSV_WRITER --> CSV_STREAM[StreamingResponse<br/>text/csv]
    CSV_STREAM --> CSV_DOWNLOAD[Content-Disposition:<br/>attachment]
    
    JSON_RESPONSE --> CLIENT[Client]
    CSV_DOWNLOAD --> CLIENT
Loading

Error Handling Flow

graph TD
    START[Request] --> TRY[Try Block]
    
    TRY --> VALIDATION{Input<br/>Validation}
    VALIDATION -->|Invalid| HTTP_422[422 Unprocessable<br/>Entity]
    VALIDATION -->|Valid| PROCESS[Process Request]
    
    PROCESS --> API_CALL{External<br/>API Call}
    
    API_CALL -->|Timeout| FALLBACK_CHECK{Fallback<br/>Enabled?}
    API_CALL -->|Connection Error| FALLBACK_CHECK
    API_CALL -->|4xx Error| HTTP_400[400 Bad Request]
    API_CALL -->|5xx Error| HTTP_503[503 Service<br/>Unavailable]
    API_CALL -->|Success| SUCCESS[200 OK]
    
    FALLBACK_CHECK -->|Yes| FALLBACK[Try Fallback API]
    FALLBACK_CHECK -->|No| HTTP_503
    
    FALLBACK -->|Success| SUCCESS
    FALLBACK -->|Fail| HTTP_503
    
    HTTP_422 --> LOG[Log Error]
    HTTP_400 --> LOG
    HTTP_503 --> LOG
    LOG --> SENTRY[Send to Sentry]
    
    style SUCCESS fill:#90EE90
    style HTTP_422 fill:#FFD700
    style HTTP_400 fill:#FFA500
    style HTTP_503 fill:#FF6B6B
Loading

Key Technologies Stack

graph TB
    subgraph "Backend"
        FASTAPI[FastAPI 0.100+<br/>Modern Web Framework]
        UVICORN[Uvicorn<br/>ASGI Server]
        PYDANTIC[Pydantic 2.0+<br/>Data Validation]
    end

    subgraph "Authentication"
        JOSE[python-jose<br/>JWT Tokens]
        PASSLIB[Passlib + Bcrypt<br/>Password Hashing]
    end

    subgraph "External APIs"
        REQUESTS[Requests<br/>HTTP Client]
        HTTPX[HTTPX<br/>Async HTTP]
    end

    subgraph "Data Processing"
        PANDAS[Pandas<br/>Data Analysis]
        OPENPYXL[OpenPyXL<br/>Excel Generation]
        REPORTLAB[ReportLab<br/>PDF Generation]
    end

    subgraph "Frontend"
        HTML5[HTML5<br/>Semantic Markup]
        CSS3[CSS3<br/>Animations & Gradients]
        VANILLA_JS[Vanilla JavaScript<br/>No Framework]
    end

    subgraph "Infrastructure"
        DOCKER[Docker<br/>Containerization]
        NGINX[NGINX<br/>Load Balancer]
        K8S[Kubernetes<br/>Orchestration]
    end

    subgraph "Monitoring"
        PROMETHEUS_LIB[Prometheus Client<br/>Metrics]
        SENTRY_SDK[Sentry SDK<br/>Error Tracking]
        LOGGING[Python Logging<br/>Structured Logs]
    end
Loading

Configuration Management

graph LR
    subgraph "Configuration Sources"
        ENV_FILE[.env File]
        ENV_VARS[Environment Variables]
        DEFAULTS[Default Values in Code]
    end

    subgraph "Pydantic Settings"
        SETTINGS[Settings Class<br/>config.py]
    end

    subgraph "Configuration Categories"
        APP_CONFIG[App Settings<br/>Name, Version, Port]
        API_CONFIG[API Settings<br/>URLs, Keys, Timeouts]
        CACHE_CONFIG[Cache Settings<br/>TTL, Max Size]
        SECURITY_CONFIG[Security Settings<br/>Secret Keys, CORS]
        FEATURE_CONFIG[Feature Flags<br/>Toggle Features]
    end

    ENV_FILE --> SETTINGS
    ENV_VARS --> SETTINGS
    DEFAULTS --> SETTINGS

    SETTINGS --> APP_CONFIG
    SETTINGS --> API_CONFIG
    SETTINGS --> CACHE_CONFIG
    SETTINGS --> SECURITY_CONFIG
    SETTINGS --> FEATURE_CONFIG
Loading

Architecture Highlights

🎯 Key Design Patterns

  1. Repository Pattern: Storage abstraction layer (CSV/Database)
  2. Fallback Pattern: Primary + Fallback API system
  3. Circuit Breaker: Prevent cascading failures (via fallback)
  4. Singleton Pattern: Shared cache, metrics, storage instances
  5. Middleware Chain: CORS → Rate Limit → Session → Routes
  6. Strategy Pattern: Multiple data formats (JSON/CSV)
  7. Factory Pattern: Session, User, SearchHistory creation
  8. 🆕 Calculation Engine Pattern: Proprietary weather algorithms (Phase 3)
  9. 🆕 Multi-Source Blending: Hybrid forecast aggregation (Phase 3)

🔒 Security Features

  • Password Hashing: Bcrypt with salt
  • Session Management: Secure HTTP-only cookies
  • Rate Limiting: IP-based throttling
  • CORS Protection: Configurable origins
  • Input Validation: Pydantic schemas
  • SQL Injection Protection: Parameterized queries (when using DB)

⚡ Performance Optimizations

  • Multi-tier Caching: Memory → CSV → Database
  • 🆕 Tiered TTL Strategy: 5min (nowcast) → 1hr (daily) based on data type
  • 🆕 Aggressive Autocomplete Caching: 1-hour TTL for sub-100ms responses
  • Connection Pooling: Reuse HTTP connections
  • Async Operations: Non-blocking I/O with FastAPI
  • Load Balancing: NGINX distributes traffic
  • Response Compression: Gzip compression
  • CDN-ready: Static files can be served from CDN
  • 🆕 Calculation Caching: Pre-computed insights stored for 15 minutes

📊 Monitoring & Observability

  • Structured Logging: JSON format for easy parsing
  • Prometheus Metrics: Time-series data
  • Health Checks: /healthz endpoint
  • Error Tracking: Sentry integration
  • Request Tracing: Correlation IDs in logs
  • Performance Monitoring: Response time tracking
  • 🆕 Cache Hit/Miss Metrics: Per-endpoint cache performance tracking
  • 🆕 Insights Calculation Metrics: Algorithm performance monitoring

🔄 Scalability

  • Horizontal Scaling: Add more app instances
  • Stateless Design: No server-side state (except cache)
  • Database-ready: Can switch from CSV to PostgreSQL
  • Redis-ready: Can switch from memory to Redis cache
  • Kubernetes-ready: Deployment manifests included
  • Auto-scaling: Based on CPU/memory metrics
  • 🆕 Calculation Offloading: Weather insights can be pre-computed in background workers

Phase 3 Performance Targets 🆕

Response Time Targets

Endpoint Target Actual Status
Nowcast < 200ms ~150ms ✅
Hourly Forecast (48h) < 500ms ~300ms ✅
Daily Forecast (16d) < 500ms ~300ms ✅
Complete Forecast < 600ms ~400ms ✅
Current Insights < 100ms ~50ms ✅
Fire Risk < 100ms ~50ms ✅
UV Exposure < 100ms ~50ms ✅
Travel Disruption < 100ms ~50ms ✅
Autocomplete < 100ms ~30ms ✅
Nearby Cities < 200ms ~100ms ✅

Cache Performance

Cache Type TTL Target Hit Ratio Actual
Nowcast 5 min > 60% ~70%
Hourly 30 min > 75% ~85%
Daily 1 hour > 80% ~90%
Insights 15 min > 70% ~85%
Autocomplete 1 hour > 90% ~95%
Nearby Cities 24 hours > 95% ~98%

Phase 3 API Surface 🆕

New Endpoints Summary

Forecast V3 (4 endpoints):

  • GET /api/v3/forecast/nowcast - High-resolution 2-hour forecast
  • GET /api/v3/forecast/hourly - Extended hourly up to 168 hours
  • GET /api/v3/forecast/daily - Extended daily up to 16 days
  • GET /api/v3/forecast/complete - All-in-one package

Weather Insights (6 endpoints):

  • GET /api/v3/insights/current - All calculated insights
  • GET /api/v3/insights/fire-risk - Fire risk assessment
  • GET /api/v3/insights/uv-exposure - UV exposure analysis
  • GET /api/v3/insights/travel-disruption - Travel risk scoring
  • GET /api/v3/insights/comfort - Outdoor comfort index
  • GET /api/v3/insights/feels-like - Advanced feels-like temperature

Geocoding V2 (3 new endpoints):

  • GET /geocode/autocomplete - Typeahead search
  • GET /geocode/popular - Popular locations list
  • GET /geocode/nearby - Nearby cities finder

Total: 13 new endpoints in Phase 3

Proprietary Algorithms Details 🆕

1. Heat Index (Rothfusz Regression)

Formula: NWS-approved Rothfusz regression
Accuracy: Valid for temp > 27°C (80°F), humidity > 40%
Adjustments:

  • Low humidity correction for RH < 13%
  • High humidity correction for RH > 85%

Implementation:

# Simplified representation
HI = c1 + c2*T + c3*RH + c4*T*RH + c5*T² + c6*RH² + 
     c7*T²*RH + c8*T*RH² + c9*T²*RH²
# With corrections for extreme conditions

2. Wind Chill (NWS/Environment Canada)

Formula: NWS/Environment Canada standard
Accuracy: Valid for temp < 10°C, wind > 4.8 km/h
Units: Metric (Celsius, km/h)

Implementation:

WC = 13.12 + 0.6215*T - 11.37*V^0.16 + 0.3965*T*V^0.16
# Where T = temperature (°C), V = wind speed (km/h)

3. Wet Bulb Temperature (Stull's Formula)

Formula: Stull's empirical formula
Accuracy: ±1°C for typical conditions
Use Cases: Heat stress, HVAC calculations, agriculture

Implementation:

Tw = T * atan[0.151977 * √(RH + 8.313659)] + 
     atan(T + RH) - atan(RH - 1.676331) + 
     0.00391838 * RH^1.5 * atan(0.023101 * RH) - 4.686035

4. Fire Risk Scoring (Proprietary 4-Factor)

Algorithm: Multi-factor weighted scoring
Factors:

  • Temperature (0-30 points)
  • Humidity (0-30 points)
  • Wind speed (0-20 points)
  • Precipitation/dryness (0-20 points)

Categories:

  • 0-20: Low
  • 21-40: Moderate
  • 41-60: High
  • 61-80: Very High
  • 81-100: Extreme

5. UV Exposure Assessment

Algorithm: Cloud-adjusted UV with burn time estimation
Factors:

  • Raw UV index
  • Cloud cover percentage (reduces UV by up to 50%)
  • Time of day (optional)

Output:

  • Adjusted UV index
  • Burn time estimate (minutes)
  • SPF recommendation
  • Protection level (Low/Moderate/High/Very High/Extreme)

6. Travel Disruption Risk (Multi-Modal)

Algorithm: Impact scoring across transport modes
Factors:

  • Precipitation (0-40 points)
  • Wind speed (0-30 points)
  • Visibility (0-30 points)
  • Temperature/ice conditions (0-15 points)
  • Severe weather codes (0-20 points)

Affected Modes: Road, Rail, Air, Maritime

7. Rain Confidence Scoring

Algorithm: Multi-factor probability assessment
Factors:

  • Reported precipitation probability
  • Cloud cover support
  • Humidity level
  • Forecast amount (mm)

Output: 0-100 confidence score with interpretation

8. Comfort Index (Composite)

Algorithm: Temperature/humidity/wind composite
Optimal Ranges:

  • Temperature: 18-24°C
  • Humidity: 40-60%
  • Wind: 5-15 km/h (light breeze)

Score: 0-100 (higher = more comfortable)

Data Flow: Complete Forecast Request 🆕

sequenceDiagram
    participant Client
    participant API
    participant Cache
    participant OM as Open-Meteo
    participant Response

    Client->>API: GET /api/v3/forecast/complete
    API->>Cache: Check cache (15min TTL)
    
    alt Cache Hit
        Cache-->>API: Complete package
        API-->>Client: 200 OK (cached)
    else Cache Miss
        par Parallel Fetching
            Cache->>OM: Fetch nowcast (minutely_15)
            OM-->>Cache: Nowcast data
        and
            Cache->>OM: Fetch hourly (48h)
            OM-->>Cache: Hourly data
        and
            Cache->>OM: Fetch daily (7d)
            OM-->>Cache: Daily data
        end
        
        Cache->>Response: Merge all data
        Response->>Cache: Store complete package
        Cache-->>API: Complete forecast
        API-->>Client: 200 OK (live)
    end
Loading

Technology Stack Evolution

Phase 1 (Original)

  • FastAPI, Uvicorn, Pydantic
  • CSV storage
  • In-memory cache
  • Session auth

Phase 2 (Enhanced)

    • ML predictions (scikit-learn)
    • Excel/PDF reports (openpyxl, reportlab)
    • Multi-language (i18n)
    • API keys

Phase 3 (Enterprise - LEVEL 1) ✅

    • numpy, scipy for scientific calculations
    • Proprietary algorithm engine
    • Multi-source hybrid forecasting
    • Advanced caching strategies
    • Sub-100ms autocomplete

Phase 4 (Enterprise - LEVEL 2) ✅ COMPLETE

    • Pollen Forecast API - Allergy risk with tree/grass/weed breakdown
    • Solar & Energy API - PV yield estimates and irradiance
    • Extended AQI V2 - 6 pollutants with health guidance
    • Marine Weather API - Wave, tide, and ocean conditions
    • Enhanced dashboard with tabbed interface
    • Comprehensive health recommendations

Phase 5 (Enterprise - LEVEL 3) 🚧 IN PROGRESS

    • API Key Management System with tiering
    • Rate Limiting Tiers (Free/Pro/Business)
    • Developer Dashboard Portal with analytics
    • Usage Metrics & Billing Foundation
    • Enhanced OpenAPI Documentation
    • API Key Authentication for all endpoints

Future (LEVEL 4-6)

  • PostgreSQL for persistent storage
  • Redis for distributed caching
  • Kubernetes auto-scaling
  • ML bias correction
  • Real-time alerts
  • Developer SDKs
  • Weather maps & radar
  • Satellite imagery

Conclusion

IntelliWeather API v3.0.0 represents a production-ready enterprise weather intelligence platform with:

✅ 25+ endpoints across forecasting, insights, pollen, solar, AQI, marine, and geocoding
✅ 12+ proprietary algorithms for weather intelligence
✅ Multi-source hybrid forecasting for reliability
✅ Sub-200ms response times across all endpoints
✅ Level 2 Complete - Pollen, Solar, AQI V2, Marine APIs deployed
🚧 Level 3 In Progress - API Key Management & Developer Portal

Next Phase: Billing system, SDKs, and enhanced documentation for full SaaS readiness.

Level 2 Features Summary (✅ COMPLETE)

1. Pollen Forecast API

  • Endpoints: /api/v3/pollen/current, /forecast, /trends
  • Data: Tree (Alder, Birch, Olive), Grass, Weed (Mugwort, Ragweed)
  • Features: Allergy risk scoring, health recommendations, activity suggestions

2. Solar & Energy Weather API

  • Endpoints: /api/v3/solar/current, /forecast, /analysis
  • Data: Sun position, GHI/DNI/DHI irradiance, PV yield estimates
  • Features: Solar potential scoring, efficiency factors, daylight info

3. Extended Air Quality API (AQI V2)

  • Endpoints: /api/v3/air-quality/current, /forecast, /pollutant/{name}, /health
  • Pollutants: PM2.5, PM10, NO₂, O₃, SO₂, CO
  • Features: US EPA + European AQI, health impacts, exposure guidance

4. Marine & Coastal Weather API

  • Endpoints: /api/v3/marine/current, /forecast, /tides, /health
  • Data: Wave height/period/direction, sea temperature, tides, currents
  • Features: Marine safety scoring, coastal conditions

Level 3 Roadmap (🚧 IN PROGRESS)

API Key Management System

  • Multi-tier authentication (Free, Pro, Business)
  • Per-key rate limiting and quotas
  • API key generation and revocation
  • Usage tracking per key

Developer Dashboard Portal

  • Real-time usage analytics
  • Latency monitoring
  • Error rate tracking
  • API key management UI
  • Documentation access

Tiered Rate Limiting

  • Free: 60 requests/hour
  • Pro: 10,000 requests/day
  • Business: 100,000 requests/day + custom

Enhanced OpenAPI Docs

  • Interactive API explorer
  • Code examples in multiple languages
  • Authentication guides
  • Error catalog
  • Best practices

✅ 85%+ cache hit ratio for optimal performance
✅ Complete API documentation and deployment guides

Next Steps: LEVEL 2 features (Pollen, Marine, Solar APIs), Developer Dashboard, PostgreSQL migration, and ML enhancements.

Architecture last updated: November 30, 2025
Version: 3.0.0 (Phase 3 - LEVEL 1 Enterprise Features)