diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
new file mode 100644
index 0000000..1058619
--- /dev/null
+++ b/.github/workflows/ci-cd.yml
@@ -0,0 +1,236 @@
+# IntelliWeather CI/CD Pipeline
+# Runs tests, builds Docker image, and optionally deploys to Kubernetes
+
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [main, develop]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  # ==================== LINT & TEST ====================
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pytest pytest-cov pytest-asyncio flake8 black mypy
+      
+      - name: Lint with flake8
+        run: |
+          # Stop the build if there are Python syntax errors or undefined names
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          # Exit-zero treats all errors as warnings
+          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=120 --statistics
+        continue-on-error: true
+      
+      - name: Check formatting with black
+        run: black --check --diff . || true
+        continue-on-error: true
+      
+      - name: Type check with mypy
+        run: mypy --ignore-missing-imports . || true
+        continue-on-error: true
+      
+      - name: Run tests
+        run: |
+          pytest tests/ -v --cov=. --cov-report=xml --cov-report=term-missing
+        env:
+          DEBUG: "true"
+      
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+
+  # ==================== BUILD DOCKER IMAGE ====================
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      contents: read
+      packages: write
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      
+      - name: Log in to Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=
+      
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64
+
+  # ==================== SECURITY SCAN ====================
+  security:
+    name: Security Scan
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      security-events: write
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
+          format: 'sarif'
+          output: 'trivy-results.sarif'
+        continue-on-error: true
+      
+      - name: Upload Trivy scan results
+        uses: github/codeql-action/upload-sarif@v2
+        with:
+          sarif_file: 'trivy-results.sarif'
+        continue-on-error: true
+
+  # ==================== DEPLOY TO STAGING ====================
+  deploy-staging:
+    name: Deploy to Staging
+    runs-on: ubuntu-latest
+    needs: [build, security]
+    permissions:
+      contents: read
+    if: github.ref == 'refs/heads/develop'
+    environment: staging
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up kubectl
+        uses: azure/setup-kubectl@v3
+      
+      - name: Configure kubectl
+        run: |
+          mkdir -p ~/.kube
+          echo "${{ secrets.KUBE_CONFIG_STAGING }}" | base64 -d > ~/.kube/config
+        if: ${{ secrets.KUBE_CONFIG_STAGING != '' }}
+      
+      - name: Deploy to staging
+        run: |
+          if [ -f ~/.kube/config ]; then
+            kubectl set image deployment/intelliweather \
+              intelliweather=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} \
+              --namespace=staging || echo "Kubectl deployment skipped (no cluster configured)"
+          else
+            echo "Staging deployment skipped (no KUBE_CONFIG_STAGING secret)"
+          fi
+
+  # ==================== DEPLOY TO PRODUCTION ====================
+  deploy-production:
+    name: Deploy to Production
+    runs-on: ubuntu-latest
+    needs: [build, security]
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: production
+    permissions:
+      contents: read
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Set up kubectl
+        uses: azure/setup-kubectl@v3
+      
+      - name: Configure kubectl
+        run: |
+          mkdir -p ~/.kube
+          echo "${{ secrets.KUBE_CONFIG_PRODUCTION }}" | base64 -d > ~/.kube/config
+        if: ${{ secrets.KUBE_CONFIG_PRODUCTION != '' }}
+      
+      - name: Deploy to production
+        run: |
+          if [ -f ~/.kube/config ]; then
+            # Extract version from tag
+            VERSION=${GITHUB_REF#refs/tags/}
+            
+            # Deploy using Helm
+            helm upgrade --install intelliweather ./helm/intelliweather \
+              --namespace=production \
+              --set image.tag=$VERSION \
+              --wait --timeout=5m || echo "Helm deployment skipped"
+          else
+            echo "Production deployment skipped (no KUBE_CONFIG_PRODUCTION secret)"
+          fi
+
+  # ==================== NOTIFY ====================
+  notify:
+    name: Notify
+    runs-on: ubuntu-latest
+    needs: [test, build]
+    if: always()
+    permissions: {}
+    
+    steps:
+      - name: Notify on success
+        if: needs.test.result == 'success' && needs.build.result == 'success'
+        run: |
+          echo "✅ Pipeline succeeded!"
+          echo "Tests: ${{ needs.test.result }}"
+          echo "Build: ${{ needs.build.result }}"
+      
+      - name: Notify on failure
+        if: needs.test.result == 'failure' || needs.build.result == 'failure'
+        run: |
+          echo "❌ Pipeline failed!"
+          echo "Tests: ${{ needs.test.result }}"
+          echo "Build: ${{ needs.build.result }}"
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..98e35ba
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment variables
+.env
+.env.local
+
+# Logs
+*.log
+
+# Data directory (CSV storage)
+data/
+
+# Test coverage
+htmlcov/
+.coverage
+.pytest_cache/
+
+# Database files (generated)
+*.db
+weather.db
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..678bc4c
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,254 @@
+# Changelog
+
+All notable changes to IntelliWeather API will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.1] - 2024-11-29
+
+### Fixed - Main Branch Compatibility
+
+#### Backend Compatibility
+- **SQLite Integration**: Merged SQLite database functions from main branch for seamless compatibility
+- **Graceful Fallbacks**: All Phase 2/3 modules now load conditionally with graceful fallbacks
+- **Error Handling**: Improved try/catch blocks for all module imports to prevent crashes
+- **Database Initialization**: Combined SQLite init with CSV storage initialization
+
+#### Frontend Fixes
+- **Theme Manager**: Added null checks for `window.themeManager` to prevent undefined errors
+- **Script Loading**: Fixed race condition in theme initialization
+
+#### Documentation
+- Updated CHANGELOG with compatibility fixes
+- Confirmed all 27 tests pass
+
+### Changed
+- `app.py` now integrates SQLite (main branch) with in-memory caching (Phase 2) seamlessly
+- Server startup message matches main branch output for consistency
+
+## [3.0.0] - 2024-01-16
+
+### Added - Phase 3 Features
+
+#### Professional UI Redesign
+- **New Header**: Fixed navigation bar with logo, nav links, theme toggle, and auth buttons
+- **New Footer**: Full footer with branding, social links, product/resource/company columns
+- **Dark/Light Mode**: System-aware theme with smooth transitions and localStorage persistence
+- **Advanced Animations**: Hardware-accelerated animations using CSS transforms and opacity
+- **Motion Controller**: JavaScript animation sequencing system with cancellation support
+- **Skeleton Loaders**: Shimmer loading states during data fetches
+- **Reduced Motion Support**: Respects `prefers-reduced-motion` system preference
+
+#### Animation System
+- `static/css/animations.css` - Comprehensive animation library
+- `static/css/theme.css` - Theme system with CSS custom properties
+- `static/js/motion.js` - MotionController for coordinated animations
+- `static/js/theme.js` - ThemeManager for dark/light mode
+- `static/js/search.js` - Enhanced search with autosuggest and keyboard navigation
+- Design tokens for consistent timing (durations, easings, staggers)
+
+#### Kubernetes Deployment
+- `k8s/deployment.yaml` - Deployment, Service, Ingress, HPA, PVC, PDB manifests
+- `k8s/secrets-template.yaml` - Secrets template (never commit actual secrets!)
+- `k8s/local/local-setup.sh` - Script for local kind/minikube development
+- Resource limits and requests for production stability
+- Health probes (liveness, readiness)
+- HorizontalPodAutoscaler for auto-scaling
+
+#### Helm Chart
+- `helm/intelliweather/Chart.yaml` - Chart metadata
+- `helm/intelliweather/values.yaml` - Configurable values
+- Redis and PostgreSQL as optional dependencies
+- Support for custom annotations, resources, and environment variables
+
+#### Observability Stack
+- `monitoring/prometheus.yml` - Prometheus scrape configuration
+- `monitoring/alert_rules.yml` - Alertmanager rules (high error rate, latency, cache ratio)
+- `monitoring/grafana-dashboard.json` - Pre-built Grafana dashboard
+- Prometheus metrics exposed at `/metrics/prometheus`
+- Metrics: request rate, latency histogram, cache hit ratio, active sessions
+
+#### Notifications Module
+- `notifications/__init__.py` - Pluggable notification system
+- **EmailBackend**: SMTP and SendGrid support
+- **SMSBackend**: Twilio integration with mock fallback
+- **WebPushBackend**: Web push notifications (stub)
+- **InAppBackend**: In-app notifications stored in memory/DB
+- Exponential backoff retry for failed deliveries
+- Notification templates for weather alerts, account events
+
+#### CI/CD Pipeline
+- `.github/workflows/ci-cd.yml` - GitHub Actions workflow
+- Jobs: lint, test, build Docker image, security scan, deploy
+- Multi-platform builds (amd64, arm64)
+- Conditional deployment to staging/production
+- Code coverage upload to Codecov
+
+#### Documentation
+- `docs/DEPLOYMENT.md` - Comprehensive deployment guide
+- `docs/CDN.md` - Cloudflare and Fastly integration guides
+- Edge caching examples with Workers/Compute@Edge
+- Cache header configuration
+
+### Changed
+- Version bump to 3.0.0
+- Updated `config.py` with Phase 3 feature flags
+- Enhanced `requirements.txt` with observability dependencies
+- Professional UI design comparable to AccuWeather
+
+### Configuration
+New environment variables:
+- `FEATURE_NOTIFICATIONS` - Enable notifications (default: true)
+- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD` - SMTP settings
+- `SENDGRID_API_KEY` - SendGrid API key
+- `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER` - Twilio SMS
+- `VAPID_PRIVATE_KEY`, `VAPID_PUBLIC_KEY` - Web push keys
+- `FEATURE_BACKGROUND_JOBS` - Enable job queue (default: true)
+- `JOB_QUEUE_BACKEND` - Queue backend (memory/redis/rq/celery)
+- `POSTGRES_URL` - PostgreSQL connection URL
+- `PROMETHEUS_ENABLED` - Enable Prometheus metrics
+- `FEATURE_ANALYTICS`, `FEATURE_REFERRALS`, `FEATURE_SHAREABLE_LINKS` - Growth features
+- `FREE_TIER_REQUESTS_PER_DAY`, `PRO_TIER_REQUESTS_PER_DAY` - Access tiers
+- `FEATURE_ANIMATIONS`, `REDUCED_MOTION_DEFAULT` - Animation settings
+
+---
+
+## [2.0.0] - 2024-01-15
+
+### Added - Phase 2 Features
+
+#### Weather Endpoints V2
+- `GET /weather/hourly` - Hourly forecast (24/48/72 hours) with CSV export
+- `GET /weather/daily` - Daily forecast (7/14 days) with CSV export
+- `GET /weather/historical` - Historical weather data with date range validation
+- Support for metric/imperial unit conversion
+- Pydantic response models with OpenAPI examples
+
+#### Geocoding
+- `GET /geocode/search` - Location search by name with caching
+- `GET /geocode/reverse` - Reverse geocoding (coordinates to location)
+- Result normalization and deduplication
+- 24-hour cache TTL for geocoding results
+
+#### Weather Alerts
+- `GET /alerts` - Active weather alerts for a location
+- Alert generation based on weather conditions (thunderstorms, high winds, etc.)
+- `POST /alerts/refresh` - Admin endpoint to refresh alerts cache
+- 15-minute cache TTL for alerts
+
+#### Downloadable Reports
+- `GET /weather/download` - Download weather reports
+- PDF report generation with temperature charts
+- Excel report generation with formatted sheets
+- Report caching for 30 minutes
+
+#### API Key Management
+- `POST /apikeys` - Create new API key
+- `GET /apikeys` - List user's API keys
+- `DELETE /apikeys/{key_id}` - Revoke API key
+- Per-key rate limiting
+- Secure key hashing (only prefix stored)
+
+#### ML Predictions
+- `GET /predict/nextday` - Next-day temperature prediction
+- Simple linear regression model on historical data
+- `GET /predict/model/info` - Model metadata
+- `POST /predict/model/train` - Trigger model training
+
+#### Internationalization (i18n)
+- `GET /i18n/languages` - Supported languages
+- `GET /i18n/translations` - All translations for a language
+- `GET /i18n/translate` - Single key translation
+- `GET /i18n/weather-description` - Localized weather descriptions
+- Supported: English, Hindi, Urdu, Arabic, Spanish
+
+#### Admin Dashboard
+- `GET /admin/dashboard` - Admin dashboard HTML page
+- `GET /admin/api/stats` - Dashboard statistics
+- `GET /admin/api/health` - System health check
+- `GET /admin/api/metrics` - Detailed metrics
+- `POST /admin/api/cache/clear` - Clear application cache
+
+### Changed
+- Updated FastAPI app with OpenAPI tags for better documentation
+- Feature flags for all Phase 2 features in config.py
+- Enhanced error responses with proper HTTP status codes
+- Improved OpenAPI documentation with examples
+
+### Configuration
+New environment variables:
+- `FEATURE_WEATHER_V2` - Enable Weather V2 endpoints (default: true)
+- `FEATURE_GEOCODING` - Enable geocoding endpoints (default: true)
+- `FEATURE_ALERTS` - Enable alerts endpoints (default: true)
+- `FEATURE_DOWNLOADS` - Enable download endpoints (default: true)
+- `FEATURE_API_KEYS` - Enable API key management (default: true)
+- `FEATURE_ML_PREDICTION` - Enable ML predictions (default: true)
+- `FEATURE_ADMIN_DASHBOARD` - Enable admin dashboard (default: true)
+- `FEATURE_I18N` - Enable internationalization (default: true)
+- `GEOCODE_CACHE_TTL_SECONDS` - Geocoding cache TTL (default: 86400)
+- `API_KEY_RATE_LIMIT_DEFAULT` - Default API key rate limit (default: 100)
+- `ML_HISTORICAL_DAYS` - Historical days for ML training (default: 365)
+
+---
+
+## [1.0.0] - 2024-01-14
+
+### Added - Phase 1 Features
+
+#### Core Backend
+- `config.py` - Centralized configuration with pydantic-settings
+- `storage.py` - CSV-backed storage for users, sessions, search history
+- `cache.py` - In-memory caching with TTL and background cleanup
+- `logging_config.py` - Structured JSON logging
+
+#### Authentication & Sessions
+- `session_middleware.py` - Server-side sessions with UUID tokens
+- `routes/auth.py` - Signup, login, logout endpoints
+- Bcrypt password hashing
+- Secure session cookies (httpOnly, SameSite)
+
+#### Rate Limiting
+- `middleware/rate_limiter.py` - Sliding window rate limiter
+- Configurable requests per minute per IP
+- 429 responses with Retry-After headers
+
+#### Health & Metrics
+- `/healthz` - Health check endpoint
+- `/metrics` - Application metrics
+- `/metrics/prometheus` - Prometheus format metrics
+
+#### Weather Endpoints
+- `GET /weather` - Current weather with caching
+- `GET /hourly` - Hourly forecast
+- `GET /forecast` - 7-day forecast
+- `GET /aqi-alerts` - Air quality and alerts
+
+#### UI
+- Royal theme with glassmorphism design
+- Animated starfield background
+- Floating gradient orbs
+- Aurora effect animation
+- Crown decoration
+- Dark purple (#4a1c6e) and gold (#d4af37) color scheme
+- Playfair Display typography
+- Responsive design
+
+#### Docker & Deployment
+- `Dockerfile` - Multi-stage build
+- `docker-compose.yml` - Multi-container setup with scaling
+- `nginx.conf` - Load balancer configuration
+
+#### Documentation
+- `README.md` - Comprehensive documentation
+- `QA.md` - Testing checklist
+- `demo_script.md` - Presentation guide
+
+---
+
+## [0.1.0] - Initial Release
+
+### Added
+- Basic FastAPI application
+- Static file serving
+- Open-Meteo API integration
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..5e83c99
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,68 @@
+# IntelliWeather API Dockerfile
+# Multi-stage build for production-ready image
+
+# ==================== BUILD STAGE ====================
+FROM python:3.11-slim as builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create virtual environment
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+
+# ==================== PRODUCTION STAGE ====================
+FROM python:3.11-slim as production
+
+WORKDIR /app
+
+# Create non-root user for security
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+
+# Copy virtual environment from builder
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Copy application code
+COPY --chown=appuser:appgroup . .
+
+# Create data directory
+RUN mkdir -p /app/data && chown -R appuser:appgroup /app/data
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    APP_HOST=0.0.0.0 \
+    APP_PORT=8000 \
+    DATA_DIR=/app/data
+
+# Expose port
+EXPOSE 8000
+
+# Switch to non-root user
+USER appuser
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz')" || exit 1
+
+# Run with Gunicorn for production
+# Using multiple workers for better performance
+CMD ["gunicorn", "app:app", \
+     "--bind", "0.0.0.0:8000", \
+     "--workers", "4", \
+     "--worker-class", "uvicorn.workers.UvicornWorker", \
+     "--access-logfile", "-", \
+     "--error-logfile", "-", \
+     "--capture-output", \
+     "--enable-stdio-inheritance"]
diff --git a/QA.md b/QA.md
new file mode 100644
index 0000000..2865b90
--- /dev/null
+++ b/QA.md
@@ -0,0 +1,293 @@
+# 🧪 QA Checklist - IntelliWeather API
+
+This document provides a comprehensive QA checklist for testing all features of the IntelliWeather API.
+
+---
+
+## 1. User Authentication
+
+### 1.1 Signup
+- [ ] **Valid signup**: Create account with valid email, username, and strong password
+- [ ] **Duplicate email**: Attempt signup with existing email → should fail
+- [ ] **Duplicate username**: Attempt signup with existing username → should fail
+- [ ] **Weak password**: Attempt signup with password < 8 chars → should fail
+- [ ] **Invalid email**: Attempt signup with invalid email format → should fail
+- [ ] **Session created**: After signup, session cookie should be set
+
+```bash
+# Test signup
+curl -X POST http://localhost:8000/auth/signup \
+  -H "Content-Type: application/json" \
+  -d '{"username":"testuser","email":"test@example.com","password":"TestPass123"}' \
+  -c cookies.txt -v
+```
+
+### 1.2 Login
+- [ ] **Valid login**: Login with correct credentials
+- [ ] **Invalid email**: Login with non-existent email → should fail
+- [ ] **Invalid password**: Login with wrong password → should fail
+- [ ] **Session created**: After login, session cookie should be set
+
+```bash
+# Test login
+curl -X POST http://localhost:8000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"TestPass123"}' \
+  -c cookies.txt -v
+```
+
+### 1.3 Logout
+- [ ] **Valid logout**: Logout invalidates session
+- [ ] **Cookie cleared**: Session cookie should be removed
+
+```bash
+# Test logout
+curl -X POST http://localhost:8000/auth/logout \
+  -b cookies.txt -v
+```
+
+### 1.4 Session Management
+- [ ] **Session persists**: Authenticated requests work with session cookie
+- [ ] **Session timeout**: Session expires after configured timeout
+- [ ] **Protected endpoints**: `/auth/me` requires authentication
+
+```bash
+# Test protected endpoint
+curl http://localhost:8000/auth/me \
+  -b cookies.txt
+```
+
+---
+
+## 2. Weather API Endpoints
+
+### 2.1 Current Weather (`/weather`)
+- [ ] **Valid request**: Get weather for valid coordinates
+- [ ] **Cache miss**: First request fetches from API (check logs)
+- [ ] **Cache hit**: Second request uses cache (check logs)
+- [ ] **Invalid coordinates**: Handle edge cases (extreme lat/lon)
+
+```bash
+# Test weather endpoint
+curl "http://localhost:8000/weather?lat=40.71&lon=-74.01"
+
+# Check for cache behavior
+curl "http://localhost:8000/weather?lat=40.71&lon=-74.01"  # Should be cache hit
+```
+
+### 2.2 Hourly Forecast (`/hourly`)
+- [ ] **Returns 24 hours**: Response contains 24 hourly entries
+- [ ] **Cache behavior**: Check cache hit/miss in logs
+
+```bash
+curl "http://localhost:8000/hourly?lat=40.71&lon=-74.01"
+```
+
+### 2.3 Daily Forecast (`/forecast`)
+- [ ] **Returns 7 days**: Response contains 7 daily entries
+- [ ] **Contains all fields**: max_temp, min_temp, sunrise, sunset, etc.
+
+```bash
+curl "http://localhost:8000/forecast?lat=40.71&lon=-74.01"
+```
+
+### 2.4 AQI & Alerts (`/aqi-alerts`)
+- [ ] **Returns AQI data**: Response contains US AQI values
+- [ ] **Shorter cache TTL**: AQI cached for 30 minutes (not 1 hour)
+
+```bash
+curl "http://localhost:8000/aqi-alerts?lat=40.71&lon=-74.01"
+```
+
+---
+
+## 3. Caching System
+
+### 3.1 In-Memory Cache
+- [ ] **Cache set/get**: Values stored and retrieved correctly
+- [ ] **TTL expiration**: Cached items expire after TTL
+- [ ] **Cache stats**: `/metrics` shows hit/miss counts
+
+```bash
+# Check cache stats
+curl http://localhost:8000/metrics | jq '.cache'
+```
+
+### 3.2 Cache Hit/Miss Demonstration
+1. Clear the cache (restart the server)
+2. Make first request → logs show "CACHE MISS"
+3. Make same request → logs show "CACHE HIT"
+4. Wait for TTL to expire
+5. Make same request → logs show "CACHE MISS" again
+
+---
+
+## 4. Rate Limiting
+
+### 4.1 Within Limits
+- [ ] **Requests allowed**: First 60 requests succeed
+- [ ] **Headers present**: `X-RateLimit-Limit` and `X-RateLimit-Remaining` in response
+
+```bash
+# Check rate limit headers
+curl -v "http://localhost:8000/weather?lat=40.71&lon=-74.01" 2>&1 | grep -i ratelimit
+```
+
+### 4.2 Exceeding Limits
+- [ ] **429 response**: Returns "Too Many Requests" after limit
+- [ ] **Retry-After header**: Response includes when to retry
+
+```bash
+# Rapid requests to trigger rate limit
+for i in {1..70}; do
+  curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:8000/weather?lat=40.71&lon=-74.01"
+done
+```
+
+---
+
+## 5. Health & Metrics
+
+### 5.1 Health Check (`/healthz`)
+- [ ] **Returns healthy**: All components pass checks
+- [ ] **Storage check**: Storage is writable
+- [ ] **Cache check**: Cache is operational
+- [ ] **Session middleware**: Middleware is loaded
+
+```bash
+curl http://localhost:8000/healthz | jq
+```
+
+### 5.2 Metrics (`/metrics`)
+- [ ] **Counters present**: total_requests, cache_hits, cache_misses
+- [ ] **Active sessions**: Shows count of active sessions
+- [ ] **Uptime**: Shows application uptime
+
+```bash
+curl http://localhost:8000/metrics | jq
+```
+
+### 5.3 Prometheus Format (`/metrics/prometheus`)
+- [ ] **Valid format**: Output matches Prometheus text format
+
+```bash
+curl http://localhost:8000/metrics/prometheus
+```
+
+---
+
+## 6. Docker & Load Balancing
+
+### 6.1 Docker Build
+- [ ] **Build succeeds**: `docker build -t intelliweather .`
+- [ ] **Image runs**: `docker run -p 8000:8000 intelliweather`
+
+### 6.2 Docker Compose
+- [ ] **All services start**: `docker-compose up -d`
+- [ ] **Multiple replicas**: `docker-compose up -d --scale app=3`
+- [ ] **Health checks pass**: All containers healthy
+
+```bash
+docker-compose up -d --scale app=3
+docker-compose ps
+```
+
+### 6.3 Load Balancing
+- [ ] **Requests distributed**: Check NGINX logs for distribution
+- [ ] **Failover works**: Stop one replica, requests continue
+
+```bash
+# Test load balancing
+for i in {1..10}; do
+  curl -s http://localhost/weather?lat=40.71&lon=-74.01 > /dev/null
+done
+
+# Check NGINX logs
+docker-compose logs nginx | tail -20
+```
+
+---
+
+## 7. Security
+
+### 7.1 Authentication
+- [ ] **Passwords hashed**: Passwords stored with bcrypt
+- [ ] **Session cookies secure**: httpOnly, SameSite flags set
+
+### 7.2 Input Validation
+- [ ] **Email validation**: Invalid emails rejected
+- [ ] **Password requirements**: Weak passwords rejected
+- [ ] **SQL injection**: Special characters handled safely
+
+### 7.3 CORS
+- [ ] **Headers present**: CORS headers in responses
+
+---
+
+## 8. Error Handling
+
+### 8.1 API Errors
+- [ ] **Invalid parameters**: Returns 422 with details
+- [ ] **External API failure**: Returns 500 with message
+- [ ] **Not found**: Returns 404 for invalid routes
+
+```bash
+# Test invalid parameters
+curl "http://localhost:8000/weather?lat=invalid&lon=-74.01"
+
+# Test non-existent endpoint
+curl http://localhost:8000/nonexistent
+```
+
+---
+
+## 9. Performance
+
+### 9.1 Response Times
+- [ ] **Cache hit < 50ms**: Cached responses are fast
+- [ ] **API call < 2s**: External API calls complete quickly
+
+```bash
+# Measure response time
+time curl "http://localhost:8000/weather?lat=40.71&lon=-74.01"
+```
+
+### 9.2 Concurrent Requests
+- [ ] **Handles 100 concurrent**: No crashes or errors
+
+```bash
+# Using Apache Bench (if available)
+ab -n 100 -c 10 "http://localhost:8000/weather?lat=40.71&lon=-74.01"
+```
+
+---
+
+## Checklist Summary
+
+| Category | Tests | Status |
+|----------|-------|--------|
+| Authentication | 10 | ⬜ |
+| Weather API | 8 | ⬜ |
+| Caching | 4 | ⬜ |
+| Rate Limiting | 4 | ⬜ |
+| Health & Metrics | 6 | ⬜ |
+| Docker | 6 | ⬜ |
+| Security | 5 | ⬜ |
+| Error Handling | 3 | ⬜ |
+| Performance | 3 | ⬜ |
+| **Total** | **49** | ⬜ |
+
+---
+
+## Test Execution
+
+```bash
+# Run all unit tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=. --cov-report=html
+
+# Run specific test file
+pytest tests/test_modules.py -v
+```
diff --git a/QA_PHASE2.md b/QA_PHASE2.md
new file mode 100644
index 0000000..f446bdd
--- /dev/null
+++ b/QA_PHASE2.md
@@ -0,0 +1,283 @@
+# Phase 2 QA Checklist
+
+## Prerequisites
+- [ ] Python 3.10+ installed
+- [ ] Dependencies installed: `pip install -r requirements.txt`
+- [ ] Server running: `uvicorn app:app --reload`
+
+---
+
+## 1. Weather V2 Endpoints
+
+### 1.1 Hourly Forecast
+```bash
+# Get 24-hour forecast (JSON)
+curl "http://localhost:8000/weather/hourly?lat=40.7128&lon=-74.006&hours=24"
+
+# Get 48-hour forecast with imperial units
+curl "http://localhost:8000/weather/hourly?lat=40.7128&lon=-74.006&hours=48&units=imperial"
+
+# Download as CSV
+curl "http://localhost:8000/weather/hourly?lat=40.7128&lon=-74.006&format=csv" -o hourly.csv
+```
+- [ ] Returns hourly data points
+- [ ] Units conversion works (metric/imperial)
+- [ ] CSV download works
+- [ ] Cache hit on second request
+
+### 1.2 Daily Forecast
+```bash
+# Get 7-day forecast
+curl "http://localhost:8000/weather/daily?lat=40.7128&lon=-74.006&days=7"
+
+# Get 14-day forecast
+curl "http://localhost:8000/weather/daily?lat=40.7128&lon=-74.006&days=14"
+```
+- [ ] Returns daily data with sunrise/sunset
+- [ ] 14-day forecast works
+- [ ] Weather codes included
+
+### 1.3 Historical Data
+```bash
+# Get historical data
+curl "http://localhost:8000/weather/historical?lat=40.7128&lon=-74.006&start=2024-01-01&end=2024-01-07"
+
+# Invalid date range (>1 year)
+curl "http://localhost:8000/weather/historical?lat=40.7128&lon=-74.006&start=2022-01-01&end=2024-01-01"
+```
+- [ ] Historical data returns
+- [ ] Date validation works (rejects >365 days)
+- [ ] Error for invalid date range
+
+---
+
+## 2. Geocoding
+
+### 2.1 Location Search
+```bash
+# Search for a city
+curl "http://localhost:8000/geocode/search?q=London&limit=5"
+
+# Search with language
+curl "http://localhost:8000/geocode/search?q=Tokyo&lang=en"
+```
+- [ ] Returns location results with coordinates
+- [ ] Includes country, timezone, population
+- [ ] Cache hit on repeat search
+
+### 2.2 Reverse Geocoding
+```bash
+# Reverse geocode coordinates
+curl "http://localhost:8000/geocode/reverse?lat=51.5074&lon=-0.1278"
+```
+- [ ] Returns location info for coordinates
+- [ ] Includes timezone
+
+---
+
+## 3. Weather Alerts
+
+### 3.1 Get Alerts
+```bash
+# Get alerts for location
+curl "http://localhost:8000/alerts?lat=40.7128&lon=-74.006"
+```
+- [ ] Returns alerts array (may be empty if no severe weather)
+- [ ] Includes alert severity and descriptions
+- [ ] Cache works (15-minute TTL)
+
+### 3.2 Admin Refresh (requires auth)
+```bash
+# Refresh alerts (needs session cookie)
+curl -X POST "http://localhost:8000/alerts/refresh" -b "session_id=YOUR_SESSION"
+```
+- [ ] Requires authentication
+- [ ] Returns refresh count
+
+---
+
+## 4. Downloads
+
+### 4.1 PDF Report
+```bash
+# Download PDF report
+curl "http://localhost:8000/weather/download?lat=40.7128&lon=-74.006&type=pdf&range=daily&days=7" -o report.pdf
+```
+- [ ] PDF file downloads
+- [ ] Contains weather data
+- [ ] Report is cached
+
+### 4.2 Excel Report
+```bash
+# Download Excel report
+curl "http://localhost:8000/weather/download?lat=40.7128&lon=-74.006&type=excel&range=daily&days=7" -o report.xlsx
+```
+- [ ] Excel file downloads
+- [ ] Contains formatted data
+- [ ] Multiple sheets (Weather, Metadata)
+
+---
+
+## 5. API Keys
+
+### 5.1 Create API Key
+```bash
+# First, login to get session
+curl -X POST "http://localhost:8000/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"testpass"}' \
+  -c cookies.txt
+
+# Create API key
+curl -X POST "http://localhost:8000/apikeys" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Test Key","rate_limit":100}' \
+  -b cookies.txt
+```
+- [ ] Returns API key (only shown once)
+- [ ] Key has prefix `iw_live_`
+
+### 5.2 List Keys
+```bash
+curl "http://localhost:8000/apikeys" -b cookies.txt
+```
+- [ ] Returns list of user's keys
+- [ ] Shows usage statistics
+
+### 5.3 Use API Key
+```bash
+# Use key in header
+curl "http://localhost:8000/weather/hourly?lat=40.7128&lon=-74.006" \
+  -H "X-API-Key: iw_live_YOUR_KEY"
+
+# Use key in query param
+curl "http://localhost:8000/weather/hourly?lat=40.7128&lon=-74.006&apikey=iw_live_YOUR_KEY"
+```
+- [ ] API key authentication works
+- [ ] Rate limiting enforced per key
+
+---
+
+## 6. ML Prediction
+
+### 6.1 Get Prediction
+```bash
+curl "http://localhost:8000/predict/nextday?lat=40.7128&lon=-74.006"
+```
+- [ ] Returns predicted temperature
+- [ ] Includes confidence interval
+- [ ] Shows model version
+
+### 6.2 Model Info
+```bash
+curl "http://localhost:8000/predict/model/info"
+```
+- [ ] Returns model metadata
+- [ ] Shows if model is trained
+
+### 6.3 Train Model
+```bash
+curl -X POST "http://localhost:8000/predict/model/train?lat=40.7128&lon=-74.006"
+```
+- [ ] Model training completes
+- [ ] Model saved to data/models/
+
+---
+
+## 7. Internationalization
+
+### 7.1 Supported Languages
+```bash
+curl "http://localhost:8000/i18n/languages"
+```
+- [ ] Returns list: en, hi, ur, ar, es
+
+### 7.2 Get Translations
+```bash
+# English
+curl "http://localhost:8000/i18n/translations?lang=en"
+
+# Hindi
+curl "http://localhost:8000/i18n/translations?lang=hi"
+
+# Arabic
+curl "http://localhost:8000/i18n/translations?lang=ar"
+```
+- [ ] Returns translations for each language
+- [ ] Hindi text is correct
+- [ ] Arabic text is right-to-left
+
+### 7.3 Weather Description
+```bash
+curl "http://localhost:8000/i18n/weather-description?code=3&lang=es"
+```
+- [ ] Returns localized weather description
+
+---
+
+## 8. Admin Dashboard
+
+### 8.1 Dashboard Page
+```bash
+# Open in browser (requires admin login)
+open http://localhost:8000/admin/dashboard
+```
+- [ ] Dashboard renders
+- [ ] Shows statistics
+- [ ] Shows system health
+
+### 8.2 API Stats
+```bash
+curl "http://localhost:8000/admin/api/stats" -b cookies.txt
+```
+- [ ] Returns dashboard statistics
+- [ ] Requires admin auth
+
+### 8.3 System Health
+```bash
+curl "http://localhost:8000/admin/api/health" -b cookies.txt
+```
+- [ ] Shows storage status
+- [ ] Shows cache status
+- [ ] Shows API connectivity
+
+---
+
+## 9. Integration Tests
+
+### 9.1 Full User Flow
+1. [ ] Sign up new user
+2. [ ] Login
+3. [ ] Create API key
+4. [ ] Use API key to fetch weather
+5. [ ] Download report
+6. [ ] Get prediction
+7. [ ] Logout
+
+### 9.2 Cache Verification
+1. [ ] Make request (cache miss)
+2. [ ] Make same request (cache hit)
+3. [ ] Clear cache (admin)
+4. [ ] Make request (cache miss again)
+
+### 9.3 Rate Limiting
+1. [ ] Create API key with rate_limit=5
+2. [ ] Make 5 requests
+3. [ ] 6th request returns 429
+
+---
+
+## 10. Performance Checks
+
+- [ ] Response times < 500ms for cached requests
+- [ ] Response times < 2s for live API requests
+- [ ] Memory usage stable under load
+- [ ] No memory leaks in cache cleanup
+
+---
+
+## Sign-off
+
+| Tester | Date | Status |
+|--------|------|--------|
+|        |      |        |
diff --git a/QA_PHASE3.md b/QA_PHASE3.md
new file mode 100644
index 0000000..890c968
--- /dev/null
+++ b/QA_PHASE3.md
@@ -0,0 +1,329 @@
+# Phase 3 QA Checklist
+
+This document provides a comprehensive QA checklist for verifying all Phase 3 features.
+
+## Prerequisites
+
+- Docker installed
+- Node.js 18+ (for local development)
+- kubectl (for Kubernetes testing)
+- kind or minikube (for local k8s)
+
+## 1. Professional UI & Animations
+
+### Header
+- [ ] Logo displays correctly with icon and text
+- [ ] Navigation links are visible (Dashboard, Maps, Alerts, Historical, API Docs)
+- [ ] Theme toggle button works
+- [ ] Sign In / Get Started buttons visible
+- [ ] Header has blur backdrop effect
+- [ ] Header shadow appears on scroll
+
+### Footer
+- [ ] Logo in footer brand section
+- [ ] Social links display (Twitter, Facebook, Instagram, GitHub)
+- [ ] Product links column visible
+- [ ] Resources links column visible
+- [ ] Company links column visible
+- [ ] Copyright text with Open-Meteo attribution
+- [ ] Language selector present
+
+### Dark/Light Mode
+```bash
+# Test in browser console
+localStorage.setItem('intelliweather-theme', 'dark');
+location.reload();
+
+localStorage.setItem('intelliweather-theme', 'light');
+location.reload();
+```
+- [ ] Light mode: light background, dark text
+- [ ] Dark mode: dark background, light text
+- [ ] Theme persists across page reloads
+- [ ] Transition is smooth (no flash)
+
+### Animations
+- [ ] Page entrance animation (fade in + slide up)
+- [ ] Weather icon bounces smoothly
+- [ ] Shimmer effect on weather card
+- [ ] Hourly items animate in with stagger
+- [ ] Daily items animate in with stagger
+- [ ] Hover effects on cards (lift + shadow)
+- [ ] Tab transitions are smooth
+
+### Reduced Motion
+```bash
+# Test with system preference
+# macOS: System Preferences > Accessibility > Display > Reduce motion
+# Windows: Settings > Ease of Access > Display > Show animations
+```
+- [ ] Animations disabled when reduced motion enabled
+- [ ] App still functions correctly
+
+### Responsive Design
+- [ ] Desktop (1200px+): Full header nav visible
+- [ ] Tablet (768-1024px): Adjusted layout
+- [ ] Mobile (< 768px): Mobile menu toggle, stacked layout
+
+## 2. Kubernetes Deployment
+
+### Prerequisites
+```bash
+# Install kind
+curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
+chmod +x ./kind
+sudo mv ./kind /usr/local/bin/kind
+```
+
+### Local Setup
+```bash
+cd k8s/local
+chmod +x local-setup.sh
+
+# Full setup
+./local-setup.sh setup
+
+# Check status
+./local-setup.sh status
+
+# Port forward
+./local-setup.sh forward
+```
+
+- [ ] kind cluster creates successfully
+- [ ] Docker image builds
+- [ ] Image loads into kind
+- [ ] Pods start (Running state)
+- [ ] Service is accessible via port-forward
+- [ ] Health endpoint responds: `curl http://localhost:8080/healthz`
+
+### Manifest Verification
+```bash
+# Validate manifests
+kubectl apply -f k8s/deployment.yaml --dry-run=client
+
+# Check resources created
+kubectl get all -n intelliweather
+```
+- [ ] Deployment creates with 3 replicas
+- [ ] Service exposes port 80
+- [ ] Ingress configured (nginx class)
+- [ ] HPA configured (2-10 replicas)
+- [ ] PVC claims storage
+- [ ] PDB ensures availability
+
+### Cleanup
+```bash
+./local-setup.sh cleanup
+```
+- [ ] Cluster deleted successfully
+
+## 3. Helm Chart
+
+```bash
+cd helm/intelliweather
+
+# Lint chart
+helm lint .
+
+# Template rendering
+helm template intelliweather . --debug
+
+# Install (if kind cluster running)
+helm install intelliweather . --namespace intelliweather --create-namespace --dry-run
+```
+
+- [ ] Chart.yaml has correct version
+- [ ] values.yaml has all required fields
+- [ ] Template renders without errors
+- [ ] Dependencies declared (redis, postgresql optional)
+
+## 4. Monitoring & Observability
+
+### Prometheus Metrics
+```bash
+# Start application
+docker-compose up -d
+
+# Check metrics endpoint
+curl http://localhost:8000/metrics/prometheus
+```
+
+- [ ] `http_request_total` counter exists
+- [ ] `http_request_duration_seconds` histogram exists
+- [ ] `cache_hits_total` counter exists
+- [ ] `cache_misses_total` counter exists
+- [ ] `active_sessions` gauge exists
+
+### Prometheus Config
+- [ ] `monitoring/prometheus.yml` valid YAML
+- [ ] Scrape configs defined for intelliweather
+- [ ] Kubernetes SD config present
+
+### Grafana Dashboard
+```bash
+# Import dashboard
+# 1. Open Grafana UI
+# 2. Go to Dashboards > Import
+# 3. Upload monitoring/grafana-dashboard.json
+```
+
+- [ ] Dashboard JSON is valid
+- [ ] Panels load without errors
+- [ ] Request rate panel shows data
+- [ ] Latency panel shows data
+- [ ] Cache ratio gauge works
+
+### Alert Rules
+```bash
+# Validate alert rules
+promtool check rules monitoring/alert_rules.yml
+```
+
+- [ ] `HighErrorRate` alert defined
+- [ ] `HighLatency` alert defined
+- [ ] `LowCacheHitRatio` alert defined
+- [ ] `ServiceDown` alert defined
+
+## 5. Notifications Module
+
+### Email (Mock)
+```python
+# Test in Python shell
+from notifications import get_notification_service, NotificationType
+
+service = get_notification_service()
+result = await service.send(
+    NotificationType.EMAIL,
+    "test@example.com",
+    "Test Subject",
+    "Test body"
+)
+print(result.status)  # Should be 'sent' or 'failed'
+```
+
+- [ ] EmailBackend initializes
+- [ ] Mock send logs message
+- [ ] Real send works with SMTP configured
+- [ ] SendGrid send works with API key
+
+### SMS (Mock)
+```python
+result = await service.send(
+    NotificationType.SMS,
+    "+1234567890",
+    "Test Alert",
+    "Weather alert test"
+)
+```
+
+- [ ] SMSBackend initializes
+- [ ] Mock send logs message
+- [ ] Twilio send works with credentials
+
+### In-App
+```python
+result = await service.send(
+    NotificationType.IN_APP,
+    "user123",
+    "Notification Title",
+    "Notification body"
+)
+
+# Get notifications
+notifications = service.get_user_notifications("user123")
+print(len(notifications))
+```
+
+- [ ] InAppBackend always available
+- [ ] Notifications stored in memory
+- [ ] Get user notifications returns list
+- [ ] Mark as read works
+
+## 6. CI/CD Pipeline
+
+### GitHub Actions
+- [ ] `.github/workflows/ci-cd.yml` exists
+- [ ] Test job runs pytest
+- [ ] Build job builds Docker image
+- [ ] Security scan job exists
+- [ ] Deploy jobs conditional on branch/tag
+
+### Local Validation
+```bash
+# Test workflow syntax
+# Use act (https://github.com/nektos/act)
+act -n  # Dry run
+
+# Or validate YAML
+yamllint .github/workflows/ci-cd.yml
+```
+
+## 7. Documentation
+
+### DEPLOYMENT.md
+- [ ] File exists at `docs/DEPLOYMENT.md`
+- [ ] Docker quick start documented
+- [ ] Kubernetes deployment documented
+- [ ] Cloud provider examples (AWS, GCP, Azure)
+- [ ] Environment variables table
+- [ ] Health checks documented
+- [ ] Scaling documented
+- [ ] Troubleshooting section
+
+### CDN.md
+- [ ] File exists at `docs/CDN.md`
+- [ ] Cloudflare setup documented
+- [ ] Fastly setup documented
+- [ ] Cache headers explained
+- [ ] Edge worker example included
+- [ ] Best practices section
+
+## 8. Integration Tests
+
+### Full Flow
+```bash
+# Start application
+docker-compose up -d
+
+# Run integration tests
+pytest tests/ -v -m integration
+```
+
+### Manual Integration Test
+```bash
+# 1. Open browser to http://localhost:8000
+# 2. Wait for location detection
+# 3. Search for "London"
+# 4. Select result
+# 5. Verify weather updates
+# 6. Switch to Hourly tab
+# 7. Switch to 7-Day tab
+# 8. Toggle dark mode
+# 9. Check footer links
+```
+
+- [ ] Location detection works
+- [ ] Search returns results
+- [ ] Weather data displays
+- [ ] Tabs switch correctly
+- [ ] Theme toggle works
+- [ ] Footer displays
+
+## Summary
+
+| Feature | Status |
+|---------|--------|
+| Professional UI | ⬜ |
+| Dark/Light Mode | ⬜ |
+| Animations | ⬜ |
+| Kubernetes | ⬜ |
+| Helm Chart | ⬜ |
+| Prometheus | ⬜ |
+| Grafana Dashboard | ⬜ |
+| Alert Rules | ⬜ |
+| Notifications | ⬜ |
+| CI/CD | ⬜ |
+| Documentation | ⬜ |
+
+Legend: ✅ Pass | ❌ Fail | ⬜ Not Tested
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a44c1e0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,353 @@
+# 🌦️ IntelliWeather
+
+A production-grade weather API built with FastAPI, featuring real-time weather data, intelligent caching, user authentication, rate limiting, and horizontal scaling support. Designed as a modern competitor to AccuWeather.
+
+![Dashboard](https://github.com/user-attachments/assets/c1fc16fb-2290-4376-9c8c-2b109d03de41)
+
+## ✨ Features
+
+### Phase 1 - Core Features
+
+#### Weather Data
+- **Real-time Weather** - Current temperature, humidity, wind speed, UV index, and more
+- **Hourly Forecasts** - 24-hour detailed weather predictions
+- **7-Day Forecast** - Extended weather outlook with high/low temperatures
+- **Air Quality Index** - AQI monitoring with health indicators
+
+#### UI & UX
+- **Royal Theme** - Premium purple and gold color scheme
+- **Animated Backgrounds** - Starfield, floating orbs, aurora effects
+- **Responsive Layout** - Works on mobile, tablet, and desktop
+- **Connection Status** - Real-time backend connectivity indicator
+
+#### Backend Features
+- **Multi-tier Caching** - In-memory cache with configurable TTL
+- **CSV Data Storage** - Simple file-based persistence
+- **Session Authentication** - Secure server-side sessions
+- **Rate Limiting** - Per-IP rate limiting
+- **Health Checks** - `/healthz` endpoint for load balancers
+
+### Phase 2 - Advanced Features
+
+#### Enhanced Weather API
+- **Hourly Endpoint V2** - 24/48/72 hour forecasts with CSV export
+- **Daily Endpoint V2** - 7/14 day forecasts with CSV export
+- **Historical Data** - Query weather data up to 1 year back
+- **Unit Conversion** - Metric and imperial support
+
+#### Geocoding
+- **Location Search** - Search cities with autocomplete
+- **Reverse Geocoding** - Get location from coordinates
+- **Caching** - 24-hour cache for geocoding results
+
+#### Weather Alerts
+- **Active Alerts** - Get severe weather warnings
+- **Alert Types** - Thunderstorms, high winds, precipitation, winter weather
+- **Background Prefetch** - Automatic alert updates for popular locations
+
+#### Downloadable Reports
+- **PDF Reports** - Formatted weather reports with charts
+- **Excel Reports** - Structured data with multiple sheets
+- **Report Caching** - Generated reports are cached
+
+#### ML Predictions
+- **Next-Day Temperature** - Linear regression model
+- **Confidence Intervals** - Prediction uncertainty
+- **Model Training** - Periodic retraining on historical data
+
+#### Multi-language Support
+- **5 Languages** - English, Hindi, Urdu, Arabic, Spanish
+- **UI Translations** - Full interface localization
+- **Weather Descriptions** - Localized condition text
+
+#### API Key Management
+- **Personal API Keys** - Create keys for programmatic access
+- **Per-Key Rate Limits** - Customizable limits per key
+- **Usage Tracking** - Monitor API key usage
+
+#### Admin Dashboard
+- **Analytics** - User counts, cache stats, top locations
+- **System Health** - Component status monitoring
+- **Cache Management** - Clear cache from dashboard
+
+## 🛠️ Tech Stack
+
+### Backend
+- **FastAPI** - Modern async Python web framework
+- **Pydantic** - Data validation with type hints
+- **Uvicorn/Gunicorn** - ASGI server for production
+- **Open-Meteo API** - Free weather data provider
+
+### Frontend
+- **HTML5/CSS3** - Royal theme design
+- **Vanilla JavaScript** - No framework dependencies
+- **Playfair Display** - Elegant typography
+
+### Infrastructure
+- **Docker** - Containerization
+- **NGINX** - Load balancing & reverse proxy
+- **Redis** (optional) - Session storage for scaled deployments
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- pip package manager
+- Docker (optional, for containerized deployment)
+
+### Quick Start
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/CodersAcademy006/Weather-API.git
+   cd Weather-API
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Run the server**
+   ```bash
+   uvicorn app:app --host 0.0.0.0 --port 8000 --reload
+   ```
+
+4. **Open in browser**
+   - Dashboard: http://localhost:8000
+   - API Docs: http://localhost:8000/docs
+
+### Docker Deployment
+
+```bash
+# Build and run with Docker Compose
+docker-compose up -d
+
+# Scale to multiple replicas
+docker-compose up -d --scale app=3
+
+# View logs
+docker-compose logs -f
+```
+
+## 📡 API Endpoints
+
+### Phase 1 - Weather Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/weather?lat={lat}&lon={lon}` | GET | Current weather |
+| `/hourly?lat={lat}&lon={lon}` | GET | 24-hour forecast |
+| `/forecast?lat={lat}&lon={lon}` | GET | 7-day forecast |
+| `/aqi-alerts?lat={lat}&lon={lon}` | GET | Air quality & alerts |
+
+### Phase 2 - Enhanced Weather
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/weather/hourly?lat=&lon=&hours=` | GET | Hourly forecast (24/48/72h) |
+| `/weather/daily?lat=&lon=&days=` | GET | Daily forecast (7/14 days) |
+| `/weather/historical?lat=&lon=&start=&end=` | GET | Historical data |
+| `/weather/download?lat=&lon=&type=pdf` | GET | Download report |
+
+### Phase 2 - Geocoding
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/geocode/search?q={query}` | GET | Search locations |
+| `/geocode/reverse?lat=&lon=` | GET | Reverse geocode |
+
+### Phase 2 - Alerts & Prediction
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/alerts?lat=&lon=` | GET | Weather alerts |
+| `/predict/nextday?lat=&lon=` | GET | Next-day prediction |
+
+### Phase 2 - API Keys & i18n
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/apikeys` | POST | Create API key |
+| `/apikeys` | GET | List API keys |
+| `/apikeys/{id}` | DELETE | Revoke API key |
+| `/i18n/translations?lang=` | GET | Get translations |
+
+### Authentication
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/auth/signup` | POST | Create account |
+| `/auth/login` | POST | Login |
+| `/auth/logout` | POST | Logout |
+| `/auth/me` | GET | Get current user |
+
+### Admin & System
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/admin/dashboard` | GET | Admin dashboard |
+| `/admin/api/stats` | GET | Dashboard stats |
+| `/healthz` | GET | Health check |
+| `/metrics` | GET | Application metrics |
+
+### Example Requests
+
+```bash
+# Current weather
+curl "http://localhost:8000/weather?lat=40.7128&lon=-74.0060"
+
+# Hourly forecast with CSV export
+curl "http://localhost:8000/weather/hourly?lat=40.7128&lon=-74.0060&hours=48&format=csv" -o forecast.csv
+
+# Search for a city
+curl "http://localhost:8000/geocode/search?q=London&limit=5"
+
+# Get weather alerts
+curl "http://localhost:8000/alerts?lat=40.7128&lon=-74.0060"
+
+# Next-day temperature prediction
+curl "http://localhost:8000/predict/nextday?lat=40.7128&lon=-74.0060"
+
+# Download PDF report
+curl "http://localhost:8000/weather/download?lat=40.7128&lon=-74.0060&type=pdf" -o report.pdf
+
+# Get Hindi translations
+curl "http://localhost:8000/i18n/translations?lang=hi"
+```
+
+## 🏗️ Project Architecture
+
+```
+Weather-API/
+├── app.py                     # Main FastAPI application
+├── config.py                  # Centralized configuration
+├── cache.py                   # In-memory caching system
+├── storage.py                 # CSV-based data storage
+├── session_middleware.py      # Session management
+├── logging_config.py          # Structured logging
+├── metrics.py                 # Health checks & metrics
+├── middleware/
+│   └── rate_limiter.py        # Rate limiting
+├── routes/
+│   ├── auth.py                # Authentication
+│   ├── weather_v2.py          # Enhanced weather endpoints
+│   ├── geocode.py             # Geocoding
+│   ├── alerts.py              # Weather alerts
+│   ├── downloads.py           # Report downloads
+│   ├── apikeys.py             # API key management
+│   ├── predict.py             # ML predictions
+│   ├── admin.py               # Admin dashboard
+│   └── i18n.py                # Internationalization
+├── modules/
+│   ├── geocode.py             # Geocoding service
+│   ├── api_keys.py            # API key manager
+│   ├── i18n.py                # Translation service
+│   ├── prediction.py          # ML prediction service
+│   └── reports/
+│       ├── pdf_report.py      # PDF generation
+│       └── xlsx_report.py     # Excel generation
+├── schemas/
+│   ├── weather.py             # Weather models
+│   ├── geocode.py             # Geocoding models
+│   ├── alerts.py              # Alert models
+│   └── api_keys.py            # API key models
+├── workers/
+│   ├── alerts_prefetch.py     # Alert prefetcher
+│   └── train_model.py         # Model trainer
+├── static/                    # Frontend files
+├── tests/                     # Unit tests
+├── data/                      # CSV storage
+├── Dockerfile                 # Docker image
+├── docker-compose.yml         # Multi-container setup
+├── nginx.conf                 # Load balancer
+├── requirements.txt           # Dependencies
+├── CHANGELOG.md               # Version history
+├── QA.md                      # Phase 1 QA checklist
+├── QA_PHASE2.md               # Phase 2 QA checklist
+├── demo_script.md             # Phase 1 demo guide
+└── demo_phase2.md             # Phase 2 demo guide
+```
+
+## ⚙️ Configuration
+
+### Core Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `APP_NAME` | IntelliWeather | Application name |
+| `APP_PORT` | 8000 | Server port |
+| `CACHE_TTL_SECONDS` | 3600 | Cache expiration |
+| `SESSION_TIMEOUT_SECONDS` | 86400 | Session expiration |
+| `RATE_LIMIT_PER_MIN` | 60 | Requests per minute per IP |
+
+### Phase 2 Feature Flags
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FEATURE_WEATHER_V2` | true | Enable enhanced weather |
+| `FEATURE_GEOCODING` | true | Enable geocoding |
+| `FEATURE_ALERTS` | true | Enable alerts |
+| `FEATURE_DOWNLOADS` | true | Enable downloads |
+| `FEATURE_API_KEYS` | true | Enable API keys |
+| `FEATURE_ML_PREDICTION` | true | Enable predictions |
+| `FEATURE_ADMIN_DASHBOARD` | true | Enable admin |
+| `FEATURE_I18N` | true | Enable i18n |
+
+### Additional Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GEOCODE_CACHE_TTL_SECONDS` | 86400 | Geocode cache (24h) |
+| `API_KEY_RATE_LIMIT_DEFAULT` | 100 | Default key rate limit |
+| `ML_HISTORICAL_DAYS` | 365 | Training data days |
+| `DEFAULT_LANGUAGE` | en | Default language |
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=. --cov-report=html
+
+# Run Phase 2 specific tests
+pytest tests/test_phase2.py -v
+```
+
+## 🎨 Screenshots
+
+| Dashboard | Login | Sign Up |
+|-----------|-------|---------|
+| ![Dashboard](https://github.com/user-attachments/assets/c1fc16fb-2290-4376-9c8c-2b109d03de41) | ![Login](https://github.com/user-attachments/assets/d89050fb-aa97-4dcc-ab96-a1883e3b7aac) | ![Sign Up](https://github.com/user-attachments/assets/82d424be-c220-4c11-80cb-fa42eeb34fd6) |
+
+## 🌐 Data Sources
+
+- **Weather Data**: [Open-Meteo](https://open-meteo.com/)
+- **Historical Weather**: [Open-Meteo Archive](https://open-meteo.com/en/docs/historical-weather-api)
+- **Air Quality**: [Open-Meteo Air Quality API](https://open-meteo.com/en/docs/air-quality-api)
+- **Geocoding**: [Open-Meteo Geocoding API](https://open-meteo.com/en/docs/geocoding-api)
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📧 Contact
+
+Created by [@CodersAcademy006](https://github.com/CodersAcademy006)
+
+---
+
+⭐ Star this repo if you find it helpful!
diff --git a/app.py b/app.py
index 8a87efd..53aebe7 100644
--- a/app.py
+++ b/app.py
@@ -1,173 +1,804 @@
-# Save this file as "app.py"
-import requests
-import psycopg2
-from fastapi import FastAPI, HTTPException
-from fastapi.staticfiles import StaticFiles
-from fastapi.middleware.cors import CORSMiddleware
-from datetime import datetime, timedelta, timezone
-
-# --- Configuration & Initialization ---
-DB_CONNECTION_STRING = "postgresql://postgres.kucoxmriguvqulnkzpcw:S.La9c4vc#wE2gq@aws-1-ap-south-1.pooler.supabase.com:6543/postgres"
-app = FastAPI()
-app.add_middleware(
-    CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"],
-)
-
-# ====================================================================
-#  HELPER FUNCTIONS
-# ====================================================================
-
-# --- CURRENT WEATHER ---
-def get_weather_from_db(lat, lon):
-    conn = psycopg2.connect(DB_CONNECTION_STRING)
-    cursor = conn.cursor()
-    one_hour_ago = datetime.now(timezone.utc) - timedelta(hours=1)
-    query = "SELECT * FROM weather_readings WHERE latitude = %s AND longitude = %s AND timestamp >= %s ORDER BY timestamp DESC LIMIT 1;"
-    cursor.execute(query, (lat, lon, one_hour_ago))
-    result = cursor.fetchone()
-    conn.close()
-    return result
-
-def save_weather_to_db(data_rows):
-    conn = psycopg2.connect(DB_CONNECTION_STRING)
-    cursor = conn.cursor()
-    insert_query = "INSERT INTO weather_readings (location_name, latitude, longitude, timestamp, temperature_c, humidity_pct, pressure_hpa, wind_speed_mps, precip_mm, weather_code, apparent_temperature, uv_index, is_day) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s) ON CONFLICT (location_name, timestamp) DO NOTHING;"
-    for row in data_rows:
-        values = (row['location_name'], row['latitude'], row['longitude'], row['timestamp'], row['temperature_c'], row['humidity_pct'], row['pressure_hpa'], row['wind_speed_mps'], row['precip_mm'], row['weather_code'], row['apparent_temperature'], row['uv_index'], row['is_day'])
-        cursor.execute(insert_query, values)
-    conn.commit()
-    conn.close()
-
-def fetch_live_weather(lat, lon):
-    api_url = "https://api.open-meteo.com/v1/forecast"
-    params = {"latitude": lat, "longitude": lon, "current": "temperature_2m,apparent_temperature,precipitation,weather_code,relative_humidity_2m,wind_speed_10m,uv_index,pressure_msl,is_day", "timezone": "auto"}
-    response = requests.get(api_url, params=params)
-    if response.status_code != 200: return None
-    raw = response.json()['current']
-    return { "location_name": f"Lat_{lat}_Lon_{lon}", "latitude": lat, "longitude": lon, "timestamp": datetime.fromisoformat(raw['time']), "temperature_c": raw['temperature_2m'], "humidity_pct": raw['relative_humidity_2m'], "pressure_hpa": raw['pressure_msl'], "wind_speed_mps": round(raw['wind_speed_10m'] / 3.6, 2), "precip_mm": raw['precipitation'], "weather_code": raw['weather_code'], "apparent_temperature": raw['apparent_temperature'], "uv_index": raw['uv_index'], "is_day": raw['is_day'] }
-
-# --- HOURLY FORECAST ---
-def get_hourly_forecast_from_db(lat, lon):
-    conn = psycopg2.connect(DB_CONNECTION_STRING)
-    cursor = conn.cursor()
-    six_hours_ago = datetime.now(timezone.utc) - timedelta(hours=6)
-    query = "SELECT forecast_time, temperature_c, precipitation_prob, wind_speed_mps, cloud_cover, weather_code FROM hourly_forecasts WHERE latitude = %s AND longitude = %s AND created_at >= %s ORDER BY forecast_time ASC LIMIT 24;"
-    cursor.execute(query, (lat, lon, six_hours_ago))
-    results = cursor.fetchall()
-    conn.close()
-    return results
-
-def save_hourly_forecast_to_db(lat, lon, forecast_data):
-    conn = psycopg2.connect(DB_CONNECTION_STRING)
-    cursor = conn.cursor()
-    query = "INSERT INTO hourly_forecasts (latitude, longitude, forecast_time, temperature_c, precipitation_prob, wind_speed_mps, cloud_cover, weather_code) VALUES (%s, %s, %s, %s, %s, %s, %s, %s) ON CONFLICT (latitude, longitude, forecast_time) DO UPDATE SET temperature_c = EXCLUDED.temperature_c, precipitation_prob = EXCLUDED.precipitation_prob, wind_speed_mps = EXCLUDED.wind_speed_mps, cloud_cover = EXCLUDED.cloud_cover, weather_code = EXCLUDED.weather_code, created_at = NOW();"
-    for hour in forecast_data:
-        values = (lat, lon, hour['time'], hour['temp'], hour['precip_prob'], hour['wind'], hour['cloud_cover'], hour['weather_code'])
-        cursor.execute(query, values)
-    conn.commit()
-    conn.close()
-
-def fetch_hourly_forecast(lat, lon):
-    api_url = "https://api.open-meteo.com/v1/forecast"
-    params = {"latitude": lat, "longitude": lon, "hourly": "temperature_2m,precipitation_probability,wind_speed_10m,cloud_cover,weather_code", "forecast_days": 1, "timezone": "auto"}
-    response = requests.get(api_url, params=params)
-    if response.status_code != 200: return None
-    raw = response.json()['hourly']
-    return [{"time": raw['time'][i], "temp": raw['temperature_2m'][i], "precip_prob": raw['precipitation_probability'][i], "wind": round(raw['wind_speed_10m'][i] / 3.6, 2), "cloud_cover": raw['cloud_cover'][i], "weather_code": raw['weather_code'][i]} for i in range(len(raw['time']))]
-
-# --- DAILY FORECAST ---
-def get_forecast_from_db(lat, lon):
-    conn = psycopg2.connect(DB_CONNECTION_STRING)
-    cursor = conn.cursor()
-    six_hours_ago = datetime.now(timezone.utc) - timedelta(hours=6)
-    query = "SELECT forecast_date, max_temp_c, min_temp_c, weather_code, sunrise, sunset, precipitation_sum, precipitation_probability_max FROM daily_forecasts WHERE latitude = %s AND longitude = %s AND created_at >= %s ORDER BY forecast_date ASC;"
-    cursor.execute(query, (lat, lon, six_hours_ago))
-    results = cursor.fetchall()
-    conn.close()
-    return results
-
-def save_forecast_to_db(lat, lon, forecast_data):
-    conn = psycopg2.connect(DB_CONNECTION_STRING)
-    cursor = conn.cursor()
-    query = "INSERT INTO daily_forecasts (latitude, longitude, forecast_date, max_temp_c, min_temp_c, weather_code, sunrise, sunset, precipitation_sum, precipitation_probability_max) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s) ON CONFLICT (latitude, longitude, forecast_date) DO UPDATE SET max_temp_c = EXCLUDED.max_temp_c, min_temp_c = EXCLUDED.min_temp_c, weather_code = EXCLUDED.weather_code, sunrise = EXCLUDED.sunrise, sunset = EXCLUDED.sunset, precipitation_sum = EXCLUDED.precipitation_sum, precipitation_probability_max = EXCLUDED.precipitation_probability_max, created_at = NOW();"
-    for day in forecast_data:
-        values = (lat, lon, day['date'], day['max_temp'], day['min_temp'], day['weather_code'], day['sunrise'], day['sunset'], day['precipitation_sum'], day['precipitation_probability_max'])
-        cursor.execute(query, values)
-    conn.commit()
-    conn.close()
-
-def fetch_daily_forecast(lat, lon):
-    api_url = "https://api.open-meteo.com/v1/forecast"
-    params = { "latitude": lat, "longitude": lon, "daily": "weather_code,temperature_2m_max,temperature_2m_min,sunrise,sunset,precipitation_sum,precipitation_probability_max", "forecast_days": 7, "timezone": "auto" }
-    response = requests.get(api_url, params=params)
-    if response.status_code != 200: return None
-    raw = response.json()['daily']
-    return [{"date": raw['time'][i], "max_temp": raw['temperature_2m_max'][i], "min_temp": raw['temperature_2m_min'][i], "weather_code": raw['weather_code'][i], "sunrise": raw['sunrise'][i], "sunset": raw['sunset'][i], "precipitation_sum": raw['precipitation_sum'][i], "precipitation_probability_max": raw['precipitation_probability_max'][i]} for i in range(len(raw['time']))]
-
-# --- AQI & ALERTS ---
-def fetch_aqi_and_alerts(lat, lon):
-    air_quality_api_url = "https://air-quality-api.open-meteo.com/v1/air-quality"
-    forecast_api_url = "https://api.open-meteo.com/v1/forecast"
-    aqi_params = {"latitude": lat, "longitude": lon, "hourly": "us_aqi,pm2_5,carbon_monoxide,ozone", "timezone": "auto"}
-    alerts_params = {"latitude": lat, "longitude": lon, "daily": "weather_code", "forecast_days": 1}
-
-    aqi_response = requests.get(air_quality_api_url, params=aqi_params)
-    alerts_response = requests.get(forecast_api_url, params=alerts_params)
-    
-    aqi_data = aqi_response.json() if aqi_response.status_code == 200 else None
-    # Alerts are still experimental and may not always be present
-    alerts = alerts_response.json().get("daily", {}).get("alerts", []) if alerts_response.status_code == 200 else []
-    
-    return {"aqi": aqi_data, "alerts": alerts}
-
-# ====================================================================
-#  API ENDPOINTS
-# ====================================================================
-
-@app.get("/weather")
-def get_weather(lat: float, lon: float):
-    cached = get_weather_from_db(lat, lon)
-    if cached and len(cached) >= 14:
-        print(f"CACHE HIT for current weather at {lat}, {lon}")
-        return {"source": "cache", "timestamp": cached[4], "temperature_c": cached[5], "humidity_pct": cached[6], "pressure_hpa": cached[7], "wind_speed_mps": cached[8], "precip_mm": cached[9], "weather_code": cached[10], "apparent_temperature": cached[11], "uv_index": cached[12], "is_day": cached[13]}
-    print(f"CACHE MISS for current weather at {lat}, {lon}. Fetching live data...")
-    live = fetch_live_weather(lat, lon)
-    if not live: raise HTTPException(status_code=500, detail="Could not retrieve live weather data.")
-    save_weather_to_db([live])
-    return {"source": "live", **live}
-
-@app.get("/hourly")
-def get_hourly_forecast(lat: float, lon: float):
-    cached = get_hourly_forecast_from_db(lat, lon)
-    if cached and len(cached) >= 24:
-        print(f"CACHE HIT for hourly forecast at {lat}, {lon}")
-        return [{"time": r[0], "temp": r[1], "precip_prob": r[2], "wind": r[3], "cloud_cover": r[4], "weather_code": r[5]} for r in cached]
-    print(f"CACHE MISS for hourly forecast at {lat}, {lon}. Fetching live data...")
-    live = fetch_hourly_forecast(lat, lon)
-    if not live: raise HTTPException(status_code=500, detail="Could not retrieve hourly forecast.")
-    save_hourly_forecast_to_db(lat, lon, live)
-    return live
-
-@app.get("/forecast")
-def get_daily_forecast(lat: float, lon: float):
-    cached = get_forecast_from_db(lat, lon)
-    if cached and len(cached) >= 5:
-        print(f"CACHE HIT for 5-day forecast at {lat}, {lon}")
-        return [{"date": r[0], "max_temp": r[1], "min_temp": r[2], "weather_code": r[3], "sunrise": r[4], "sunset": r[5], "precipitation_sum": r[6], "precipitation_probability_max": r[7]} for r in cached]
-    print(f"CACHE MISS for 5-day forecast at {lat}, {lon}. Fetching live data...")
-    live = fetch_daily_forecast(lat, lon)
-    if not live: raise HTTPException(status_code=500, detail="Could not retrieve live forecast data.")
-    save_forecast_to_db(lat, lon, live)
-    return live
-
-@app.get("/aqi-alerts")
-def get_aqi_and_alerts(lat: float, lon: float):
-    # Caching is not implemented for this endpoint in the prototype
-    print(f"Fetching AQI & Alerts data for {lat}, {lon}...")
-    data = fetch_aqi_and_alerts(lat, lon)
-    if not data["aqi"]:
-        raise HTTPException(status_code=500, detail="Could not retrieve Air Quality data.")
-    return data
-
-# --- Mount the Static Files (Frontend) ---
-app.mount("/", StaticFiles(directory="static", html=True), name="static")
+"""
+IntelliWeather API - Production-Grade Weather Service
+
+A modern, feature-rich weather API built with FastAPI featuring:
+- Real-time weather data from Open-Meteo
+- SQLite database for caching (main branch compatible)
+- In-memory caching with TTL (fallback)
+- Session-based authentication
+- Rate limiting
+- Health checks and metrics
+
+Phase 2 Features:
+- Hourly, daily, and historical weather endpoints
+- Geocoding and reverse geocoding
+- Weather alerts
+- PDF/Excel report downloads
+- ML-based temperature predictions
+- Multi-language support
+- API key management
+- Admin dashboard
+
+Phase 3 Features:
+- Kubernetes deployment support
+- Prometheus metrics
+- Notifications (email/SMS/push)
+- Growth features (analytics, referrals, shareable links)
+"""
+
+import requests
+import sqlite3
+import json
+import os
+from typing import Optional
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+from datetime import datetime, timedelta, timezone
+
+# Configuration - try to import from config.py, fall back to defaults
+try:
+    from config import settings
+    HAS_CONFIG = True
+except ImportError:
+    HAS_CONFIG = False
+    class DefaultSettings:
+        APP_NAME = "IntelliWeather"
+        APP_VERSION = "3.0.1"
+        CORS_ORIGINS = ["*"]
+        CORS_ALLOW_CREDENTIALS = True
+        FEATURE_WEATHER_V2 = True
+        FEATURE_GEOCODING = True
+        FEATURE_ALERTS = True
+        FEATURE_DOWNLOADS = True
+        FEATURE_API_KEYS = True
+        FEATURE_ML_PREDICTION = True
+        FEATURE_ADMIN_DASHBOARD = True
+        FEATURE_I18N = True
+        FEATURE_ANALYTICS = True
+        FEATURE_REFERRALS = True
+        FEATURE_SHAREABLE_LINKS = True
+        SENTRY_DSN = None
+    settings = DefaultSettings()
+
+# Logging - try to import from logging_config.py, fall back to print
+try:
+    from logging_config import get_logger
+    logger = get_logger(__name__)
+except ImportError:
+    class SimpleLogger:
+        def info(self, msg): print(f"INFO: {msg}")
+        def error(self, msg): print(f"ERROR: {msg}")
+        def warning(self, msg): print(f"WARNING: {msg}")
+    logger = SimpleLogger()
+
+# Try to import Phase 2/3 modules (optional)
+try:
+    from cache import get_cache, generate_weather_cache_key, init_cache
+    HAS_CACHE_MODULE = True
+except ImportError:
+    HAS_CACHE_MODULE = False
+    def get_cache(): return None
+    def generate_weather_cache_key(lat, lon, type): return f"{lat}:{lon}:{type}"
+    def init_cache(): pass
+
+try:
+    from storage import get_storage, init_storage, CachedWeather
+    HAS_STORAGE_MODULE = True
+except ImportError:
+    HAS_STORAGE_MODULE = False
+    def get_storage(): return None
+    def init_storage(): pass
+    class CachedWeather: pass
+
+try:
+    from session_middleware import SessionMiddleware, set_session_middleware
+    HAS_SESSION_MODULE = True
+except ImportError:
+    HAS_SESSION_MODULE = False
+
+try:
+    from middleware.rate_limiter import RateLimiterMiddleware
+    HAS_RATE_LIMITER = True
+except ImportError:
+    HAS_RATE_LIMITER = False
+
+try:
+    from routes.auth import router as auth_router
+    HAS_AUTH_ROUTER = True
+except ImportError:
+    HAS_AUTH_ROUTER = False
+
+try:
+    from metrics import router as metrics_router, get_metrics
+    HAS_METRICS_ROUTER = True
+except ImportError:
+    HAS_METRICS_ROUTER = False
+    class DummyMetrics:
+        def increment(self, key): pass
+    def get_metrics(): return DummyMetrics()
+
+# Phase 2 routers (optional)
+try:
+    from routes.weather_v2 import router as weather_v2_router
+    HAS_WEATHER_V2 = True
+except ImportError:
+    HAS_WEATHER_V2 = False
+
+try:
+    from routes.geocode import router as geocode_router
+    HAS_GEOCODE = True
+except ImportError:
+    HAS_GEOCODE = False
+
+try:
+    from routes.alerts import router as alerts_router
+    HAS_ALERTS = True
+except ImportError:
+    HAS_ALERTS = False
+
+try:
+    from routes.downloads import router as downloads_router
+    HAS_DOWNLOADS = True
+except ImportError:
+    HAS_DOWNLOADS = False
+
+try:
+    from routes.apikeys import router as apikeys_router
+    HAS_APIKEYS = True
+except ImportError:
+    HAS_APIKEYS = False
+
+try:
+    from routes.predict import router as predict_router
+    HAS_PREDICT = True
+except ImportError:
+    HAS_PREDICT = False
+
+try:
+    from routes.admin import router as admin_router
+    HAS_ADMIN = True
+except ImportError:
+    HAS_ADMIN = False
+
+try:
+    from routes.i18n import router as i18n_router
+    HAS_I18N = True
+except ImportError:
+    HAS_I18N = False
+
+try:
+    from routes.growth import router as growth_router
+    HAS_GROWTH = True
+except ImportError:
+    HAS_GROWTH = False
+
+
+# ==================== DATABASE CONFIGURATION (Main Branch Compatible) ====================
+DB_FILE = "weather.db"
+
+
+def init_db():
+    """Initialize the SQLite database with necessary tables."""
+    try:
+        conn = sqlite3.connect(DB_FILE)
+        cursor = conn.cursor()
+        
+        # Weather Readings Table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS weather_readings (
+                location_name TEXT,
+                latitude REAL,
+                longitude REAL,
+                timestamp TEXT,
+                temperature_c REAL,
+                humidity_pct REAL,
+                pressure_hpa REAL,
+                wind_speed_mps REAL,
+                precip_mm REAL,
+                weather_code INTEGER,
+                apparent_temperature REAL,
+                uv_index REAL,
+                is_day INTEGER,
+                PRIMARY KEY (location_name, timestamp)
+            );
+        """)
+        
+        # Hourly Forecasts Table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS hourly_forecasts (
+                latitude REAL,
+                longitude REAL,
+                forecast_time TEXT,
+                temperature_c REAL,
+                precipitation_prob REAL,
+                wind_speed_mps REAL,
+                cloud_cover REAL,
+                weather_code INTEGER,
+                created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (latitude, longitude, forecast_time)
+            );
+        """)
+        
+        # Daily Forecasts Table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS daily_forecasts (
+                latitude REAL,
+                longitude REAL,
+                forecast_date TEXT,
+                max_temp_c REAL,
+                min_temp_c REAL,
+                weather_code INTEGER,
+                sunrise TEXT,
+                sunset TEXT,
+                precipitation_sum REAL,
+                precipitation_probability_max REAL,
+                created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+                PRIMARY KEY (latitude, longitude, forecast_date)
+            );
+        """)
+        
+        conn.commit()
+        conn.close()
+        logger.info("✅ Local SQLite database initialized.")
+    except Exception as e:
+        logger.error(f"❌ Failed to initialize database: {e}")
+
+
+# ==================== APPLICATION LIFECYCLE ====================
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifecycle manager."""
+    # Startup
+    logger.info(f"Starting {settings.APP_NAME} v{settings.APP_VERSION}")
+    
+    # Initialize SQLite database (main branch compatible)
+    init_db()
+    
+    # Initialize Phase 2 components (if available)
+    if HAS_STORAGE_MODULE:
+        init_storage()
+    if HAS_CACHE_MODULE:
+        init_cache()
+    
+    # Initialize Sentry if configured
+    if getattr(settings, 'SENTRY_DSN', None):
+        try:
+            import sentry_sdk
+            sentry_sdk.init(dsn=settings.SENTRY_DSN, traces_sample_rate=0.1)
+            logger.info("Sentry initialized")
+        except ImportError:
+            logger.warning("Sentry SDK not installed")
+    
+    print("=" * 70)
+    print("✅ SERVER STARTED SUCCESSFULLY!")
+    print("=" * 70)
+    print("📍 Local: http://localhost:8000")
+    print("🌐 Codespaces: Check PORTS tab for the forwarded URL")
+    print("=" * 70)
+    print("\n🔧 API Endpoints:")
+    print("   GET /weather?lat={lat}&lon={lon}")
+    print("   GET /hourly?lat={lat}&lon={lon}")
+    print("   GET /forecast?lat={lat}&lon={lon}")
+    print("   GET /aqi-alerts?lat={lat}&lon={lon}")
+    print("   GET /api-test (health check)")
+    print("=" * 70 + "\n")
+    
+    yield
+    
+    # Shutdown
+    logger.info("Shutting down application")
+    if HAS_CACHE_MODULE:
+        cache = get_cache()
+        if cache:
+            cache.shutdown()
+    logger.info("Application shutdown complete")
+
+
+# ==================== APPLICATION SETUP ====================
+
+app = FastAPI(
+    title=settings.APP_NAME,
+    version=settings.APP_VERSION,
+    description="""
+# IntelliWeather API
+
+Production-grade weather API with SQLite caching, authentication, and rate limiting.
+
+## Features
+- Real-time weather data
+- SQLite database caching
+- Session-based authentication  
+- Rate limiting
+- Health & metrics
+""",
+    lifespan=lifespan,
+    openapi_tags=[
+        {"name": "Weather", "description": "Current weather and basic forecasts"},
+        {"name": "Weather V2", "description": "Enhanced weather endpoints with CSV support"},
+        {"name": "Geocoding", "description": "Location search and reverse geocoding"},
+        {"name": "Weather Alerts", "description": "Active alerts and warnings"},
+        {"name": "Downloads", "description": "PDF and Excel report downloads"},
+        {"name": "ML Prediction", "description": "Machine learning predictions"},
+        {"name": "Internationalization", "description": "Multi-language support"},
+        {"name": "API Keys", "description": "API key management"},
+        {"name": "Auth", "description": "Authentication endpoints"},
+        {"name": "Admin", "description": "Admin dashboard and analytics"},
+        {"name": "Health", "description": "Health checks and metrics"},
+    ]
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=getattr(settings, 'CORS_ORIGINS', ["*"]),
+    allow_credentials=getattr(settings, 'CORS_ALLOW_CREDENTIALS', True),
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Add rate limiter middleware (if available)
+if HAS_RATE_LIMITER:
+    app.add_middleware(RateLimiterMiddleware)
+
+# Add session middleware (if available)
+if HAS_SESSION_MODULE:
+    session_middleware = SessionMiddleware(app)
+    set_session_middleware(session_middleware)
+
+# Include Phase 1 routers (if available)
+if HAS_AUTH_ROUTER:
+    app.include_router(auth_router)
+if HAS_METRICS_ROUTER:
+    app.include_router(metrics_router)
+
+# Include Phase 2 routers (conditionally based on feature flags)
+if HAS_WEATHER_V2 and getattr(settings, 'FEATURE_WEATHER_V2', True):
+    app.include_router(weather_v2_router)
+    logger.info("Weather V2 routes enabled")
+
+if HAS_GEOCODE and getattr(settings, 'FEATURE_GEOCODING', True):
+    app.include_router(geocode_router)
+    logger.info("Geocoding routes enabled")
+
+if HAS_ALERTS and getattr(settings, 'FEATURE_ALERTS', True):
+    app.include_router(alerts_router)
+    logger.info("Alerts routes enabled")
+
+if HAS_DOWNLOADS and getattr(settings, 'FEATURE_DOWNLOADS', True):
+    app.include_router(downloads_router)
+    logger.info("Downloads routes enabled")
+
+if HAS_APIKEYS and getattr(settings, 'FEATURE_API_KEYS', True):
+    app.include_router(apikeys_router)
+    logger.info("API Keys routes enabled")
+
+if HAS_PREDICT and getattr(settings, 'FEATURE_ML_PREDICTION', True):
+    app.include_router(predict_router)
+    logger.info("ML Prediction routes enabled")
+
+if HAS_ADMIN and getattr(settings, 'FEATURE_ADMIN_DASHBOARD', True):
+    app.include_router(admin_router)
+    logger.info("Admin dashboard routes enabled")
+
+if HAS_I18N and getattr(settings, 'FEATURE_I18N', True):
+    app.include_router(i18n_router)
+    logger.info("i18n routes enabled")
+
+# Phase 3: Growth features
+if HAS_GROWTH and (getattr(settings, 'FEATURE_ANALYTICS', True) or 
+                   getattr(settings, 'FEATURE_REFERRALS', True) or 
+                   getattr(settings, 'FEATURE_SHAREABLE_LINKS', True)):
+    app.include_router(growth_router)
+    logger.info("Growth routes enabled")
+
+
+# ==================== HELPER FUNCTIONS (Main Branch Compatible) ====================
+
+def normalize_coordinates(lat: float, lon: float) -> tuple:
+    """Normalize coordinates to 2 decimal places for caching."""
+    return round(lat, 2), round(lon, 2)
+
+
+# --- CURRENT WEATHER ---
+def get_weather_from_db(lat, lon):
+    try:
+        conn = sqlite3.connect(DB_FILE)
+        cursor = conn.cursor()
+        one_hour_ago = (datetime.now(timezone.utc) - timedelta(hours=1)).isoformat()
+        query = "SELECT * FROM weather_readings WHERE latitude = ? AND longitude = ? AND timestamp >= ? ORDER BY timestamp DESC LIMIT 1;"
+        cursor.execute(query, (lat, lon, one_hour_ago))
+        result = cursor.fetchone()
+        conn.close()
+        return result
+    except Exception as e:
+        logger.warning(f"DB Error (get_weather): {e}")
+        return None
+
+
+def save_weather_to_db(data_rows):
+    try:
+        conn = sqlite3.connect(DB_FILE)
+        cursor = conn.cursor()
+        insert_query = "INSERT OR IGNORE INTO weather_readings (location_name, latitude, longitude, timestamp, temperature_c, humidity_pct, pressure_hpa, wind_speed_mps, precip_mm, weather_code, apparent_temperature, uv_index, is_day) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);"
+        for row in data_rows:
+            timestamp_val = row['timestamp']
+            if isinstance(timestamp_val, datetime):
+                timestamp_val = timestamp_val.isoformat()
+            values = (row['location_name'], row['latitude'], row['longitude'], timestamp_val, row['temperature_c'], row['humidity_pct'], row['pressure_hpa'], row['wind_speed_mps'], row['precip_mm'], row['weather_code'], row['apparent_temperature'], row['uv_index'], row['is_day'])
+            cursor.execute(insert_query, values)
+        conn.commit()
+        conn.close()
+    except Exception as e:
+        logger.warning(f"DB Error (save_weather): {e}")
+
+
+def fetch_live_weather(lat, lon):
+    try:
+        api_url = "https://api.open-meteo.com/v1/forecast"
+        params = {"latitude": lat, "longitude": lon, "current": "temperature_2m,apparent_temperature,precipitation,weather_code,relative_humidity_2m,wind_speed_10m,uv_index,pressure_msl,is_day", "timezone": "auto"}
+        response = requests.get(api_url, params=params, timeout=10)
+        if response.status_code != 200:
+            return None
+        raw = response.json()['current']
+        return {
+            "location_name": f"Lat_{lat}_Lon_{lon}",
+            "latitude": lat,
+            "longitude": lon,
+            "timestamp": datetime.fromisoformat(raw['time']),
+            "temperature_c": raw['temperature_2m'],
+            "humidity_pct": raw['relative_humidity_2m'],
+            "pressure_hpa": raw['pressure_msl'],
+            "wind_speed_mps": round(raw['wind_speed_10m'] / 3.6, 2),
+            "precip_mm": raw['precipitation'],
+            "weather_code": raw['weather_code'],
+            "apparent_temperature": raw['apparent_temperature'],
+            "uv_index": raw['uv_index'],
+            "is_day": raw['is_day']
+        }
+    except requests.exceptions.Timeout:
+        logger.warning(f"Timeout fetching weather for {lat}, {lon}")
+        return None
+    except Exception as e:
+        logger.error(f"Error fetching weather: {e}")
+        return None
+
+
+# --- HOURLY FORECAST ---
+def get_hourly_forecast_from_db(lat, lon):
+    try:
+        conn = sqlite3.connect(DB_FILE)
+        cursor = conn.cursor()
+        six_hours_ago = (datetime.now(timezone.utc) - timedelta(hours=6)).isoformat()
+        query = "SELECT forecast_time, temperature_c, precipitation_prob, wind_speed_mps, cloud_cover, weather_code FROM hourly_forecasts WHERE latitude = ? AND longitude = ? AND created_at >= ? ORDER BY forecast_time ASC LIMIT 24;"
+        cursor.execute(query, (lat, lon, six_hours_ago))
+        results = cursor.fetchall()
+        conn.close()
+        return results
+    except Exception as e:
+        logger.warning(f"DB Error (get_hourly): {e}")
+        return None
+
+
+def save_hourly_forecast_to_db(lat, lon, forecast_data):
+    try:
+        conn = sqlite3.connect(DB_FILE)
+        cursor = conn.cursor()
+        query = """
+            INSERT INTO hourly_forecasts (latitude, longitude, forecast_time, temperature_c, precipitation_prob, wind_speed_mps, cloud_cover, weather_code, created_at) 
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) 
+            ON CONFLICT(latitude, longitude, forecast_time) DO UPDATE SET 
+            temperature_c = excluded.temperature_c, 
+            precipitation_prob = excluded.precipitation_prob, 
+            wind_speed_mps = excluded.wind_speed_mps, 
+            cloud_cover = excluded.cloud_cover, 
+            weather_code = excluded.weather_code, 
+            created_at = excluded.created_at;
+        """
+        now_str = datetime.now(timezone.utc).isoformat()
+        for hour in forecast_data:
+            values = (lat, lon, hour['time'], hour['temp'], hour['precip_prob'], hour['wind'], hour['cloud_cover'], hour['weather_code'], now_str)
+            cursor.execute(query, values)
+        conn.commit()
+        conn.close()
+    except Exception as e:
+        logger.warning(f"DB Error (save_hourly): {e}")
+
+
+def fetch_hourly_forecast(lat, lon):
+    try:
+        api_url = "https://api.open-meteo.com/v1/forecast"
+        params = {"latitude": lat, "longitude": lon, "hourly": "temperature_2m,precipitation_probability,weather_code,wind_speed_10m,cloud_cover", "forecast_days": 1, "timezone": "auto"}
+        response = requests.get(api_url, params=params, timeout=10)
+        if response.status_code != 200:
+            return None
+        raw = response.json()['hourly']
+        return [{"time": raw['time'][i], "temp": raw['temperature_2m'][i], "precip_prob": raw['precipitation_probability'][i], "wind": round(raw['wind_speed_10m'][i] / 3.6, 2), "cloud_cover": raw['cloud_cover'][i], "weather_code": raw['weather_code'][i]} for i in range(len(raw['time']))]
+    except requests.exceptions.Timeout:
+        logger.warning(f"Timeout fetching hourly forecast for {lat}, {lon}")
+        return None
+    except Exception as e:
+        logger.error(f"Error fetching hourly forecast: {e}")
+        return None
+
+
+# --- DAILY FORECAST ---
+def get_forecast_from_db(lat, lon):
+    try:
+        conn = sqlite3.connect(DB_FILE)
+        cursor = conn.cursor()
+        six_hours_ago = (datetime.now(timezone.utc) - timedelta(hours=6)).isoformat()
+        query = "SELECT forecast_date, max_temp_c, min_temp_c, weather_code, sunrise, sunset, precipitation_sum, precipitation_probability_max FROM daily_forecasts WHERE latitude = ? AND longitude = ? AND created_at >= ? ORDER BY forecast_date ASC;"
+        cursor.execute(query, (lat, lon, six_hours_ago))
+        results = cursor.fetchall()
+        conn.close()
+        return results
+    except Exception as e:
+        logger.warning(f"DB Error (get_forecast): {e}")
+        return None
+
+
+def save_forecast_to_db(lat, lon, forecast_data):
+    try:
+        conn = sqlite3.connect(DB_FILE)
+        cursor = conn.cursor()
+        query = """
+            INSERT INTO daily_forecasts (latitude, longitude, forecast_date, max_temp_c, min_temp_c, weather_code, sunrise, sunset, precipitation_sum, precipitation_probability_max, created_at) 
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) 
+            ON CONFLICT(latitude, longitude, forecast_date) DO UPDATE SET 
+            max_temp_c = excluded.max_temp_c, 
+            min_temp_c = excluded.min_temp_c, 
+            weather_code = excluded.weather_code, 
+            sunrise = excluded.sunrise, 
+            sunset = excluded.sunset, 
+            precipitation_sum = excluded.precipitation_sum, 
+            precipitation_probability_max = excluded.precipitation_probability_max, 
+            created_at = excluded.created_at;
+        """
+        now_str = datetime.now(timezone.utc).isoformat()
+        for day in forecast_data:
+            values = (lat, lon, day['date'], day['max_temp'], day['min_temp'], day['weather_code'], day['sunrise'], day['sunset'], day['precipitation_sum'], day['precipitation_probability_max'], now_str)
+            cursor.execute(query, values)
+        conn.commit()
+        conn.close()
+    except Exception as e:
+        logger.warning(f"DB Error (save_forecast): {e}")
+
+
+def fetch_daily_forecast(lat, lon):
+    try:
+        api_url = "https://api.open-meteo.com/v1/forecast"
+        params = {"latitude": lat, "longitude": lon, "daily": "weather_code,temperature_2m_max,temperature_2m_min,sunrise,sunset,precipitation_sum,precipitation_probability_max", "forecast_days": 7, "timezone": "auto"}
+        response = requests.get(api_url, params=params, timeout=10)
+        if response.status_code != 200:
+            return None
+        raw = response.json()['daily']
+        return [{"date": raw['time'][i], "max_temp": raw['temperature_2m_max'][i], "min_temp": raw['temperature_2m_min'][i], "weather_code": raw['weather_code'][i], "sunrise": raw['sunrise'][i], "sunset": raw['sunset'][i], "precipitation_sum": raw['precipitation_sum'][i], "precipitation_probability_max": raw['precipitation_probability_max'][i]} for i in range(len(raw['time']))]
+    except requests.exceptions.Timeout:
+        logger.warning(f"Timeout fetching daily forecast for {lat}, {lon}")
+        return None
+    except Exception as e:
+        logger.error(f"Error fetching daily forecast: {e}")
+        return None
+
+
+# --- AQI & ALERTS ---
+def fetch_aqi_and_alerts(lat, lon):
+    try:
+        air_quality_api_url = "https://air-quality-api.open-meteo.com/v1/air-quality"
+        forecast_api_url = "https://api.open-meteo.com/v1/forecast"
+        aqi_params = {"latitude": lat, "longitude": lon, "hourly": "us_aqi,pm2_5,carbon_monoxide,ozone", "timezone": "auto"}
+        alerts_params = {"latitude": lat, "longitude": lon, "daily": "weather_code", "forecast_days": 1}
+
+        aqi_response = requests.get(air_quality_api_url, params=aqi_params, timeout=10)
+        alerts_response = requests.get(forecast_api_url, params=alerts_params, timeout=10)
+        
+        aqi_data = aqi_response.json() if aqi_response.status_code == 200 else None
+        alerts = alerts_response.json().get("daily", {}).get("alerts", []) if alerts_response.status_code == 200 else []
+        
+        return {"aqi": aqi_data, "alerts": alerts}
+    except requests.exceptions.Timeout:
+        logger.warning(f"Timeout fetching AQI/alerts for {lat}, {lon}")
+        return {"aqi": None, "alerts": []}
+    except Exception as e:
+        logger.error(f"Error fetching AQI/alerts: {e}")
+        return {"aqi": None, "alerts": []}
+
+
+# ==================== API ENDPOINTS (Main Branch Compatible) ====================
+
+@app.get("/weather", tags=["Weather"])
+def get_weather(lat: float, lon: float):
+    """Get current weather for a location."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("weather_requests")
+    
+    logger.info(f"GET /weather request for: {lat}, {lon}")
+    
+    # Normalize coordinates
+    lat_norm, lon_norm = normalize_coordinates(lat, lon)
+    
+    # Check in-memory cache first (if available)
+    if HAS_CACHE_MODULE:
+        cache = get_cache()
+        cache_key = generate_weather_cache_key(lat_norm, lon_norm, "current")
+        cached_data = cache.get(cache_key) if cache else None
+        if cached_data:
+            metrics.increment("cache_hits")
+            logger.info(f"MEMORY CACHE HIT for current weather at {lat_norm}, {lon_norm}")
+            return {"source": "cache", **cached_data}
+    
+    # Check SQLite database cache
+    cached = get_weather_from_db(lat_norm, lon_norm)
+    if cached and len(cached) >= 13:
+        metrics.increment("cache_hits")
+        logger.info(f"DB CACHE HIT for current weather at {lat_norm}, {lon_norm}")
+        return {
+            "source": "cache", 
+            "location_name": cached[0],
+            "latitude": cached[1],
+            "longitude": cached[2],
+            "timestamp": cached[3], 
+            "temperature_c": cached[4], 
+            "humidity_pct": cached[5], 
+            "pressure_hpa": cached[6], 
+            "wind_speed_mps": cached[7], 
+            "precip_mm": cached[8], 
+            "weather_code": cached[9], 
+            "apparent_temperature": cached[10], 
+            "uv_index": cached[11], 
+            "is_day": cached[12]
+        }
+    
+    metrics.increment("cache_misses")
+    logger.info(f"CACHE MISS for current weather at {lat_norm}, {lon_norm}. Fetching live data...")
+    
+    # Fetch live data
+    live = fetch_live_weather(lat_norm, lon_norm)
+    if not live:
+        logger.warning(f"Failed to fetch weather data for {lat_norm}, {lon_norm}, returning fallback")
+        return {
+            "source": "unavailable",
+            "location_name": f"Lat_{lat}_Lon_{lon}",
+            "latitude": lat,
+            "longitude": lon,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "temperature_c": 0,
+            "humidity_pct": 0,
+            "pressure_hpa": 0,
+            "wind_speed_mps": 0,
+            "precip_mm": 0,
+            "weather_code": 0,
+            "apparent_temperature": 0,
+            "uv_index": 0,
+            "is_day": 1
+        }
+    
+    # Save to SQLite database
+    save_weather_to_db([live])
+    
+    # Save to in-memory cache (if available)
+    if HAS_CACHE_MODULE:
+        cache = get_cache()
+        if cache:
+            result = {
+                "temperature_c": live["temperature_c"],
+                "humidity_pct": live["humidity_pct"],
+                "pressure_hpa": live["pressure_hpa"],
+                "wind_speed_mps": live["wind_speed_mps"],
+                "precip_mm": live["precip_mm"],
+                "weather_code": live["weather_code"],
+                "apparent_temperature": live["apparent_temperature"],
+                "uv_index": live["uv_index"],
+                "is_day": live["is_day"]
+            }
+            cache_key = generate_weather_cache_key(lat_norm, lon_norm, "current")
+            cache.set(cache_key, result)
+    
+    # Prepare response
+    response = {**live}
+    if 'timestamp' in response and isinstance(response['timestamp'], datetime):
+        response['timestamp'] = response['timestamp'].isoformat()
+    return {"source": "live", **response}
+
+
+@app.get("/hourly", tags=["Weather"])
+def get_hourly_forecast_endpoint(lat: float, lon: float):
+    """Get hourly forecast for a location."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("hourly_requests")
+    
+    lat_norm, lon_norm = normalize_coordinates(lat, lon)
+    
+    # Check SQLite database cache
+    cached = get_hourly_forecast_from_db(lat_norm, lon_norm)
+    if cached and len(cached) >= 24:
+        metrics.increment("cache_hits")
+        logger.info(f"CACHE HIT for hourly forecast at {lat_norm}, {lon_norm}")
+        return [{"time": r[0], "temp": r[1], "precip_prob": r[2], "wind": r[3], "cloud_cover": r[4], "weather_code": r[5]} for r in cached]
+    
+    metrics.increment("cache_misses")
+    logger.info(f"CACHE MISS for hourly forecast at {lat_norm}, {lon_norm}. Fetching live data...")
+    
+    live = fetch_hourly_forecast(lat_norm, lon_norm)
+    if not live:
+        logger.warning(f"Failed to fetch hourly data for {lat_norm}, {lon_norm}, returning empty array")
+        return []
+    
+    save_hourly_forecast_to_db(lat_norm, lon_norm, live)
+    return live
+
+
+@app.get("/forecast", tags=["Weather"])
+def get_daily_forecast_endpoint(lat: float, lon: float):
+    """Get 7-day forecast for a location."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("forecast_requests")
+    
+    lat_norm, lon_norm = normalize_coordinates(lat, lon)
+    
+    # Check SQLite database cache
+    cached = get_forecast_from_db(lat_norm, lon_norm)
+    if cached and len(cached) >= 5:
+        metrics.increment("cache_hits")
+        logger.info(f"CACHE HIT for 5-day forecast at {lat_norm}, {lon_norm}")
+        return [{"date": r[0], "max_temp": r[1], "min_temp": r[2], "weather_code": r[3], "sunrise": r[4], "sunset": r[5], "precipitation_sum": r[6], "precipitation_probability_max": r[7]} for r in cached]
+    
+    metrics.increment("cache_misses")
+    logger.info(f"CACHE MISS for 5-day forecast at {lat_norm}, {lon_norm}. Fetching live data...")
+    
+    live = fetch_daily_forecast(lat_norm, lon_norm)
+    if not live:
+        logger.warning(f"Failed to fetch forecast data for {lat_norm}, {lon_norm}, returning empty array")
+        return []
+    
+    save_forecast_to_db(lat_norm, lon_norm, live)
+    return live
+
+
+@app.get("/aqi-alerts", tags=["Weather"])
+def get_aqi_and_alerts_endpoint(lat: float, lon: float):
+    """Get air quality index and weather alerts for a location."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("aqi_requests")
+    
+    lat_norm, lon_norm = normalize_coordinates(lat, lon)
+    logger.info(f"Fetching AQI & Alerts data for {lat_norm}, {lon_norm}...")
+    
+    data = fetch_aqi_and_alerts(lat_norm, lon_norm)
+    return data if data else {"aqi": None, "alerts": []}
+
+
+@app.get("/api-test", tags=["Health"])
+def api_test():
+    """Simple endpoint to verify API is working."""
+    return {"status": "ok", "message": "Weather API is running!", "timestamp": datetime.now(timezone.utc).isoformat()}
+
+
+@app.get("/api/info", tags=["Health"])
+def api_info():
+    """Get API information."""
+    return {
+        "name": settings.APP_NAME,
+        "version": settings.APP_VERSION,
+        "description": "Production-grade weather API",
+        "endpoints": {
+            "weather": "/weather?lat={lat}&lon={lon}",
+            "hourly": "/hourly?lat={lat}&lon={lon}",
+            "forecast": "/forecast?lat={lat}&lon={lon}",
+            "aqi_alerts": "/aqi-alerts?lat={lat}&lon={lon}",
+            "health": "/healthz",
+            "metrics": "/metrics"
+        }
+    }
+
+
+# ==================== MOUNT STATIC FILES ====================
+# Note: This should be last to avoid conflicts with API routes
+app.mount("/", StaticFiles(directory="static", html=True), name="static")
diff --git a/cache.py b/cache.py
new file mode 100644
index 0000000..64eba69
--- /dev/null
+++ b/cache.py
@@ -0,0 +1,335 @@
+"""
+In-Memory Cache System with TTL
+
+This module provides a thread-safe caching system with:
+- Configurable TTL (Time To Live)
+- Background cleanup thread for expired keys
+- Optional persistence of popular items to CSV storage
+- Integration with weather API endpoints
+"""
+
+import threading
+import time
+from typing import Any, Optional, Dict, List, Callable
+from dataclasses import dataclass
+from datetime import datetime
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class CacheEntry:
+    """Represents a single cache entry with metadata."""
+    value: Any
+    created_at: float
+    expires_at: float
+    hits: int = 0
+    
+    def is_expired(self) -> bool:
+        """Check if this cache entry has expired."""
+        return time.time() > self.expires_at
+    
+    def time_remaining(self) -> float:
+        """Get remaining TTL in seconds."""
+        return max(0, self.expires_at - time.time())
+
+
+class Cache:
+    """
+    Thread-safe in-memory cache with TTL support.
+    
+    Features:
+    - get, set, delete, keys operations
+    - Background cleanup thread
+    - Hit/miss statistics
+    - Size limits
+    - Optional persistence callbacks
+    """
+    
+    def __init__(
+        self,
+        default_ttl: int = None,
+        max_size: int = None,
+        cleanup_interval: int = None
+    ):
+        """
+        Initialize the cache.
+        
+        Args:
+            default_ttl: Default TTL in seconds
+            max_size: Maximum number of items to store
+            cleanup_interval: Interval between cleanup runs in seconds
+        """
+        self._cache: Dict[str, CacheEntry] = {}
+        self._lock = threading.RLock()
+        self._default_ttl = default_ttl or settings.CACHE_TTL_SECONDS
+        self._max_size = max_size or settings.CACHE_MAX_SIZE
+        self._cleanup_interval = cleanup_interval or settings.CACHE_CLEANUP_INTERVAL
+        
+        # Statistics
+        self._hits = 0
+        self._misses = 0
+        self._evictions = 0
+        
+        # Persistence callback
+        self._persist_callback: Optional[Callable[[str, Any], None]] = None
+        
+        # Start background cleanup thread
+        self._cleanup_thread: Optional[threading.Thread] = None
+        self._stop_cleanup = threading.Event()
+        self._start_cleanup_thread()
+        
+        logger.info(
+            f"Cache initialized with TTL={self._default_ttl}s, "
+            f"max_size={self._max_size}, cleanup_interval={self._cleanup_interval}s"
+        )
+    
+    def _start_cleanup_thread(self) -> None:
+        """Start the background cleanup thread."""
+        self._cleanup_thread = threading.Thread(
+            target=self._cleanup_loop,
+            daemon=True,
+            name="cache-cleanup"
+        )
+        self._cleanup_thread.start()
+    
+    def _cleanup_loop(self) -> None:
+        """Background loop that periodically cleans up expired entries."""
+        while not self._stop_cleanup.wait(self._cleanup_interval):
+            self.cleanup_expired()
+    
+    def cleanup_expired(self) -> int:
+        """
+        Remove all expired entries from the cache.
+        
+        Returns:
+            Number of entries removed
+        """
+        removed = 0
+        with self._lock:
+            expired_keys = [
+                key for key, entry in self._cache.items()
+                if entry.is_expired()
+            ]
+            for key in expired_keys:
+                del self._cache[key]
+                removed += 1
+                
+        if removed > 0:
+            logger.debug(f"Cleaned up {removed} expired cache entries")
+            
+        return removed
+    
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get a value from the cache.
+        
+        Args:
+            key: The cache key
+            
+        Returns:
+            The cached value, or None if not found or expired
+        """
+        with self._lock:
+            entry = self._cache.get(key)
+            
+            if entry is None:
+                self._misses += 1
+                return None
+                
+            if entry.is_expired():
+                del self._cache[key]
+                self._misses += 1
+                return None
+                
+            entry.hits += 1
+            self._hits += 1
+            return entry.value
+    
+    def set(
+        self,
+        key: str,
+        value: Any,
+        ttl: Optional[int] = None
+    ) -> None:
+        """
+        Set a value in the cache.
+        
+        Args:
+            key: The cache key
+            value: The value to cache
+            ttl: Optional TTL in seconds (uses default if not specified)
+        """
+        ttl = ttl if ttl is not None else self._default_ttl
+        now = time.time()
+        
+        with self._lock:
+            # Check if we need to evict entries
+            if len(self._cache) >= self._max_size and key not in self._cache:
+                self._evict_lru()
+            
+            self._cache[key] = CacheEntry(
+                value=value,
+                created_at=now,
+                expires_at=now + ttl
+            )
+            
+        logger.debug(f"Cache set: {key} (TTL={ttl}s)")
+    
+    def delete(self, key: str) -> bool:
+        """
+        Delete a key from the cache.
+        
+        Args:
+            key: The cache key
+            
+        Returns:
+            True if the key was deleted, False if not found
+        """
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+                logger.debug(f"Cache delete: {key}")
+                return True
+            return False
+    
+    def keys(self, pattern: Optional[str] = None) -> List[str]:
+        """
+        Get all keys in the cache, optionally filtered by pattern.
+        
+        Args:
+            pattern: Optional prefix pattern to filter keys
+            
+        Returns:
+            List of matching keys
+        """
+        with self._lock:
+            all_keys = list(self._cache.keys())
+            if pattern:
+                return [k for k in all_keys if k.startswith(pattern)]
+            return all_keys
+    
+    def clear(self) -> None:
+        """Clear all entries from the cache."""
+        with self._lock:
+            self._cache.clear()
+        logger.info("Cache cleared")
+    
+    def size(self) -> int:
+        """Get the number of entries in the cache."""
+        with self._lock:
+            return len(self._cache)
+    
+    def stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics.
+        
+        Returns:
+            Dictionary with cache statistics
+        """
+        with self._lock:
+            total_requests = self._hits + self._misses
+            hit_rate = (self._hits / total_requests * 100) if total_requests > 0 else 0
+            
+            return {
+                "size": len(self._cache),
+                "max_size": self._max_size,
+                "hits": self._hits,
+                "misses": self._misses,
+                "hit_rate_percent": round(hit_rate, 2),
+                "evictions": self._evictions,
+                "default_ttl": self._default_ttl
+            }
+    
+    def _evict_lru(self) -> None:
+        """Evict the least recently used entry."""
+        if not self._cache:
+            return
+            
+        # Find entry with lowest hit count (simple LRU approximation)
+        lru_key = min(
+            self._cache.keys(),
+            key=lambda k: self._cache[k].hits
+        )
+        
+        # Persist popular items before eviction
+        entry = self._cache[lru_key]
+        if entry.hits >= 5 and self._persist_callback:
+            try:
+                self._persist_callback(lru_key, entry.value)
+            except Exception as e:
+                logger.error(f"Failed to persist cache entry: {e}")
+        
+        del self._cache[lru_key]
+        self._evictions += 1
+        logger.debug(f"Evicted cache entry: {lru_key}")
+    
+    def set_persist_callback(
+        self,
+        callback: Callable[[str, Any], None]
+    ) -> None:
+        """
+        Set a callback for persisting popular cache entries.
+        
+        Args:
+            callback: Function that takes (key, value) and persists them
+        """
+        self._persist_callback = callback
+    
+    def shutdown(self) -> None:
+        """Shutdown the cache and cleanup thread."""
+        self._stop_cleanup.set()
+        if self._cleanup_thread:
+            self._cleanup_thread.join(timeout=5)
+        logger.info("Cache shutdown complete")
+
+
+def generate_weather_cache_key(lat: float, lon: float, data_type: str = "current") -> str:
+    """
+    Generate a cache key for weather data.
+    
+    Args:
+        lat: Latitude (rounded to 2 decimal places)
+        lon: Longitude (rounded to 2 decimal places)
+        data_type: Type of weather data (current, hourly, daily, aqi)
+        
+    Returns:
+        Cache key string
+    """
+    # Round to 2 decimal places for ~1km precision
+    lat_rounded = round(lat, 2)
+    lon_rounded = round(lon, 2)
+    return f"weather:{data_type}:{lat_rounded}:{lon_rounded}"
+
+
+# Global cache instance
+_cache: Optional[Cache] = None
+
+
+def get_cache() -> Cache:
+    """
+    Get the global cache instance.
+    
+    Returns:
+        The global Cache instance
+    """
+    global _cache
+    if _cache is None:
+        _cache = Cache()
+    return _cache
+
+
+def init_cache() -> Cache:
+    """
+    Initialize (or reinitialize) the global cache.
+    
+    Returns:
+        The new Cache instance
+    """
+    global _cache
+    if _cache:
+        _cache.shutdown()
+    _cache = Cache()
+    return _cache
diff --git a/config.py b/config.py
new file mode 100644
index 0000000..eb64d34
--- /dev/null
+++ b/config.py
@@ -0,0 +1,213 @@
+"""
+Centralized Configuration Module
+
+This module provides a unified configuration system using Pydantic BaseSettings.
+All configuration values can be overridden via environment variables.
+"""
+
+import os
+from typing import List, Optional
+from functools import lru_cache
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """
+    Application settings loaded from environment variables.
+    
+    All settings have sensible defaults for development but should be
+    overridden in production via environment variables.
+    """
+    
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore"
+    )
+    
+    # Application settings
+    APP_NAME: str = "IntelliWeather"
+    APP_VERSION: str = "3.0.1"
+    APP_HOST: str = "0.0.0.0"
+    APP_PORT: int = 8000
+    DEBUG: bool = False
+    
+    # Data storage
+    DATA_DIR: str = "data"
+    
+    # Cache settings
+    CACHE_TTL_SECONDS: int = 3600  # 1 hour default
+    CACHE_MAX_SIZE: int = 1000  # Maximum number of cached items
+    CACHE_CLEANUP_INTERVAL: int = 300  # 5 minutes
+    GEOCODE_CACHE_TTL_SECONDS: int = 86400  # 24 hours for geocoding
+    
+    # Session settings
+    SESSION_TIMEOUT_SECONDS: int = 86400  # 24 hours
+    SESSION_COOKIE_NAME: str = "session_id"
+    SESSION_COOKIE_SECURE: bool = False  # Set to True in production with HTTPS
+    SESSION_COOKIE_HTTPONLY: bool = True
+    SESSION_COOKIE_SAMESITE: str = "lax"
+    SESSION_BACKEND: str = "csv"  # Options: "csv", "redis"
+    
+    # Redis settings (for production session backend)
+    REDIS_URL: Optional[str] = None
+    
+    # Rate limiting
+    RATE_LIMIT_PER_MIN: int = 60  # Requests per minute per IP
+    RATE_LIMIT_WINDOW_SECONDS: int = 60
+    
+    # Security
+    SECRET_KEY: str = "change-this-in-production-use-a-secure-random-key"
+    ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    
+    # Database
+    DB_CONNECTION_STRING: Optional[str] = None
+    
+    # External APIs
+    OPEN_METEO_API_URL: str = "https://api.open-meteo.com/v1/forecast"
+    OPEN_METEO_AIR_QUALITY_URL: str = "https://air-quality-api.open-meteo.com/v1/air-quality"
+    OPEN_METEO_HISTORICAL_URL: str = "https://archive-api.open-meteo.com/v1/archive"
+    GEOCODING_API_URL: str = "https://geocoding-api.open-meteo.com/v1/search"
+    
+    # Popular locations to pre-cache (lat, lon, name)
+    POPULAR_LOCATIONS: List[str] = [
+        "40.7128,-74.0060,New York",
+        "51.5074,-0.1278,London",
+        "35.6762,139.6503,Tokyo",
+        "48.8566,2.3522,Paris",
+        "28.6139,77.2090,New Delhi",
+        "31.5204,74.3587,Lahore",
+        "24.8607,67.0011,Karachi",
+        "19.0760,72.8777,Mumbai",
+        "40.4168,-3.7038,Madrid",
+        "25.2048,55.2708,Dubai"
+    ]
+    
+    # Observability
+    SENTRY_DSN: Optional[str] = None
+    LOG_LEVEL: str = "INFO"
+    LOG_FORMAT: str = "json"  # Options: "json", "text"
+    
+    # CORS settings
+    CORS_ORIGINS: List[str] = ["*"]
+    CORS_ALLOW_CREDENTIALS: bool = True
+    
+    # ==================== PHASE 2 FEATURE FLAGS ====================
+    
+    # Feature toggles (all disabled by default for safety)
+    FEATURE_WEATHER_V2: bool = True  # Hourly/daily/historical endpoints
+    FEATURE_GEOCODING: bool = True  # Geocoding endpoints
+    FEATURE_ALERTS: bool = True  # Weather alerts
+    FEATURE_DOWNLOADS: bool = True  # PDF/Excel downloads
+    FEATURE_ADMIN_DASHBOARD: bool = True  # Admin analytics
+    FEATURE_DARK_MODE: bool = True  # Frontend dark mode
+    FEATURE_I18N: bool = True  # Multi-language support
+    FEATURE_API_KEYS: bool = True  # API key management
+    FEATURE_ML_PREDICTION: bool = True  # ML temperature prediction
+    
+    # Alerts configuration
+    ALERTS_PREFETCH_INTERVAL_HOURS: int = 6
+    ALERTS_ENABLED: bool = True
+    
+    # Download/Reports configuration
+    REPORTS_CACHE_TTL_SECONDS: int = 1800  # 30 minutes
+    REPORTS_MAX_DAYS: int = 30
+    
+    # API Keys configuration
+    API_KEY_RATE_LIMIT_DEFAULT: int = 100  # Requests per minute per key
+    API_KEY_ENABLED: bool = True
+    
+    # ML Prediction configuration
+    ML_MODEL_RETRAIN_HOURS: int = 24
+    ML_HISTORICAL_DAYS: int = 365
+    
+    # i18n configuration
+    DEFAULT_LANGUAGE: str = "en"
+    SUPPORTED_LANGUAGES: List[str] = ["en", "hi", "ur", "ar", "es"]
+    
+    # Admin configuration
+    ADMIN_EMAILS: List[str] = []  # List of admin email addresses
+    
+    # ==================== PHASE 3 FEATURE FLAGS ====================
+    
+    # Notifications
+    FEATURE_NOTIFICATIONS: bool = True
+    SMTP_HOST: Optional[str] = None
+    SMTP_PORT: int = 587
+    SMTP_USERNAME: Optional[str] = None
+    SMTP_PASSWORD: Optional[str] = None
+    SENDGRID_API_KEY: Optional[str] = None
+    FROM_EMAIL: str = "noreply@intelliweather.io"
+    
+    # Twilio SMS
+    TWILIO_ACCOUNT_SID: Optional[str] = None
+    TWILIO_AUTH_TOKEN: Optional[str] = None
+    TWILIO_PHONE_NUMBER: Optional[str] = None
+    
+    # Web Push
+    VAPID_PRIVATE_KEY: Optional[str] = None
+    VAPID_PUBLIC_KEY: Optional[str] = None
+    VAPID_EMAIL: str = "admin@intelliweather.io"
+    
+    # Background Jobs
+    FEATURE_BACKGROUND_JOBS: bool = True
+    JOB_QUEUE_BACKEND: str = "memory"  # Options: "memory", "redis", "rq", "celery"
+    
+    # PostgreSQL (alternative to CSV storage)
+    POSTGRES_URL: Optional[str] = None
+    
+    # Observability
+    PROMETHEUS_ENABLED: bool = True
+    GRAFANA_ENABLED: bool = False
+    
+    # Growth Features
+    FEATURE_ANALYTICS: bool = True
+    FEATURE_REFERRALS: bool = True
+    FEATURE_SHAREABLE_LINKS: bool = True
+    FEATURE_SOCIAL_PREVIEW: bool = True
+    
+    # Access Tiers
+    FREE_TIER_REQUESTS_PER_DAY: int = 100
+    PRO_TIER_REQUESTS_PER_DAY: int = 10000
+    
+    # Animation settings
+    FEATURE_ANIMATIONS: bool = True
+    REDUCED_MOTION_DEFAULT: bool = False
+    
+    def get_data_path(self, filename: str) -> str:
+        """Get the full path for a data file."""
+        return os.path.join(self.DATA_DIR, filename)
+    
+    def parse_popular_locations(self) -> List[dict]:
+        """Parse popular locations into a list of dictionaries."""
+        locations = []
+        for loc in self.POPULAR_LOCATIONS:
+            parts = loc.split(",")
+            if len(parts) >= 3:
+                locations.append({
+                    "lat": float(parts[0]),
+                    "lon": float(parts[1]),
+                    "name": ",".join(parts[2:])
+                })
+        return locations
+    
+    def is_admin(self, email: str) -> bool:
+        """Check if an email is an admin."""
+        return email.lower() in [e.lower() for e in self.ADMIN_EMAILS]
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """
+    Get cached settings instance.
+    
+    This function is cached to avoid re-reading environment variables
+    on every call. Use `get_settings.cache_clear()` to reload settings.
+    """
+    return Settings()
+
+
+# Convenience function for accessing settings
+settings = get_settings()
diff --git a/demo_phase2.md b/demo_phase2.md
new file mode 100644
index 0000000..255d04f
--- /dev/null
+++ b/demo_phase2.md
@@ -0,0 +1,270 @@
+# Phase 2 Demo Script
+
+## Demo Duration: 7-10 minutes
+
+This script guides you through demonstrating the Phase 2 features of IntelliWeather API.
+
+---
+
+## Setup (Before Demo)
+
+```bash
+# Start the server
+cd Weather-API
+pip install -r requirements.txt
+uvicorn app:app --reload --port 8000
+
+# Open Swagger docs
+open http://localhost:8000/docs
+```
+
+---
+
+## Part 1: Weather V2 Endpoints (2 min)
+
+### Show Enhanced Weather API
+
+1. **Open Swagger UI** at `http://localhost:8000/docs`
+   - Point out the organized tags: Weather V2, Geocoding, Alerts, etc.
+
+2. **Hourly Forecast**
+   ```bash
+   curl "http://localhost:8000/weather/hourly?lat=40.7128&lon=-74.006&hours=48"
+   ```
+   - Show the structured JSON response
+   - Highlight: temperature, humidity, precipitation probability
+
+3. **CSV Export**
+   ```bash
+   curl "http://localhost:8000/weather/hourly?lat=40.7128&lon=-74.006&format=csv" -o hourly.csv
+   open hourly.csv
+   ```
+   - "Users can export data to CSV for their own analysis"
+
+4. **Historical Data**
+   ```bash
+   curl "http://localhost:8000/weather/historical?lat=40.7128&lon=-74.006&start=2024-01-01&end=2024-01-07"
+   ```
+   - "We can fetch historical weather for any date range up to 1 year"
+
+---
+
+## Part 2: Geocoding & Search (1 min)
+
+### Location Search
+
+1. **Search for a city**
+   ```bash
+   curl "http://localhost:8000/geocode/search?q=Lahore&limit=3"
+   ```
+   - Show coordinates, country, timezone, population
+
+2. **Reverse Geocoding**
+   ```bash
+   curl "http://localhost:8000/geocode/reverse?lat=31.5204&lon=74.3587"
+   ```
+   - "From coordinates, we can get the location name"
+
+3. **Show Cache Hit**
+   - Make the same request again
+   - Point out `"source": "cache"` in response
+   - "Second request is instant - served from cache"
+
+---
+
+## Part 3: Weather Alerts (1 min)
+
+### Alert System
+
+1. **Get Alerts**
+   ```bash
+   curl "http://localhost:8000/alerts?lat=40.7128&lon=-74.006"
+   ```
+   - Show alert structure: severity, headline, instructions
+
+2. **Explain the System**
+   - "Alerts are generated based on weather conditions"
+   - "In production, this would integrate with National Weather Service"
+   - "Alerts are cached for 15 minutes"
+
+---
+
+## Part 4: Downloadable Reports (1.5 min)
+
+### PDF and Excel Reports
+
+1. **Download PDF Report**
+   ```bash
+   curl "http://localhost:8000/weather/download?lat=40.7128&lon=-74.006&type=pdf&range=daily&days=7" -o report.pdf
+   open report.pdf
+   ```
+   - Show the formatted report with temperature chart
+
+2. **Download Excel Report**
+   ```bash
+   curl "http://localhost:8000/weather/download?lat=40.7128&lon=-74.006&type=excel&range=daily&days=7" -o report.xlsx
+   open report.xlsx
+   ```
+   - Show multiple sheets: Weather data, Metadata
+   - "Excel files have proper styling and formatting"
+
+---
+
+## Part 5: ML Prediction (1 min)
+
+### Temperature Prediction
+
+1. **Get Next-Day Prediction**
+   ```bash
+   curl "http://localhost:8000/predict/nextday?lat=40.7128&lon=-74.006"
+   ```
+   - Show predicted temperature and confidence interval
+   - "Simple ML model using historical data"
+
+2. **Model Info**
+   ```bash
+   curl "http://localhost:8000/predict/model/info"
+   ```
+   - Show model version and training date
+
+---
+
+## Part 6: Multi-Language Support (1 min)
+
+### Internationalization
+
+1. **Show Supported Languages**
+   ```bash
+   curl "http://localhost:8000/i18n/languages"
+   ```
+   - List: English, Hindi, Urdu, Arabic, Spanish
+
+2. **Get Hindi Translations**
+   ```bash
+   curl "http://localhost:8000/i18n/translations?lang=hi" | jq '.translations | {current_weather, feels_like, humidity}'
+   ```
+   - Show Hindi text
+
+3. **Weather Description in Arabic**
+   ```bash
+   curl "http://localhost:8000/i18n/weather-description?code=3&lang=ar"
+   ```
+   - Show Arabic translation
+
+---
+
+## Part 7: API Key System (1 min)
+
+### API Key Management
+
+1. **Login First**
+   ```bash
+   curl -X POST "http://localhost:8000/auth/login" \
+     -H "Content-Type: application/json" \
+     -d '{"email":"demo@example.com","password":"demo123"}' \
+     -c cookies.txt
+   ```
+
+2. **Create API Key**
+   ```bash
+   curl -X POST "http://localhost:8000/apikeys" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"Demo Key","rate_limit":100}' \
+     -b cookies.txt
+   ```
+   - "Key is only shown once - store securely"
+
+3. **Use API Key**
+   ```bash
+   curl "http://localhost:8000/weather/hourly?lat=40.7128&lon=-74.006" \
+     -H "X-API-Key: YOUR_API_KEY"
+   ```
+   - "Each key has its own rate limit"
+
+---
+
+## Part 8: Admin Dashboard (1 min)
+
+### Analytics Dashboard
+
+1. **Open Dashboard**
+   - Navigate to `http://localhost:8000/admin/dashboard`
+   - (Requires admin user)
+
+2. **Show Statistics**
+   - Total users
+   - Active sessions
+   - Cache hit rate
+   - Top searched locations
+
+3. **System Health**
+   - Storage status
+   - Cache operational
+   - API connectivity
+
+---
+
+## Part 9: Scaling Demo (Optional, 1 min)
+
+### Docker Scaling
+
+```bash
+# Show docker-compose
+cat docker-compose.yml
+
+# Scale to 3 instances
+docker-compose up -d --scale app=3
+
+# Show NGINX load balancing
+curl http://localhost/weather?lat=40.7128&lon=-74.006
+```
+
+---
+
+## Closing Points
+
+1. **Architecture Highlights**
+   - Multi-tier caching (memory → CSV → external API)
+   - Feature flags for all Phase 2 features
+   - Structured JSON logging
+   - Thread-safe operations
+
+2. **Production Ready**
+   - Docker support with load balancing
+   - Health checks and metrics
+   - Rate limiting per IP and per API key
+   - Secure session management
+
+3. **Documentation**
+   - Swagger/OpenAPI docs
+   - README.md
+   - QA checklist
+   - Demo scripts
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Server won't start | Check `pip install -r requirements.txt` |
+| 401 errors | Login first or provide API key |
+| 429 errors | Rate limit hit, wait 60 seconds |
+| Empty alerts | No severe weather at that location |
+| PDF not rendering | Check if data fetched successfully |
+
+---
+
+## Q&A Preparation
+
+**Q: Why CSV storage instead of a database?**
+A: Simpler setup, no external dependencies. Demonstrates file-based persistence. Production would use PostgreSQL/Redis.
+
+**Q: How does the ML model work?**
+A: Linear regression on historical temperatures. Features: day of year (cyclical), previous temps, trend.
+
+**Q: How accurate are predictions?**
+A: Simple model with ±3°C confidence. Production would use more sophisticated approaches.
+
+**Q: What happens if Open-Meteo is down?**
+A: Cached data is returned if available. Error responses include 503 status with clear message.
diff --git a/demo_phase3.md b/demo_phase3.md
new file mode 100644
index 0000000..08f6e8e
--- /dev/null
+++ b/demo_phase3.md
@@ -0,0 +1,310 @@
+# Phase 3 Demo Script
+
+This guide walks through demonstrating all Phase 3 features of IntelliWeather.
+
+## Prerequisites
+
+- Docker Desktop running
+- Terminal/command line access
+- Web browser (Chrome/Firefox recommended)
+
+## Setup
+
+```bash
+# Clone and navigate to repository
+cd Weather-API
+
+# Start the application
+docker-compose up -d --build
+
+# Verify it's running
+curl http://localhost:8000/healthz
+```
+
+## Demo Flow (15-20 minutes)
+
+### 1. Professional UI Overview (3 min)
+
+**Open Browser**: Navigate to `http://localhost:8000`
+
+**Header Tour**:
+- Point out the IntelliWeather logo with weather icon
+- Show navigation links: Dashboard, Maps, Alerts, Historical, API Docs
+- Highlight the theme toggle button (moon/sun icon)
+- Show Sign In / Get Started buttons
+
+**Dashboard**:
+- Location automatically detected (or defaults to New York)
+- Current date displayed
+- Search box with magnifying glass icon
+- Tab navigation: Now, Hourly, 7-Day
+
+**Weather Display**:
+- Large weather icon with bounce animation
+- Temperature with gradient text effect
+- Weather description
+- Details grid: Feels Like, Humidity, Wind, UV Index, Air Quality, Precipitation
+
+**Footer Tour**:
+- Scroll to bottom of page
+- Show branding with logo and description
+- Point out social media links
+- Product, Resources, Company link columns
+- Copyright and language selector
+
+### 2. Dark/Light Mode (2 min)
+
+**Toggle Theme**:
+```
+Click the moon icon in the header
+```
+
+**Observe**:
+- Smooth transition (no flash)
+- Background changes from light to dark
+- Text colors invert
+- Cards adjust styling
+- Footer updates
+
+**Persistence**:
+```
+1. Refresh the page (F5)
+2. Theme stays in dark mode
+3. Click sun icon to switch back to light
+```
+
+**System Preference**:
+- Mention that first visit respects system preference
+- Demo by changing system dark mode setting (if time permits)
+
+### 3. Animation System (2 min)
+
+**Page Animations**:
+- Refresh page to see entrance animation
+- Dashboard fades in and slides up
+- Weather card has shimmer effect
+
+**Interaction Animations**:
+```
+1. Hover over a detail card
+2. Card lifts up with shadow
+3. Switch to Hourly tab
+4. Items animate in with stagger effect
+5. Hover over hourly item - rises and glows
+6. Switch to 7-Day tab
+7. Items slide in from left with stagger
+```
+
+**Weather Icon**:
+- Point out the gentle bounce animation
+- Mention it uses `requestAnimationFrame` for smoothness
+
+**Reduced Motion**:
+```
+If demonstrating accessibility:
+1. Open system preferences
+2. Enable "Reduce motion"
+3. Refresh page
+4. Animations are disabled
+```
+
+### 4. Search Experience (2 min)
+
+**Search Flow**:
+```
+1. Click in search box
+2. Type "London"
+3. See loading spinner
+4. Results appear with animation
+5. Use arrow keys to navigate
+6. Press Enter or click to select
+```
+
+**Features to Highlight**:
+- Debounced search (300ms delay)
+- Keyboard navigation support
+- Smooth dropdown animation
+- Arrow indicator on hover/selection
+
+### 5. Kubernetes Deployment (3 min)
+
+**Show Manifests**:
+```bash
+# Open k8s/deployment.yaml in editor
+cat k8s/deployment.yaml | head -50
+```
+
+**Highlight**:
+- Deployment with 3 replicas
+- Resource limits (100m CPU, 256Mi memory)
+- Health probes (liveness, readiness)
+- HorizontalPodAutoscaler (2-10 replicas)
+- PodDisruptionBudget
+
+**Local Demo** (if kind installed):
+```bash
+cd k8s/local
+./local-setup.sh setup
+
+# Check status
+./local-setup.sh status
+
+# Show pods
+kubectl get pods -n intelliweather
+
+# Port forward
+./local-setup.sh forward
+# Then open http://localhost:8080
+```
+
+**Helm Chart**:
+```bash
+# Show Helm structure
+ls -la helm/intelliweather/
+
+# View values
+cat helm/intelliweather/values.yaml | head -30
+```
+
+### 6. Monitoring & Observability (3 min)
+
+**Prometheus Metrics**:
+```bash
+# View metrics endpoint
+curl http://localhost:8000/metrics/prometheus
+
+# Key metrics:
+# - http_request_total
+# - http_request_duration_seconds
+# - cache_hits_total
+# - active_sessions
+```
+
+**Show Grafana Dashboard**:
+```bash
+# Open the JSON file
+cat monitoring/grafana-dashboard.json | jq '.panels[].title'
+```
+
+**Panels include**:
+- Request Rate by Method
+- Response Latency (p50, p95, p99)
+- Cache Hit Ratio gauge
+- Active Sessions stat
+- Requests by Status Code
+- CPU/Memory gauges
+
+**Alert Rules**:
+```bash
+cat monitoring/alert_rules.yml | grep "alert:"
+```
+
+**Alerts**:
+- HighErrorRate (>5% 5xx errors)
+- HighLatency (>2s p95)
+- LowCacheHitRatio (<50%)
+- ServiceDown
+
+### 7. Notifications System (2 min)
+
+**Show Code Structure**:
+```bash
+cat notifications/__init__.py | head -100
+```
+
+**Features**:
+- Pluggable backend architecture
+- EmailBackend (SMTP + SendGrid)
+- SMSBackend (Twilio)
+- WebPushBackend
+- InAppBackend
+
+**Configuration**:
+```bash
+grep -A5 "Notifications" config.py
+```
+
+**Environment Variables**:
+- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`
+- `SENDGRID_API_KEY`
+- `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`
+
+### 8. CI/CD Pipeline (2 min)
+
+**Show Workflow**:
+```bash
+cat .github/workflows/ci-cd.yml
+```
+
+**Pipeline Stages**:
+1. **Test**: Run pytest with coverage
+2. **Build**: Build multi-platform Docker image
+3. **Security**: Trivy vulnerability scan
+4. **Deploy Staging**: On develop branch
+5. **Deploy Production**: On version tags (v*)
+
+**Triggers**:
+- Push to main/develop
+- Pull requests to main
+- Version tags (v*)
+
+### 9. Documentation (1 min)
+
+**Show Docs**:
+```bash
+# Deployment guide
+head -50 docs/DEPLOYMENT.md
+
+# CDN guide
+head -50 docs/CDN.md
+```
+
+**Topics Covered**:
+- Docker quick start
+- Kubernetes deployment
+- Cloud providers (AWS, GCP, Azure, DigitalOcean)
+- Cloudflare/Fastly CDN setup
+- Cache configuration
+- Edge workers
+
+## Q&A
+
+**Common Questions**:
+
+1. **Q: How do I deploy to production?**
+   A: Use the Helm chart with your values.yaml or apply k8s manifests directly.
+
+2. **Q: How do I enable real notifications?**
+   A: Set the SMTP or SendGrid environment variables for email, Twilio for SMS.
+
+3. **Q: Does it scale automatically?**
+   A: Yes, HPA scales from 2-10 replicas based on CPU/memory.
+
+4. **Q: How is caching handled?**
+   A: In-memory by default, Redis optional for distributed caching.
+
+5. **Q: What about HTTPS?**
+   A: The Ingress supports TLS with cert-manager annotations.
+
+## Cleanup
+
+```bash
+# Stop Docker containers
+docker-compose down
+
+# Delete kind cluster (if created)
+./k8s/local/local-setup.sh cleanup
+```
+
+## Summary
+
+Phase 3 transforms IntelliWeather into a production-ready application with:
+
+✅ **Professional UI** - Modern design with header, footer, branding
+✅ **Dark/Light Mode** - User preference with persistence
+✅ **Smooth Animations** - Hardware-accelerated, accessibility-aware
+✅ **Kubernetes Ready** - Full manifests and Helm chart
+✅ **Observability** - Prometheus, Grafana, Alertmanager
+✅ **Notifications** - Email, SMS, Push, In-App
+✅ **CI/CD** - GitHub Actions with multi-stage pipeline
+✅ **Documentation** - Deployment, CDN, troubleshooting guides
diff --git a/demo_script.md b/demo_script.md
new file mode 100644
index 0000000..6fa6442
--- /dev/null
+++ b/demo_script.md
@@ -0,0 +1,301 @@
+# 🎓 Demo Script - IntelliWeather API
+
+## Final Year Project Presentation Guide
+
+This guide provides step-by-step instructions for demonstrating the IntelliWeather API to judges and examiners.
+
+---
+
+## 📋 Pre-Demo Setup (10 minutes before)
+
+### 1. Start the Services
+
+```bash
+# Navigate to project directory
+cd Weather-API
+
+# Option A: Local development
+pip install -r requirements.txt
+uvicorn app:app --reload --host 0.0.0.0 --port 8000
+
+# Option B: Docker (recommended for demo)
+docker-compose up -d --scale app=2
+```
+
+### 2. Verify Services Running
+
+```bash
+# Check health
+curl http://localhost:8000/healthz
+
+# Expected output:
+# {"status":"healthy","timestamp":"...","checks":{...}}
+```
+
+### 3. Open Browser Tabs
+- Tab 1: http://localhost:8000 (Dashboard)
+- Tab 2: http://localhost:8000/docs (API Documentation)
+- Tab 3: Terminal for curl commands
+
+---
+
+## 🎬 Demo Presentation (15-20 minutes)
+
+### Part 1: UI Dashboard (3 minutes)
+
+**Show the modern weather dashboard:**
+
+1. Open http://localhost:8000 in browser
+2. Point out key features:
+   - Glassmorphism design with backdrop blur
+   - Dynamic gradient background
+   - Connection status indicator (top right)
+   - Responsive layout
+
+3. Search for a city:
+   - Type "London" in search box
+   - Show autocomplete suggestions
+   - Select a city to load weather
+
+4. Navigate tabs:
+   - **Now**: Current weather with details
+   - **Hourly**: 24-hour forecast with scroll
+   - **7-Day**: Weekly forecast
+
+**Talking Points:**
+> "This is our production-ready weather dashboard. Notice the modern glassmorphism design that changes based on weather conditions. The connection indicator shows real-time backend connectivity."
+
+---
+
+### Part 2: API Endpoints (4 minutes)
+
+**Open the Swagger docs:**
+
+1. Navigate to http://localhost:8000/docs
+2. Show the available endpoints:
+   - `/weather` - Current conditions
+   - `/hourly` - Hourly forecast
+   - `/forecast` - 7-day forecast
+   - `/aqi-alerts` - Air quality
+
+3. **Live API Call Demo:**
+
+```bash
+# In terminal, show a weather request
+curl "http://localhost:8000/weather?lat=40.71&lon=-74.01" | jq
+
+# Expected output:
+# {
+#   "source": "live",  # or "cache"
+#   "temperature_c": 22.5,
+#   "humidity_pct": 65,
+#   ...
+# }
+```
+
+**Talking Points:**
+> "Our API follows REST principles with standardized JSON responses. We use Open-Meteo as our weather data provider, which gives us global coverage without API key requirements."
+
+---
+
+### Part 3: Caching System (4 minutes)
+
+**Demonstrate cache behavior:**
+
+1. **First request (cache miss):**
+```bash
+# Clear any existing cache by restarting, then:
+curl "http://localhost:8000/weather?lat=51.51&lon=-0.13"
+# Check logs: "CACHE MISS for current weather"
+```
+
+2. **Second request (cache hit):**
+```bash
+curl "http://localhost:8000/weather?lat=51.51&lon=-0.13"
+# Check logs: "CACHE HIT for current weather"
+```
+
+3. **Show cache statistics:**
+```bash
+curl http://localhost:8000/metrics | jq '.cache'
+# Shows: hits, misses, hit_rate_percent
+```
+
+**Talking Points:**
+> "We implemented a multi-tier caching strategy. First, we check our in-memory cache with configurable TTL. This dramatically reduces API calls and improves response times from ~500ms to under 10ms."
+
+---
+
+### Part 4: User Authentication (3 minutes)
+
+**Demonstrate signup/login flow:**
+
+1. **Create account:**
+```bash
+curl -X POST http://localhost:8000/auth/signup \
+  -H "Content-Type: application/json" \
+  -d '{"username":"demo_user","email":"demo@test.com","password":"DemoPass123"}' \
+  -c cookies.txt
+```
+
+2. **Check session:**
+```bash
+curl http://localhost:8000/auth/session -b cookies.txt
+# Shows authenticated: true
+```
+
+3. **Access protected endpoint:**
+```bash
+curl http://localhost:8000/auth/me -b cookies.txt
+# Returns user info
+```
+
+4. **Logout:**
+```bash
+curl -X POST http://localhost:8000/auth/logout -b cookies.txt
+```
+
+**Talking Points:**
+> "Our authentication uses secure server-side sessions with bcrypt password hashing. Sessions are stored in CSV files for simplicity, but we've designed it to easily swap to Redis for production scale."
+
+---
+
+### Part 5: Rate Limiting (2 minutes)
+
+**Demonstrate rate limiting:**
+
+```bash
+# Rapid requests
+for i in {1..70}; do
+  echo -n "Request $i: "
+  curl -s -o /dev/null -w "%{http_code}" "http://localhost:8000/weather?lat=40.71&lon=-74.01"
+  echo
+done
+
+# After ~60 requests, you'll see 429 (Too Many Requests)
+```
+
+**Talking Points:**
+> "Rate limiting protects our service from abuse. We use a sliding window algorithm that allows 60 requests per minute per IP address. Clients receive helpful headers showing remaining quota."
+
+---
+
+### Part 6: Health & Metrics (2 minutes)
+
+**Show observability endpoints:**
+
+1. **Health check:**
+```bash
+curl http://localhost:8000/healthz | jq
+```
+
+2. **Metrics:**
+```bash
+curl http://localhost:8000/metrics | jq
+```
+
+**Talking Points:**
+> "For production monitoring, we expose health checks for load balancers and detailed metrics including request counts, cache performance, and active sessions. This integrates with Prometheus and Grafana for dashboards."
+
+---
+
+### Part 7: Docker & Scaling (3 minutes)
+
+**Show containerized deployment:**
+
+```bash
+# Show running containers
+docker-compose ps
+
+# Scale up
+docker-compose up -d --scale app=3
+
+# Verify 3 replicas
+docker-compose ps
+
+# Show load balancing
+for i in {1..6}; do
+  curl -s http://localhost/healthz > /dev/null
+done
+docker-compose logs nginx | tail -10
+```
+
+**Talking Points:**
+> "Our application is fully containerized with Docker. The docker-compose setup includes NGINX as a load balancer distributing traffic across multiple app replicas. This allows horizontal scaling to handle increased traffic."
+
+---
+
+## 🏆 Key Points to Emphasize
+
+### Technical Achievements
+1. **Modern Stack**: FastAPI + Python 3.11
+2. **Production Patterns**: Caching, rate limiting, health checks
+3. **Clean Architecture**: Modular design with separation of concerns
+4. **Type Safety**: Full type hints throughout
+5. **Testing**: Comprehensive unit tests
+
+### Competitive Advantages vs AccuWeather
+1. **Free & Open**: No API key required (Open-Meteo)
+2. **Self-Hosted**: Full control over data
+3. **Modern UI**: Glassmorphism design
+4. **Lightweight**: Minimal dependencies
+5. **Scalable**: Docker-ready
+
+### Production Readiness
+1. ✅ In-memory caching with TTL
+2. ✅ CSV-based persistence (upgradeable to PostgreSQL)
+3. ✅ Session management
+4. ✅ Rate limiting
+5. ✅ Health checks
+6. ✅ Metrics/observability
+7. ✅ Docker containerization
+8. ✅ NGINX load balancing
+
+---
+
+## 🎯 Answers to Common Questions
+
+**Q: Why CSV storage instead of a database?**
+> "CSV storage provides simplicity for demonstration and development. The storage layer is abstracted, making it easy to swap in PostgreSQL or any other database without changing application code."
+
+**Q: How does the caching work?**
+> "We use a multi-tier approach: in-memory cache checked first (fastest), then database cache, then external API. The in-memory cache uses LRU eviction with configurable TTL."
+
+**Q: Can this scale to handle more users?**
+> "Yes! The Docker setup supports horizontal scaling. Add more replicas with `--scale app=N`. For persistent sessions across replicas, we'd switch to Redis (already scaffolded in the code)."
+
+**Q: How secure is the authentication?**
+> "Passwords are hashed with bcrypt (work factor 12). Sessions use secure, httpOnly cookies. The rate limiter prevents brute force attacks."
+
+**Q: What would you improve for production?**
+> "Redis for sessions, PostgreSQL for persistence, Sentry for error tracking (already integrated), and Kubernetes for orchestration."
+
+---
+
+## 📸 Screenshot Opportunities
+
+1. Dashboard with weather data loaded
+2. Swagger API documentation page
+3. Terminal showing cache hit/miss logs
+4. Metrics endpoint output
+5. Docker containers running
+6. Rate limit 429 response
+
+---
+
+## ⏱️ Timing Summary
+
+| Section | Duration |
+|---------|----------|
+| UI Dashboard | 3 min |
+| API Endpoints | 4 min |
+| Caching System | 4 min |
+| Authentication | 3 min |
+| Rate Limiting | 2 min |
+| Health & Metrics | 2 min |
+| Docker & Scaling | 3 min |
+| **Total** | **~20 min** |
+
+---
+
+Good luck with your presentation! 🎉
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..609a840
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,102 @@
+# IntelliWeather API - Docker Compose Configuration
+# 
+# This configuration includes:
+# - Multiple app replicas for load balancing
+# - NGINX reverse proxy/load balancer
+# - Redis for session storage (production)
+# - Volume mounts for data persistence
+#
+# Usage:
+#   docker-compose up -d                  # Start all services
+#   docker-compose up -d --scale app=3    # Start with 3 app replicas
+#   docker-compose logs -f                # View logs
+#   docker-compose down                   # Stop all services
+
+version: '3.8'
+
+services:
+  # ==================== APPLICATION ====================
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      - APP_NAME=IntelliWeather
+      - APP_HOST=0.0.0.0
+      - APP_PORT=8000
+      - DATA_DIR=/app/data
+      - CACHE_TTL_SECONDS=3600
+      - SESSION_TIMEOUT_SECONDS=86400
+      - RATE_LIMIT_PER_MIN=60
+      - LOG_LEVEL=INFO
+      - LOG_FORMAT=json
+      # Uncomment for Redis session backend (recommended for multiple replicas)
+      # - SESSION_BACKEND=redis
+      # - REDIS_URL=redis://redis:6379/0
+      # Uncomment for Sentry error tracking
+      # - SENTRY_DSN=${SENTRY_DSN}
+    volumes:
+      - app_data:/app/data
+    expose:
+      - "8000"
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz')"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+    restart: unless-stopped
+    deploy:
+      replicas: 2
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+        reservations:
+          cpus: '0.25'
+          memory: 256M
+
+  # ==================== NGINX LOAD BALANCER ====================
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./static:/usr/share/nginx/html/static:ro
+    depends_on:
+      - app
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost/healthz"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    restart: unless-stopped
+
+  # ==================== REDIS (Optional - for production sessions) ====================
+  # Uncomment to enable Redis session backend
+  # redis:
+  #   image: redis:7-alpine
+  #   command: redis-server --appendonly yes
+  #   volumes:
+  #     - redis_data:/data
+  #   expose:
+  #     - "6379"
+  #   healthcheck:
+  #     test: ["CMD", "redis-cli", "ping"]
+  #     interval: 30s
+  #     timeout: 10s
+  #     retries: 3
+  #   restart: unless-stopped
+
+volumes:
+  app_data:
+    driver: local
+  # redis_data:
+  #   driver: local
+
+networks:
+  default:
+    name: intelliweather_network
+    driver: bridge
diff --git a/docs/CDN.md b/docs/CDN.md
new file mode 100644
index 0000000..3dc6176
--- /dev/null
+++ b/docs/CDN.md
@@ -0,0 +1,451 @@
+# IntelliWeather CDN Integration Guide
+
+This guide covers integrating IntelliWeather with Content Delivery Networks (CDNs) for improved performance and global distribution.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Cloudflare Setup](#cloudflare-setup)
+- [Fastly Setup](#fastly-setup)
+- [Cache Headers](#cache-headers)
+- [Edge Computing](#edge-computing)
+- [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+CDN integration provides:
+
+- **Reduced latency** - Serve content from edge locations closer to users
+- **Improved availability** - Multiple origin servers and failover
+- **DDoS protection** - Built-in protection at the edge
+- **SSL/TLS termination** - Handle HTTPS at the edge
+- **Caching** - Reduce load on origin servers
+
+### What to Cache
+
+| Content Type | Cache Duration | Notes |
+|-------------|----------------|-------|
+| Static assets (CSS, JS, images) | 1 year | Versioned filenames recommended |
+| Weather data (current) | 5-15 minutes | Short TTL for freshness |
+| Weather data (forecast) | 30-60 minutes | Longer TTL acceptable |
+| Geocoding results | 24 hours | Rarely changes |
+| API documentation | 1 hour | Semi-static |
+| Authentication endpoints | No cache | Always bypass |
+
+---
+
+## Cloudflare Setup
+
+### DNS Configuration
+
+```
+# Point your domain to Cloudflare
+weather.example.com    A    <cloudflare-ip>
+weather.example.com    AAAA <cloudflare-ipv6>
+```
+
+### Page Rules
+
+```
+# Cache static assets
+URL: weather.example.com/static/*
+Settings:
+  - Cache Level: Cache Everything
+  - Edge Cache TTL: 1 month
+  - Browser Cache TTL: 1 year
+
+# Cache weather API with short TTL
+URL: weather.example.com/weather*
+Settings:
+  - Cache Level: Cache Everything
+  - Edge Cache TTL: 5 minutes
+  - Origin Cache Control: On
+
+# Bypass cache for auth
+URL: weather.example.com/auth/*
+Settings:
+  - Cache Level: Bypass
+  - Security Level: High
+```
+
+### Cache Rules (Modern)
+
+```json
+// Cloudflare Dashboard > Rules > Cache Rules
+
+// Rule 1: Static Assets
+{
+  "expression": "(http.request.uri.path starts_with \"/static\")",
+  "action": "cache",
+  "cache_ttl": {
+    "default": 2592000
+  }
+}
+
+// Rule 2: Weather API
+{
+  "expression": "(http.request.uri.path starts_with \"/weather\")",
+  "action": "cache",
+  "cache_ttl": {
+    "default": 300
+  },
+  "cache_key": {
+    "query_string": {
+      "include": ["lat", "lon", "units"]
+    }
+  }
+}
+
+// Rule 3: Bypass Auth
+{
+  "expression": "(http.request.uri.path starts_with \"/auth\")",
+  "action": "bypass"
+}
+```
+
+### Cloudflare Worker (Edge Caching)
+
+```javascript
+// workers/weather-cache.js
+// Intelligent edge caching for weather data
+
+const CACHE_CONFIG = {
+  '/weather': { ttl: 300, vary: ['lat', 'lon'] },
+  '/forecast': { ttl: 1800, vary: ['lat', 'lon', 'days'] },
+  '/geocode': { ttl: 86400, vary: ['q'] },
+  '/hourly': { ttl: 900, vary: ['lat', 'lon'] },
+};
+
+addEventListener('fetch', event => {
+  event.respondWith(handleRequest(event.request));
+});
+
+async function handleRequest(request) {
+  const url = new URL(request.url);
+  const path = url.pathname;
+  
+  // Find matching cache config
+  const config = Object.entries(CACHE_CONFIG).find(([p]) => path.startsWith(p));
+  
+  if (!config) {
+    // No caching - pass through
+    return fetch(request);
+  }
+  
+  const [, { ttl, vary }] = config;
+  
+  // Build cache key from path and vary parameters
+  const cacheKey = buildCacheKey(url, vary);
+  const cache = caches.default;
+  
+  // Check cache
+  let response = await cache.match(cacheKey);
+  
+  if (response) {
+    // Cache hit - add header for debugging
+    response = new Response(response.body, response);
+    response.headers.set('X-Cache', 'HIT');
+    response.headers.set('X-Cache-Key', cacheKey);
+    return response;
+  }
+  
+  // Cache miss - fetch from origin
+  response = await fetch(request);
+  
+  if (response.ok) {
+    // Clone response for caching
+    const responseToCache = new Response(response.body, response);
+    responseToCache.headers.set('Cache-Control', `public, max-age=${ttl}`);
+    responseToCache.headers.set('X-Cache', 'MISS');
+    
+    // Store in cache
+    event.waitUntil(cache.put(cacheKey, responseToCache.clone()));
+    
+    return responseToCache;
+  }
+  
+  return response;
+}
+
+function buildCacheKey(url, varyParams) {
+  const params = new URLSearchParams();
+  
+  for (const param of varyParams) {
+    const value = url.searchParams.get(param);
+    if (value) {
+      // Round coordinates for better cache hit ratio
+      if (param === 'lat' || param === 'lon') {
+        params.set(param, parseFloat(value).toFixed(2));
+      } else {
+        params.set(param, value);
+      }
+    }
+  }
+  
+  return `${url.origin}${url.pathname}?${params.toString()}`;
+}
+```
+
+### Deploying the Worker
+
+```bash
+# Install Wrangler CLI
+npm install -g wrangler
+
+# Login to Cloudflare
+wrangler login
+
+# Create wrangler.toml
+cat > wrangler.toml << EOF
+name = "weather-cache"
+main = "workers/weather-cache.js"
+compatibility_date = "2024-01-01"
+
+[env.production]
+route = "weather.example.com/*"
+EOF
+
+# Deploy
+wrangler deploy --env production
+```
+
+---
+
+## Fastly Setup
+
+### VCL Configuration
+
+```vcl
+// Fastly VCL for IntelliWeather
+
+sub vcl_recv {
+  // Normalize query parameters for better cache hit ratio
+  if (req.url ~ "^/weather" || req.url ~ "^/forecast") {
+    // Round coordinates to 2 decimal places
+    set req.url = querystring.filter_except(req.url, "lat" "lon" "units" "format");
+  }
+  
+  // Bypass cache for auth endpoints
+  if (req.url ~ "^/auth") {
+    return(pass);
+  }
+  
+  // Bypass cache for POST/PUT/DELETE
+  if (req.method != "GET" && req.method != "HEAD") {
+    return(pass);
+  }
+}
+
+sub vcl_backend_response {
+  // Set cache TTL based on path
+  if (req.url ~ "^/static") {
+    set beresp.ttl = 30d;
+    set beresp.http.Cache-Control = "public, max-age=2592000";
+  } else if (req.url ~ "^/weather") {
+    set beresp.ttl = 5m;
+    set beresp.http.Surrogate-Control = "max-age=300";
+  } else if (req.url ~ "^/forecast") {
+    set beresp.ttl = 30m;
+    set beresp.http.Surrogate-Control = "max-age=1800";
+  } else if (req.url ~ "^/geocode") {
+    set beresp.ttl = 24h;
+    set beresp.http.Surrogate-Control = "max-age=86400";
+  }
+  
+  // Add debug headers
+  set beresp.http.X-Cache-TTL = beresp.ttl;
+}
+
+sub vcl_deliver {
+  // Add cache status header
+  if (obj.hits > 0) {
+    set resp.http.X-Cache = "HIT";
+    set resp.http.X-Cache-Hits = obj.hits;
+  } else {
+    set resp.http.X-Cache = "MISS";
+  }
+}
+```
+
+### Fastly Compute@Edge (Rust)
+
+```rust
+// src/main.rs
+use fastly::http::{header, Method, StatusCode};
+use fastly::{mime, Error, Request, Response};
+use std::collections::HashMap;
+
+const BACKEND_NAME: &str = "origin";
+
+#[fastly::main]
+fn main(req: Request) -> Result<Response, Error> {
+    let path = req.get_path();
+    
+    // Route based on path
+    match path {
+        p if p.starts_with("/static") => handle_static(req),
+        p if p.starts_with("/weather") => handle_weather(req, 300),
+        p if p.starts_with("/forecast") => handle_weather(req, 1800),
+        p if p.starts_with("/geocode") => handle_weather(req, 86400),
+        p if p.starts_with("/auth") => handle_passthrough(req),
+        _ => handle_passthrough(req),
+    }
+}
+
+fn handle_static(req: Request) -> Result<Response, Error> {
+    let mut resp = req.send(BACKEND_NAME)?;
+    resp.set_header(header::CACHE_CONTROL, "public, max-age=2592000");
+    Ok(resp)
+}
+
+fn handle_weather(mut req: Request, ttl: u64) -> Result<Response, Error> {
+    // Normalize coordinates
+    let url = req.get_url_mut();
+    if let Some(lat) = url.query_pairs().find(|(k, _)| k == "lat") {
+        let rounded = (lat.1.parse::<f64>().unwrap_or(0.0) * 100.0).round() / 100.0;
+        // Update query parameter
+    }
+    
+    let mut resp = req.send(BACKEND_NAME)?;
+    resp.set_header(
+        header::CACHE_CONTROL, 
+        &format!("public, max-age={}", ttl)
+    );
+    Ok(resp)
+}
+
+fn handle_passthrough(req: Request) -> Result<Response, Error> {
+    let mut resp = req.send(BACKEND_NAME)?;
+    resp.set_header(header::CACHE_CONTROL, "no-store");
+    Ok(resp)
+}
+```
+
+---
+
+## Cache Headers
+
+### Origin Server Configuration
+
+Update `app.py` to include proper cache headers:
+
+```python
+from fastapi import Response
+from datetime import timedelta
+
+# Middleware to add cache headers
+@app.middleware("http")
+async def add_cache_headers(request, call_next):
+    response = await call_next(request)
+    path = request.url.path
+    
+    # Static assets
+    if path.startswith("/static"):
+        response.headers["Cache-Control"] = "public, max-age=2592000"
+        response.headers["Surrogate-Control"] = "max-age=2592000"
+    
+    # Weather endpoints
+    elif path.startswith("/weather"):
+        response.headers["Cache-Control"] = "public, max-age=300"
+        response.headers["Surrogate-Control"] = "max-age=300"
+        response.headers["Vary"] = "Accept-Encoding"
+    
+    # Forecast endpoints
+    elif path.startswith("/forecast"):
+        response.headers["Cache-Control"] = "public, max-age=1800"
+        response.headers["Surrogate-Control"] = "max-age=1800"
+    
+    # Geocoding
+    elif path.startswith("/geocode"):
+        response.headers["Cache-Control"] = "public, max-age=86400"
+        response.headers["Surrogate-Control"] = "max-age=86400"
+    
+    # Auth - no cache
+    elif path.startswith("/auth"):
+        response.headers["Cache-Control"] = "no-store, no-cache, must-revalidate"
+    
+    return response
+```
+
+### Cache-Control Headers
+
+| Header | Description |
+|--------|-------------|
+| `Cache-Control: public, max-age=300` | Cache for 5 minutes |
+| `Surrogate-Control: max-age=300` | CDN-specific TTL |
+| `Vary: Accept-Encoding` | Cache separately for gzip/brotli |
+| `ETag: "abc123"` | Content-based validation |
+| `Last-Modified: <date>` | Time-based validation |
+
+---
+
+## Best Practices
+
+### 1. Normalize Cache Keys
+
+```javascript
+// Round coordinates to reduce cache variants
+const lat = Math.round(lat * 100) / 100;  // 40.7128 -> 40.71
+const lon = Math.round(lon * 100) / 100;
+```
+
+### 2. Cache Warming
+
+```bash
+# Pre-warm cache for popular locations
+LOCATIONS=(
+  "40.71,-74.01"    # New York
+  "51.51,-0.13"     # London
+  "35.68,139.65"    # Tokyo
+)
+
+for loc in "${LOCATIONS[@]}"; do
+  IFS=',' read -r lat lon <<< "$loc"
+  curl -s "https://weather.example.com/weather?lat=$lat&lon=$lon" > /dev/null
+  curl -s "https://weather.example.com/forecast?lat=$lat&lon=$lon" > /dev/null
+done
+```
+
+### 3. Cache Purging
+
+```bash
+# Cloudflare - purge specific URLs
+curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  --data '{"files":["https://weather.example.com/weather?lat=40.71&lon=-74.01"]}'
+
+# Cloudflare - purge everything
+curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  --data '{"purge_everything":true}'
+
+# Fastly
+curl -X POST "https://api.fastly.com/service/{service_id}/purge_all" \
+  -H "Fastly-Key: {api_key}"
+```
+
+### 4. Monitor Cache Performance
+
+```bash
+# Check cache hit ratio (Cloudflare)
+curl -s "https://api.cloudflare.com/client/v4/zones/{zone_id}/analytics/dashboard" \
+  -H "Authorization: Bearer {api_token}" | jq '.result.totals.requests.cached'
+
+# Check headers
+curl -I "https://weather.example.com/weather?lat=40.71&lon=-74.01"
+# Look for: X-Cache: HIT, CF-Cache-Status: HIT
+```
+
+---
+
+## Summary
+
+1. **Use CDN for all traffic** - Better performance and security
+2. **Set appropriate TTLs** - Balance freshness vs. efficiency
+3. **Normalize cache keys** - Reduce variants for better hit ratio
+4. **Bypass cache for auth** - Never cache authenticated requests
+5. **Monitor cache performance** - Track hit ratios and optimize
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
new file mode 100644
index 0000000..e7e3702
--- /dev/null
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,423 @@
+# IntelliWeather Deployment Guide
+
+This guide covers deploying IntelliWeather to various environments.
+
+## Table of Contents
+
+- [Quick Start (Docker)](#quick-start-docker)
+- [Production Deployment (Kubernetes)](#production-deployment-kubernetes)
+- [Cloud Providers](#cloud-providers)
+- [Environment Configuration](#environment-configuration)
+- [Health Checks & Monitoring](#health-checks--monitoring)
+- [Scaling](#scaling)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Start (Docker)
+
+### Prerequisites
+
+- Docker 20.10+
+- Docker Compose 2.0+
+
+### Development
+
+```bash
+# Clone the repository
+git clone https://github.com/CodersAcademy006/Weather-API.git
+cd Weather-API
+
+# Start with Docker Compose
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Access the application
+open http://localhost:8000
+```
+
+### Production (Single Node)
+
+```bash
+# Build production image
+docker build -t intelliweather:latest .
+
+# Run with production settings
+docker run -d \
+  --name intelliweather \
+  -p 8000:8000 \
+  -e DEBUG=false \
+  -e SECRET_KEY=$(openssl rand -hex 32) \
+  -e LOG_LEVEL=INFO \
+  -v intelliweather-data:/app/data \
+  intelliweather:latest
+```
+
+### With NGINX Load Balancer
+
+```bash
+# Scale to 3 instances with NGINX
+docker-compose -f docker-compose.yml up -d --scale app=3
+```
+
+---
+
+## Production Deployment (Kubernetes)
+
+### Prerequisites
+
+- Kubernetes 1.25+
+- kubectl configured
+- Helm 3.x (optional)
+
+### Using kubectl
+
+```bash
+# Create namespace
+kubectl create namespace intelliweather
+
+# Create secrets (IMPORTANT: use your own values!)
+kubectl create secret generic intelliweather-secrets \
+  --namespace intelliweather \
+  --from-literal=secret-key=$(openssl rand -hex 32) \
+  --from-literal=redis-url="" \
+  --from-literal=sentry-dsn=""
+
+# Apply manifests
+kubectl apply -f k8s/deployment.yaml --namespace intelliweather
+
+# Check status
+kubectl get pods -n intelliweather
+kubectl get svc -n intelliweather
+```
+
+### Using Helm
+
+```bash
+# Add/update dependencies
+cd helm/intelliweather
+helm dependency update
+
+# Install
+helm install intelliweather . \
+  --namespace intelliweather \
+  --create-namespace \
+  --values values.yaml \
+  --set image.tag=v3.0.0
+
+# Upgrade
+helm upgrade intelliweather . \
+  --namespace intelliweather \
+  --set image.tag=v3.1.0
+
+# Uninstall
+helm uninstall intelliweather --namespace intelliweather
+```
+
+### Local Development (kind/minikube)
+
+```bash
+# Using the provided script
+cd k8s/local
+chmod +x local-setup.sh
+
+# Full setup
+./local-setup.sh setup
+
+# Port forward to access
+./local-setup.sh forward
+
+# Cleanup
+./local-setup.sh cleanup
+```
+
+---
+
+## Cloud Providers
+
+### AWS (EKS)
+
+```bash
+# Create EKS cluster
+eksctl create cluster \
+  --name intelliweather \
+  --region us-east-1 \
+  --nodes 3
+
+# Configure kubectl
+aws eks update-kubeconfig --name intelliweather --region us-east-1
+
+# Deploy
+kubectl apply -f k8s/deployment.yaml
+```
+
+### Google Cloud (GKE)
+
+```bash
+# Create GKE cluster
+gcloud container clusters create intelliweather \
+  --zone us-central1-a \
+  --num-nodes 3
+
+# Get credentials
+gcloud container clusters get-credentials intelliweather --zone us-central1-a
+
+# Deploy
+kubectl apply -f k8s/deployment.yaml
+```
+
+### Azure (AKS)
+
+```bash
+# Create AKS cluster
+az aks create \
+  --resource-group intelliweather-rg \
+  --name intelliweather \
+  --node-count 3
+
+# Get credentials
+az aks get-credentials --resource-group intelliweather-rg --name intelliweather
+
+# Deploy
+kubectl apply -f k8s/deployment.yaml
+```
+
+### DigitalOcean (DOKS)
+
+```bash
+# Create cluster via doctl
+doctl kubernetes cluster create intelliweather \
+  --region nyc1 \
+  --node-pool "name=pool;size=s-2vcpu-4gb;count=3"
+
+# Deploy
+kubectl apply -f k8s/deployment.yaml
+```
+
+---
+
+## Environment Configuration
+
+### Required Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECRET_KEY` | Secure random key for sessions | (required) |
+| `APP_HOST` | Bind address | `0.0.0.0` |
+| `APP_PORT` | Port number | `8000` |
+
+### Optional Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DEBUG` | Enable debug mode | `false` |
+| `LOG_LEVEL` | Logging level | `INFO` |
+| `LOG_FORMAT` | Log format (json/text) | `json` |
+| `DATA_DIR` | Data directory path | `/app/data` |
+| `REDIS_URL` | Redis connection URL | (none) |
+| `SENTRY_DSN` | Sentry error tracking | (none) |
+| `CACHE_TTL_SECONDS` | Cache TTL | `3600` |
+| `SESSION_TIMEOUT_SECONDS` | Session timeout | `86400` |
+| `RATE_LIMIT_PER_MIN` | Rate limit per IP | `60` |
+
+### Production Configuration
+
+```yaml
+# k8s/configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: intelliweather-config
+data:
+  DEBUG: "false"
+  LOG_LEVEL: "INFO"
+  LOG_FORMAT: "json"
+  CACHE_TTL_SECONDS: "3600"
+  SESSION_TIMEOUT_SECONDS: "86400"
+  RATE_LIMIT_PER_MIN: "100"
+```
+
+---
+
+## Health Checks & Monitoring
+
+### Health Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/healthz` | Liveness check |
+| `/metrics` | Application metrics |
+| `/metrics/prometheus` | Prometheus format |
+
+### Kubernetes Probes
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: 8000
+  initialDelaySeconds: 10
+  periodSeconds: 30
+
+readinessProbe:
+  httpGet:
+    path: /healthz
+    port: 8000
+  initialDelaySeconds: 5
+  periodSeconds: 10
+```
+
+### Prometheus Scrape Config
+
+```yaml
+scrape_configs:
+  - job_name: 'intelliweather'
+    kubernetes_sd_configs:
+      - role: pod
+    relabel_configs:
+      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
+        action: keep
+        regex: true
+```
+
+---
+
+## Scaling
+
+### Horizontal Pod Autoscaler
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: intelliweather
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: intelliweather
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+```
+
+### Manual Scaling
+
+```bash
+# Scale to 5 replicas
+kubectl scale deployment intelliweather --replicas=5
+
+# With Docker Compose
+docker-compose up -d --scale app=5
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### Pod CrashLoopBackOff
+
+```bash
+# Check logs
+kubectl logs -f deployment/intelliweather
+
+# Check events
+kubectl describe pod <pod-name>
+
+# Common causes:
+# - Missing SECRET_KEY
+# - Invalid configuration
+# - Resource limits too low
+```
+
+#### Connection Refused
+
+```bash
+# Check service
+kubectl get svc intelliweather
+
+# Check endpoints
+kubectl get endpoints intelliweather
+
+# Port forward for testing
+kubectl port-forward svc/intelliweather 8080:80
+```
+
+#### High Latency
+
+```bash
+# Check resource usage
+kubectl top pods
+
+# Check cache hit ratio
+curl http://localhost:8000/metrics | grep cache_
+
+# Consider:
+# - Increasing replicas
+# - Enabling Redis cache
+# - Increasing resource limits
+```
+
+### Useful Commands
+
+```bash
+# Get all resources
+kubectl get all -n intelliweather
+
+# Describe deployment
+kubectl describe deployment intelliweather
+
+# View logs
+kubectl logs -f -l app=intelliweather
+
+# Execute into pod
+kubectl exec -it deployment/intelliweather -- /bin/bash
+
+# Restart deployment
+kubectl rollout restart deployment/intelliweather
+
+# Check rollout status
+kubectl rollout status deployment/intelliweather
+```
+
+---
+
+## Security Recommendations
+
+1. **TLS/SSL**: Always use HTTPS in production
+2. **Secrets Management**: Use Kubernetes Secrets or external secret managers
+3. **Network Policies**: Restrict pod-to-pod communication
+4. **Pod Security**: Run as non-root, read-only filesystem
+5. **Image Scanning**: Scan images for vulnerabilities
+
+```yaml
+# Example: Enable TLS with cert-manager
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+spec:
+  tls:
+    - hosts:
+        - weather.example.com
+      secretName: intelliweather-tls
+```
+
+---
+
+## Support
+
+- **Documentation**: [README.md](../README.md)
+- **Issues**: [GitHub Issues](https://github.com/CodersAcademy006/Weather-API/issues)
+- **API Docs**: `/docs` endpoint
diff --git a/helm/intelliweather/Chart.yaml b/helm/intelliweather/Chart.yaml
new file mode 100644
index 0000000..05d5970
--- /dev/null
+++ b/helm/intelliweather/Chart.yaml
@@ -0,0 +1,26 @@
+apiVersion: v2
+name: intelliweather
+description: Production-grade Weather API with caching, auth, and observability
+type: application
+version: 3.0.0
+appVersion: "3.0.0"
+keywords:
+  - weather
+  - api
+  - fastapi
+  - python
+maintainers:
+  - name: IntelliWeather Team
+    email: team@intelliweather.io
+home: https://github.com/CodersAcademy006/Weather-API
+sources:
+  - https://github.com/CodersAcademy006/Weather-API
+dependencies:
+  - name: redis
+    version: "17.x.x"
+    repository: https://charts.bitnami.com/bitnami
+    condition: redis.enabled
+  - name: postgresql
+    version: "12.x.x"
+    repository: https://charts.bitnami.com/bitnami
+    condition: postgresql.enabled
diff --git a/helm/intelliweather/templates/_helpers.tpl b/helm/intelliweather/templates/_helpers.tpl
new file mode 100644
index 0000000..99558b0
--- /dev/null
+++ b/helm/intelliweather/templates/_helpers.tpl
@@ -0,0 +1,64 @@
+{{- /*
+IntelliWeather Helm Chart - Helper Templates
+*/}}
+
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "intelliweather.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "intelliweather.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "intelliweather.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "intelliweather.labels" -}}
+helm.sh/chart: {{ include "intelliweather.chart" . }}
+{{ include "intelliweather.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "intelliweather.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "intelliweather.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "intelliweather.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "intelliweather.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}
diff --git a/helm/intelliweather/templates/deployment.yaml b/helm/intelliweather/templates/deployment.yaml
new file mode 100644
index 0000000..debb176
--- /dev/null
+++ b/helm/intelliweather/templates/deployment.yaml
@@ -0,0 +1,84 @@
+{{- /*
+IntelliWeather Helm Chart - Deployment Template
+*/}}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "intelliweather.fullname" . }}
+  labels:
+    {{- include "intelliweather.labels" . | nindent 4 }}
+spec:
+  {{- if not .Values.autoscaling.enabled }}
+  replicas: {{ .Values.replicaCount }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "intelliweather.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      annotations:
+        {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      labels:
+        {{- include "intelliweather.selectorLabels" . | nindent 8 }}
+    spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      serviceAccountName: {{ include "intelliweather.serviceAccountName" . }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+        - name: {{ .Chart.Name }}
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: {{ .Values.service.targetPort }}
+              protocol: TCP
+          env:
+            {{- range $key, $value := .Values.env }}
+            - name: {{ $key }}
+              value: {{ $value | quote }}
+            {{- end }}
+            {{- range .Values.secretEnv }}
+            - name: {{ .name }}
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .secretName }}
+                  key: {{ .secretKey }}
+                  optional: {{ .optional | default false }}
+            {{- end }}
+          livenessProbe:
+            {{- toYaml .Values.livenessProbe | nindent 12 }}
+          readinessProbe:
+            {{- toYaml .Values.readinessProbe | nindent 12 }}
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          {{- if .Values.persistence.enabled }}
+          volumeMounts:
+            - name: data
+              mountPath: /app/data
+          {{- end }}
+      {{- if .Values.persistence.enabled }}
+      volumes:
+        - name: data
+          persistentVolumeClaim:
+            claimName: {{ include "intelliweather.fullname" . }}-data
+      {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
diff --git a/helm/intelliweather/templates/service.yaml b/helm/intelliweather/templates/service.yaml
new file mode 100644
index 0000000..0fd6979
--- /dev/null
+++ b/helm/intelliweather/templates/service.yaml
@@ -0,0 +1,18 @@
+{{- /*
+IntelliWeather Helm Chart - Service Template
+*/}}
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "intelliweather.fullname" . }}
+  labels:
+    {{- include "intelliweather.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    {{- include "intelliweather.selectorLabels" . | nindent 4 }}
diff --git a/helm/intelliweather/values.yaml b/helm/intelliweather/values.yaml
new file mode 100644
index 0000000..e5a63d7
--- /dev/null
+++ b/helm/intelliweather/values.yaml
@@ -0,0 +1,180 @@
+# IntelliWeather Helm Chart Values
+# Override these values for your environment
+
+# Replica count
+replicaCount: 3
+
+image:
+  repository: intelliweather
+  tag: latest
+  pullPolicy: IfNotPresent
+
+# Image pull secrets (for private registries)
+imagePullSecrets: []
+
+# Service account
+serviceAccount:
+  create: true
+  annotations: {}
+  name: ""
+
+# Pod annotations
+podAnnotations:
+  prometheus.io/scrape: "true"
+  prometheus.io/port: "8000"
+  prometheus.io/path: "/metrics/prometheus"
+
+# Pod security context
+podSecurityContext:
+  runAsNonRoot: true
+  runAsUser: 1000
+  fsGroup: 1000
+
+# Container security context
+securityContext:
+  readOnlyRootFilesystem: false
+  runAsNonRoot: true
+  runAsUser: 1000
+
+# Service configuration
+service:
+  type: ClusterIP
+  port: 80
+  targetPort: 8000
+
+# Ingress configuration
+ingress:
+  enabled: true
+  className: nginx
+  annotations:
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+  hosts:
+    - host: weather.example.com
+      paths:
+        - path: /
+          pathType: Prefix
+  tls:
+    - secretName: intelliweather-tls
+      hosts:
+        - weather.example.com
+
+# Resource limits
+resources:
+  limits:
+    cpu: 500m
+    memory: 512Mi
+  requests:
+    cpu: 100m
+    memory: 256Mi
+
+# Autoscaling
+autoscaling:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 70
+  targetMemoryUtilizationPercentage: 80
+
+# Node selector
+nodeSelector: {}
+
+# Tolerations
+tolerations: []
+
+# Affinity
+affinity: {}
+
+# Environment variables
+env:
+  APP_HOST: "0.0.0.0"
+  APP_PORT: "8000"
+  DEBUG: "false"
+  LOG_LEVEL: "INFO"
+  LOG_FORMAT: "json"
+  DATA_DIR: "/app/data"
+  CACHE_TTL_SECONDS: "3600"
+  SESSION_TIMEOUT_SECONDS: "86400"
+  RATE_LIMIT_PER_MIN: "60"
+  DEFAULT_LANGUAGE: "en"
+
+# Secret environment variables (reference existing secrets)
+secretEnv:
+  - name: SECRET_KEY
+    secretName: intelliweather-secrets
+    secretKey: secret-key
+  - name: REDIS_URL
+    secretName: intelliweather-secrets
+    secretKey: redis-url
+    optional: true
+  - name: SENTRY_DSN
+    secretName: intelliweather-secrets
+    secretKey: sentry-dsn
+    optional: true
+
+# Persistent storage
+persistence:
+  enabled: true
+  storageClass: ""
+  accessMode: ReadWriteOnce
+  size: 1Gi
+
+# Health probes
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: http
+  initialDelaySeconds: 10
+  periodSeconds: 30
+  timeoutSeconds: 5
+  failureThreshold: 3
+
+readinessProbe:
+  httpGet:
+    path: /healthz
+    port: http
+  initialDelaySeconds: 5
+  periodSeconds: 10
+  timeoutSeconds: 3
+  failureThreshold: 3
+
+# Pod disruption budget
+podDisruptionBudget:
+  enabled: true
+  minAvailable: 1
+
+# Redis subchart configuration
+redis:
+  enabled: false
+  architecture: standalone
+  auth:
+    enabled: true
+    password: ""
+  master:
+    persistence:
+      enabled: true
+      size: 1Gi
+
+# PostgreSQL subchart configuration
+postgresql:
+  enabled: false
+  auth:
+    username: intelliweather
+    password: ""
+    database: intelliweather
+  primary:
+    persistence:
+      enabled: true
+      size: 5Gi
+
+# Prometheus ServiceMonitor
+serviceMonitor:
+  enabled: false
+  interval: 30s
+  labels: {}
+
+# Grafana dashboard ConfigMap
+grafanaDashboard:
+  enabled: false
+  labels:
+    grafana_dashboard: "1"
diff --git a/k8s/deployment.yaml b/k8s/deployment.yaml
new file mode 100644
index 0000000..a6a0c38
--- /dev/null
+++ b/k8s/deployment.yaml
@@ -0,0 +1,194 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: intelliweather
+  labels:
+    app: intelliweather
+    version: v3.0.0
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: intelliweather
+  template:
+    metadata:
+      labels:
+        app: intelliweather
+        version: v3.0.0
+      annotations:
+        prometheus.io/scrape: "true"
+        prometheus.io/port: "8000"
+        prometheus.io/path: "/metrics/prometheus"
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+        fsGroup: 1000
+      containers:
+        - name: intelliweather
+          image: intelliweather:latest
+          imagePullPolicy: IfNotPresent
+          ports:
+            - containerPort: 8000
+              name: http
+          env:
+            - name: APP_HOST
+              value: "0.0.0.0"
+            - name: APP_PORT
+              value: "8000"
+            - name: DEBUG
+              value: "false"
+            - name: LOG_LEVEL
+              value: "INFO"
+            - name: LOG_FORMAT
+              value: "json"
+            - name: DATA_DIR
+              value: "/app/data"
+            - name: REDIS_URL
+              valueFrom:
+                secretKeyRef:
+                  name: intelliweather-secrets
+                  key: redis-url
+                  optional: true
+            - name: SECRET_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: intelliweather-secrets
+                  key: secret-key
+            - name: SENTRY_DSN
+              valueFrom:
+                secretKeyRef:
+                  name: intelliweather-secrets
+                  key: sentry-dsn
+                  optional: true
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              cpu: 500m
+              memory: 512Mi
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 30
+            timeoutSeconds: 5
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /healthz
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 3
+            failureThreshold: 3
+          volumeMounts:
+            - name: data
+              mountPath: /app/data
+      volumes:
+        - name: data
+          persistentVolumeClaim:
+            claimName: intelliweather-data
+      terminationGracePeriodSeconds: 30
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: intelliweather
+  labels:
+    app: intelliweather
+spec:
+  type: ClusterIP
+  ports:
+    - port: 80
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    app: intelliweather
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: intelliweather
+  annotations:
+    kubernetes.io/ingress.class: nginx
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
+    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
+    cert-manager.io/cluster-issuer: "letsencrypt-prod"
+spec:
+  tls:
+    - hosts:
+        - weather.example.com
+      secretName: intelliweather-tls
+  rules:
+    - host: weather.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: intelliweather
+                port:
+                  number: 80
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: intelliweather-data
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 1Gi
+---
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: intelliweather
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: intelliweather
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: 80
+---
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: intelliweather
+spec:
+  minAvailable: 1
+  selector:
+    matchLabels:
+      app: intelliweather
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: intelliweather-config
+data:
+  CACHE_TTL_SECONDS: "3600"
+  SESSION_TIMEOUT_SECONDS: "86400"
+  RATE_LIMIT_PER_MIN: "60"
+  POPULAR_LOCATIONS: "40.7128,-74.0060,New York;51.5074,-0.1278,London;35.6762,139.6503,Tokyo"
+  DEFAULT_LANGUAGE: "en"
+  SUPPORTED_LANGUAGES: "en,hi,ur,ar,es"
diff --git a/k8s/local/local-setup.sh b/k8s/local/local-setup.sh
new file mode 100644
index 0000000..2243ee4
--- /dev/null
+++ b/k8s/local/local-setup.sh
@@ -0,0 +1,214 @@
+#!/bin/bash
+# IntelliWeather - Local Kubernetes Setup Script
+# Uses kind (Kubernetes in Docker) for local development
+
+set -e
+
+CLUSTER_NAME="intelliweather"
+NAMESPACE="intelliweather"
+
+echo "🌤️  IntelliWeather Local Kubernetes Setup"
+echo "==========================================="
+
+# Check dependencies
+check_deps() {
+    echo "Checking dependencies..."
+    
+    if ! command -v docker &> /dev/null; then
+        echo "❌ Docker is not installed. Please install Docker first."
+        exit 1
+    fi
+    
+    if ! command -v kind &> /dev/null; then
+        echo "❌ kind is not installed. Installing..."
+        if [[ "$OSTYPE" == "darwin"* ]]; then
+            brew install kind
+        else
+            curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64
+            chmod +x ./kind
+            sudo mv ./kind /usr/local/bin/kind
+        fi
+    fi
+    
+    if ! command -v kubectl &> /dev/null; then
+        echo "❌ kubectl is not installed. Please install kubectl first."
+        exit 1
+    fi
+    
+    echo "✅ All dependencies are installed"
+}
+
+# Create kind cluster
+create_cluster() {
+    echo ""
+    echo "Creating kind cluster..."
+    
+    if kind get clusters | grep -q "^${CLUSTER_NAME}$"; then
+        echo "Cluster '${CLUSTER_NAME}' already exists"
+    else
+        kind create cluster --name ${CLUSTER_NAME} --config - <<EOF
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+  - role: control-plane
+    kubeadmConfigPatches:
+      - |
+        kind: InitConfiguration
+        nodeRegistration:
+          kubeletExtraArgs:
+            node-labels: "ingress-ready=true"
+    extraPortMappings:
+      - containerPort: 80
+        hostPort: 80
+        protocol: TCP
+      - containerPort: 443
+        hostPort: 443
+        protocol: TCP
+      - containerPort: 30000
+        hostPort: 30000
+        protocol: TCP
+EOF
+        echo "✅ Cluster created"
+    fi
+}
+
+# Build and load Docker image
+build_image() {
+    echo ""
+    echo "Building Docker image..."
+    
+    cd "$(dirname "$0")/.."
+    docker build -t intelliweather:latest .
+    
+    echo "Loading image into kind cluster..."
+    kind load docker-image intelliweather:latest --name ${CLUSTER_NAME}
+    
+    echo "✅ Image built and loaded"
+}
+
+# Install NGINX Ingress Controller
+install_ingress() {
+    echo ""
+    echo "Installing NGINX Ingress Controller..."
+    
+    kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
+    
+    echo "Waiting for ingress controller to be ready..."
+    kubectl wait --namespace ingress-nginx \
+        --for=condition=ready pod \
+        --selector=app.kubernetes.io/component=controller \
+        --timeout=90s || true
+    
+    echo "✅ Ingress controller installed"
+}
+
+# Create namespace and deploy
+deploy() {
+    echo ""
+    echo "Deploying IntelliWeather..."
+    
+    # Create namespace
+    kubectl create namespace ${NAMESPACE} --dry-run=client -o yaml | kubectl apply -f -
+    
+    # Create secrets (using defaults for local dev)
+    kubectl create secret generic intelliweather-secrets \
+        --namespace ${NAMESPACE} \
+        --from-literal=secret-key="local-dev-secret-key-change-in-prod" \
+        --dry-run=client -o yaml | kubectl apply -f -
+    
+    # Apply manifests
+    kubectl apply -f "$(dirname "$0")/deployment.yaml" --namespace ${NAMESPACE}
+    
+    echo "Waiting for pods to be ready..."
+    kubectl wait --namespace ${NAMESPACE} \
+        --for=condition=ready pod \
+        --selector=app=intelliweather \
+        --timeout=120s || true
+    
+    echo "✅ Deployment complete"
+}
+
+# Port forward
+port_forward() {
+    echo ""
+    echo "Setting up port forwarding..."
+    echo "Access the application at: http://localhost:8080"
+    echo "Press Ctrl+C to stop"
+    echo ""
+    
+    kubectl port-forward --namespace ${NAMESPACE} svc/intelliweather 8080:80
+}
+
+# Show status
+status() {
+    echo ""
+    echo "📊 Cluster Status"
+    echo "=================="
+    
+    echo ""
+    echo "Pods:"
+    kubectl get pods --namespace ${NAMESPACE} -o wide
+    
+    echo ""
+    echo "Services:"
+    kubectl get svc --namespace ${NAMESPACE}
+    
+    echo ""
+    echo "Ingress:"
+    kubectl get ingress --namespace ${NAMESPACE}
+    
+    echo ""
+    echo "HPA:"
+    kubectl get hpa --namespace ${NAMESPACE}
+}
+
+# Cleanup
+cleanup() {
+    echo ""
+    echo "Cleaning up..."
+    
+    kind delete cluster --name ${CLUSTER_NAME}
+    
+    echo "✅ Cluster deleted"
+}
+
+# Main
+case "${1:-}" in
+    setup)
+        check_deps
+        create_cluster
+        build_image
+        install_ingress
+        deploy
+        status
+        echo ""
+        echo "🎉 Setup complete! Run './local-setup.sh forward' to access the app"
+        ;;
+    forward)
+        port_forward
+        ;;
+    status)
+        status
+        ;;
+    cleanup)
+        cleanup
+        ;;
+    build)
+        build_image
+        ;;
+    deploy)
+        deploy
+        ;;
+    *)
+        echo "Usage: $0 {setup|forward|status|cleanup|build|deploy}"
+        echo ""
+        echo "Commands:"
+        echo "  setup   - Full setup: create cluster, build image, deploy"
+        echo "  forward - Port forward to access the application"
+        echo "  status  - Show cluster status"
+        echo "  cleanup - Delete the cluster"
+        echo "  build   - Build and load Docker image"
+        echo "  deploy  - Deploy to existing cluster"
+        exit 1
+        ;;
+esac
diff --git a/k8s/secrets-template.yaml b/k8s/secrets-template.yaml
new file mode 100644
index 0000000..1742f67
--- /dev/null
+++ b/k8s/secrets-template.yaml
@@ -0,0 +1,37 @@
+# IntelliWeather Secrets Template
+# IMPORTANT: Never commit actual secrets to version control!
+# Copy this file and fill in your values, or use Kubernetes secret management
+
+apiVersion: v1
+kind: Secret
+metadata:
+  name: intelliweather-secrets
+type: Opaque
+stringData:
+  # Generate a secure random key: python -c "import secrets; print(secrets.token_hex(32))"
+  secret-key: "REPLACE_WITH_SECURE_SECRET_KEY"
+  
+  # Redis connection URL (optional, for production session/cache backend)
+  # Format: redis://[:password@]host[:port][/database]
+  redis-url: ""
+  
+  # Sentry DSN for error tracking (optional)
+  sentry-dsn: ""
+  
+  # Database connection string (optional, for PostgreSQL backend)
+  # Format: postgresql://user:password@host:port/database
+  db-connection-string: ""
+  
+  # SMTP credentials for email notifications (optional)
+  smtp-host: ""
+  smtp-port: "587"
+  smtp-username: ""
+  smtp-password: ""
+  
+  # SendGrid API key (optional, alternative to SMTP)
+  sendgrid-api-key: ""
+  
+  # Twilio credentials for SMS notifications (optional)
+  twilio-account-sid: ""
+  twilio-auth-token: ""
+  twilio-phone-number: ""
diff --git a/logging_config.py b/logging_config.py
new file mode 100644
index 0000000..3326053
--- /dev/null
+++ b/logging_config.py
@@ -0,0 +1,159 @@
+"""
+Structured Logging Configuration
+
+This module provides JSON-style structured logging for the application.
+Includes timestamps, level, route information, and other contextual data.
+"""
+
+import logging
+import sys
+import json
+from datetime import datetime
+from typing import Optional, Dict, Any
+from config import settings
+
+
+class JSONFormatter(logging.Formatter):
+    """
+    Custom formatter that outputs logs as JSON objects.
+    """
+    
+    def format(self, record: logging.LogRecord) -> str:
+        """Format the log record as a JSON string."""
+        log_data: Dict[str, Any] = {
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+        }
+        
+        # Add extra fields if present
+        if hasattr(record, "request_id"):
+            log_data["request_id"] = record.request_id
+        if hasattr(record, "route"):
+            log_data["route"] = record.route
+        if hasattr(record, "method"):
+            log_data["method"] = record.method
+        if hasattr(record, "status_code"):
+            log_data["status_code"] = record.status_code
+        if hasattr(record, "duration_ms"):
+            log_data["duration_ms"] = record.duration_ms
+        if hasattr(record, "ip_address"):
+            log_data["ip_address"] = record.ip_address
+        if hasattr(record, "user_id"):
+            log_data["user_id"] = record.user_id
+        if hasattr(record, "extra_data"):
+            log_data["extra"] = record.extra_data
+            
+        # Add exception info if present
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+            
+        return json.dumps(log_data)
+
+
+class TextFormatter(logging.Formatter):
+    """
+    Standard text formatter with structured output.
+    """
+    
+    def __init__(self):
+        super().__init__(
+            fmt="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S"
+        )
+
+
+def setup_logging(
+    level: Optional[str] = None,
+    format_type: Optional[str] = None
+) -> logging.Logger:
+    """
+    Configure and return the root logger for the application.
+    
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        format_type: Format type ("json" or "text")
+        
+    Returns:
+        Configured logger instance
+    """
+    log_level = level or settings.LOG_LEVEL
+    log_format = format_type or settings.LOG_FORMAT
+    
+    # Get the root logger
+    logger = logging.getLogger("intelliweather")
+    logger.setLevel(getattr(logging, log_level.upper()))
+    
+    # Remove existing handlers
+    logger.handlers.clear()
+    
+    # Create console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(getattr(logging, log_level.upper()))
+    
+    # Set formatter based on format type
+    if log_format.lower() == "json":
+        console_handler.setFormatter(JSONFormatter())
+    else:
+        console_handler.setFormatter(TextFormatter())
+    
+    logger.addHandler(console_handler)
+    
+    return logger
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger with the specified name.
+    
+    Args:
+        name: Name for the logger (usually __name__)
+        
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(f"intelliweather.{name}")
+
+
+class LogContext:
+    """
+    Context manager for adding extra context to log records.
+    """
+    
+    def __init__(self, logger: logging.Logger, **kwargs):
+        self.logger = logger
+        self.extra = kwargs
+        
+    def __enter__(self):
+        return self
+        
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass
+        
+    def info(self, message: str, **kwargs):
+        """Log an info message with context."""
+        extra = {**self.extra, **kwargs}
+        self.logger.info(message, extra={"extra_data": extra})
+        
+    def error(self, message: str, **kwargs):
+        """Log an error message with context."""
+        extra = {**self.extra, **kwargs}
+        self.logger.error(message, extra={"extra_data": extra})
+        
+    def warning(self, message: str, **kwargs):
+        """Log a warning message with context."""
+        extra = {**self.extra, **kwargs}
+        self.logger.warning(message, extra={"extra_data": extra})
+        
+    def debug(self, message: str, **kwargs):
+        """Log a debug message with context."""
+        extra = {**self.extra, **kwargs}
+        self.logger.debug(message, extra={"extra_data": extra})
+
+
+# Initialize the logger on module import
+logger = setup_logging()
diff --git a/metrics.py b/metrics.py
new file mode 100644
index 0000000..89f460a
--- /dev/null
+++ b/metrics.py
@@ -0,0 +1,290 @@
+"""
+Metrics and Health Check Module
+
+This module provides:
+- /healthz endpoint for health checks
+- /metrics endpoint for observability
+- In-memory counters for request tracking
+"""
+
+import threading
+from typing import Dict, Any
+from datetime import datetime, timezone
+from fastapi import APIRouter, HTTPException, status
+from storage import get_storage
+from cache import get_cache
+from session_middleware import get_session_middleware
+from middleware.rate_limiter import get_rate_limiter
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+router = APIRouter(tags=["Health & Metrics"])
+
+
+class Metrics:
+    """
+    Thread-safe metrics collector.
+    
+    Tracks various application metrics including request counts,
+    cache performance, and error rates.
+    """
+    
+    def __init__(self):
+        self._lock = threading.RLock()
+        self._counters: Dict[str, int] = {
+            "total_requests": 0,
+            "successful_requests": 0,
+            "failed_requests": 0,
+            "weather_requests": 0,
+            "hourly_requests": 0,
+            "forecast_requests": 0,
+            "aqi_requests": 0,
+            "auth_requests": 0,
+            "cache_hits": 0,
+            "cache_misses": 0,
+            "rate_limit_exceeded": 0,
+        }
+        self._start_time = datetime.now(timezone.utc)
+    
+    def increment(self, counter: str, value: int = 1) -> None:
+        """Increment a counter."""
+        with self._lock:
+            if counter in self._counters:
+                self._counters[counter] += value
+            else:
+                self._counters[counter] = value
+    
+    def get(self, counter: str) -> int:
+        """Get a counter value."""
+        with self._lock:
+            return self._counters.get(counter, 0)
+    
+    def get_all(self) -> Dict[str, int]:
+        """Get all counters."""
+        with self._lock:
+            return self._counters.copy()
+    
+    def reset(self) -> None:
+        """Reset all counters."""
+        with self._lock:
+            for key in self._counters:
+                self._counters[key] = 0
+    
+    def uptime_seconds(self) -> float:
+        """Get application uptime in seconds."""
+        return (datetime.now(timezone.utc) - self._start_time).total_seconds()
+
+
+# Global metrics instance
+_metrics: Metrics = None
+
+
+def get_metrics() -> Metrics:
+    """Get the global metrics instance."""
+    global _metrics
+    if _metrics is None:
+        _metrics = Metrics()
+    return _metrics
+
+
+def init_metrics() -> Metrics:
+    """Initialize the global metrics instance."""
+    global _metrics
+    _metrics = Metrics()
+    return _metrics
+
+
+# ==================== HEALTH CHECK ====================
+
+@router.get("/healthz")
+async def health_check():
+    """
+    Health check endpoint.
+    
+    Checks:
+    - Storage is writable
+    - Cache is working
+    - Session middleware is loaded
+    
+    Returns:
+        Health status with component checks
+    """
+    checks = {
+        "status": "healthy",
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "checks": {}
+    }
+    
+    all_healthy = True
+    
+    # Check storage
+    try:
+        storage = get_storage()
+        storage_healthy = storage.is_writable()
+        checks["checks"]["storage"] = {
+            "status": "healthy" if storage_healthy else "unhealthy",
+            "writable": storage_healthy
+        }
+        if not storage_healthy:
+            all_healthy = False
+    except Exception as e:
+        checks["checks"]["storage"] = {
+            "status": "unhealthy",
+            "error": str(e)
+        }
+        all_healthy = False
+    
+    # Check cache
+    try:
+        cache = get_cache()
+        # Test cache operations
+        test_key = "__health_check__"
+        cache.set(test_key, "test", ttl=10)
+        cache_value = cache.get(test_key)
+        cache.delete(test_key)
+        cache_healthy = cache_value == "test"
+        
+        checks["checks"]["cache"] = {
+            "status": "healthy" if cache_healthy else "unhealthy",
+            "size": cache.size(),
+            "stats": cache.stats()
+        }
+        if not cache_healthy:
+            all_healthy = False
+    except Exception as e:
+        checks["checks"]["cache"] = {
+            "status": "unhealthy",
+            "error": str(e)
+        }
+        all_healthy = False
+    
+    # Check session middleware
+    try:
+        session_middleware = get_session_middleware()
+        session_loaded = session_middleware is not None
+        
+        checks["checks"]["session_middleware"] = {
+            "status": "healthy" if session_loaded else "not_loaded",
+            "loaded": session_loaded
+        }
+    except Exception as e:
+        checks["checks"]["session_middleware"] = {
+            "status": "error",
+            "error": str(e)
+        }
+    
+    # Overall status
+    if not all_healthy:
+        checks["status"] = "unhealthy"
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=checks
+        )
+    
+    return checks
+
+
+# ==================== METRICS ====================
+
+@router.get("/metrics")
+async def get_metrics_endpoint():
+    """
+    Metrics endpoint.
+    
+    Exposes counters for:
+    - Total requests
+    - Cache hits/misses
+    - Active sessions
+    - Rate limit events
+    - Uptime
+    
+    Returns:
+        Application metrics
+    """
+    metrics = get_metrics()
+    
+    # Get cache stats
+    try:
+        cache = get_cache()
+        cache_stats = cache.stats()
+    except Exception:
+        cache_stats = {}
+    
+    # Get storage stats
+    try:
+        storage = get_storage()
+        storage_stats = storage.get_stats()
+        active_sessions = storage_stats.get("sessions_count", 0)
+    except Exception:
+        storage_stats = {}
+        active_sessions = 0
+    
+    # Get rate limiter stats
+    try:
+        rate_limiter = get_rate_limiter()
+        rate_limiter_stats = rate_limiter.stats() if rate_limiter else {}
+    except Exception:
+        rate_limiter_stats = {}
+    
+    return {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "uptime_seconds": round(metrics.uptime_seconds(), 2),
+        "counters": metrics.get_all(),
+        "cache": cache_stats,
+        "storage": storage_stats,
+        "rate_limiter": rate_limiter_stats,
+        "active_sessions": active_sessions,
+        "app_info": {
+            "name": settings.APP_NAME,
+            "version": settings.APP_VERSION,
+            "environment": "development" if settings.DEBUG else "production"
+        }
+    }
+
+
+# ==================== PROMETHEUS FORMAT (Optional) ====================
+
+@router.get("/metrics/prometheus")
+async def get_prometheus_metrics():
+    """
+    Metrics in Prometheus format.
+    
+    Returns metrics in Prometheus text exposition format.
+    """
+    metrics = get_metrics()
+    counters = metrics.get_all()
+    
+    lines = [
+        "# HELP intelliweather_requests_total Total number of requests",
+        "# TYPE intelliweather_requests_total counter",
+        f"intelliweather_requests_total {counters.get('total_requests', 0)}",
+        "",
+        "# HELP intelliweather_cache_hits_total Total cache hits",
+        "# TYPE intelliweather_cache_hits_total counter",
+        f"intelliweather_cache_hits_total {counters.get('cache_hits', 0)}",
+        "",
+        "# HELP intelliweather_cache_misses_total Total cache misses",
+        "# TYPE intelliweather_cache_misses_total counter",
+        f"intelliweather_cache_misses_total {counters.get('cache_misses', 0)}",
+        "",
+        "# HELP intelliweather_uptime_seconds Application uptime in seconds",
+        "# TYPE intelliweather_uptime_seconds gauge",
+        f"intelliweather_uptime_seconds {round(metrics.uptime_seconds(), 2)}",
+    ]
+    
+    # Get active sessions
+    try:
+        storage = get_storage()
+        active_sessions = storage.count_active_sessions()
+        lines.extend([
+            "",
+            "# HELP intelliweather_active_sessions Number of active sessions",
+            "# TYPE intelliweather_active_sessions gauge",
+            f"intelliweather_active_sessions {active_sessions}",
+        ])
+    except Exception:
+        pass
+    
+    return "\n".join(lines) + "\n"
diff --git a/middleware/__init__.py b/middleware/__init__.py
new file mode 100644
index 0000000..58189a3
--- /dev/null
+++ b/middleware/__init__.py
@@ -0,0 +1,19 @@
+"""
+Middleware package initialization.
+"""
+
+from middleware.rate_limiter import (
+    RateLimiterMiddleware,
+    SlidingWindowRateLimiter,
+    RateLimitExceeded,
+    get_rate_limiter,
+    init_rate_limiter
+)
+
+__all__ = [
+    "RateLimiterMiddleware",
+    "SlidingWindowRateLimiter",
+    "RateLimitExceeded",
+    "get_rate_limiter",
+    "init_rate_limiter"
+]
diff --git a/middleware/rate_limiter.py b/middleware/rate_limiter.py
new file mode 100644
index 0000000..9dd2682
--- /dev/null
+++ b/middleware/rate_limiter.py
@@ -0,0 +1,273 @@
+"""
+Per-IP Rate Limiter Middleware
+
+This module provides rate limiting functionality with:
+- Configurable requests per minute per IP
+- Sliding window algorithm
+- In-memory storage
+- Thread-safe operations
+"""
+
+import threading
+import time
+from typing import Dict, List, Callable, Tuple
+from collections import defaultdict
+from fastapi import Request, Response, HTTPException, status
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class RateLimitExceeded(HTTPException):
+    """Exception raised when rate limit is exceeded."""
+    
+    def __init__(self, retry_after: int):
+        super().__init__(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail=f"Rate limit exceeded. Try again in {retry_after} seconds.",
+            headers={"Retry-After": str(retry_after)}
+        )
+
+
+class SlidingWindowRateLimiter:
+    """
+    Thread-safe sliding window rate limiter.
+    
+    Uses a sliding window algorithm to track requests per IP.
+    """
+    
+    def __init__(
+        self,
+        requests_per_window: int = None,
+        window_seconds: int = None
+    ):
+        """
+        Initialize the rate limiter.
+        
+        Args:
+            requests_per_window: Maximum requests allowed per window
+            window_seconds: Window size in seconds
+        """
+        self.requests_per_window = requests_per_window or settings.RATE_LIMIT_PER_MIN
+        self.window_seconds = window_seconds or settings.RATE_LIMIT_WINDOW_SECONDS
+        
+        # Store timestamps of requests per IP
+        self._requests: Dict[str, List[float]] = defaultdict(list)
+        self._lock = threading.RLock()
+        
+        # Statistics
+        self._total_requests = 0
+        self._blocked_requests = 0
+        
+        logger.info(
+            f"Rate limiter initialized: {self.requests_per_window} requests "
+            f"per {self.window_seconds} seconds"
+        )
+    
+    def is_allowed(self, identifier: str) -> Tuple[bool, int]:
+        """
+        Check if a request is allowed for the given identifier.
+        
+        Args:
+            identifier: Unique identifier (usually IP address)
+            
+        Returns:
+            Tuple of (is_allowed, retry_after_seconds)
+        """
+        now = time.time()
+        window_start = now - self.window_seconds
+        
+        with self._lock:
+            self._total_requests += 1
+            
+            # Clean up old timestamps
+            self._requests[identifier] = [
+                ts for ts in self._requests[identifier]
+                if ts > window_start
+            ]
+            
+            # Check if limit exceeded
+            current_count = len(self._requests[identifier])
+            
+            if current_count >= self.requests_per_window:
+                self._blocked_requests += 1
+                
+                # Calculate retry after
+                oldest_in_window = min(self._requests[identifier])
+                retry_after = int(oldest_in_window + self.window_seconds - now) + 1
+                
+                return False, max(1, retry_after)
+            
+            # Allow request and record timestamp
+            self._requests[identifier].append(now)
+            return True, 0
+    
+    def get_remaining(self, identifier: str) -> int:
+        """
+        Get remaining requests for an identifier.
+        
+        Args:
+            identifier: Unique identifier (usually IP address)
+            
+        Returns:
+            Number of remaining requests in current window
+        """
+        now = time.time()
+        window_start = now - self.window_seconds
+        
+        with self._lock:
+            current_count = len([
+                ts for ts in self._requests[identifier]
+                if ts > window_start
+            ])
+            return max(0, self.requests_per_window - current_count)
+    
+    def reset(self, identifier: str) -> None:
+        """Reset rate limit for an identifier."""
+        with self._lock:
+            self._requests[identifier] = []
+    
+    def cleanup(self) -> int:
+        """
+        Clean up expired entries.
+        
+        Returns:
+            Number of entries cleaned up
+        """
+        now = time.time()
+        window_start = now - self.window_seconds
+        cleaned = 0
+        
+        with self._lock:
+            for identifier in list(self._requests.keys()):
+                old_len = len(self._requests[identifier])
+                self._requests[identifier] = [
+                    ts for ts in self._requests[identifier]
+                    if ts > window_start
+                ]
+                cleaned += old_len - len(self._requests[identifier])
+                
+                # Remove empty entries
+                if not self._requests[identifier]:
+                    del self._requests[identifier]
+        
+        return cleaned
+    
+    def stats(self) -> Dict:
+        """Get rate limiter statistics."""
+        with self._lock:
+            return {
+                "total_requests": self._total_requests,
+                "blocked_requests": self._blocked_requests,
+                "unique_ips": len(self._requests),
+                "requests_per_window": self.requests_per_window,
+                "window_seconds": self.window_seconds
+            }
+
+
+class RateLimiterMiddleware(BaseHTTPMiddleware):
+    """
+    FastAPI middleware for rate limiting.
+    
+    Limits requests per IP address using sliding window algorithm.
+    """
+    
+    # Paths to exclude from rate limiting
+    EXCLUDED_PATHS = ["/healthz", "/metrics", "/docs", "/redoc", "/openapi.json"]
+    
+    def __init__(
+        self,
+        app,
+        requests_per_window: int = None,
+        window_seconds: int = None,
+        excluded_paths: List[str] = None
+    ):
+        super().__init__(app)
+        self.limiter = SlidingWindowRateLimiter(requests_per_window, window_seconds)
+        self.excluded_paths = excluded_paths or self.EXCLUDED_PATHS
+        
+        logger.info("Rate limiter middleware initialized")
+    
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Process request with rate limiting."""
+        # Skip rate limiting for excluded paths
+        if request.url.path in self.excluded_paths:
+            return await call_next(request)
+        
+        # Get client IP
+        client_ip = self._get_client_ip(request)
+        
+        # Check rate limit
+        is_allowed, retry_after = self.limiter.is_allowed(client_ip)
+        
+        if not is_allowed:
+            logger.warning(f"Rate limit exceeded for IP: {client_ip}")
+            return JSONResponse(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                content={
+                    "detail": f"Rate limit exceeded. Try again in {retry_after} seconds."
+                },
+                headers={
+                    "Retry-After": str(retry_after),
+                    "X-RateLimit-Limit": str(self.limiter.requests_per_window),
+                    "X-RateLimit-Remaining": "0",
+                    "X-RateLimit-Reset": str(int(time.time()) + retry_after)
+                }
+            )
+        
+        # Process request
+        response = await call_next(request)
+        
+        # Add rate limit headers
+        remaining = self.limiter.get_remaining(client_ip)
+        response.headers["X-RateLimit-Limit"] = str(self.limiter.requests_per_window)
+        response.headers["X-RateLimit-Remaining"] = str(remaining)
+        
+        return response
+    
+    def _get_client_ip(self, request: Request) -> str:
+        """
+        Get the client IP address from the request.
+        
+        Handles X-Forwarded-For header for requests behind proxies.
+        """
+        # Check for proxy headers
+        forwarded_for = request.headers.get("X-Forwarded-For")
+        if forwarded_for:
+            # Get the first IP in the chain (original client)
+            return forwarded_for.split(",")[0].strip()
+        
+        real_ip = request.headers.get("X-Real-IP")
+        if real_ip:
+            return real_ip.strip()
+        
+        # Fall back to direct client
+        if request.client:
+            return request.client.host
+        
+        return "unknown"
+
+
+# Global rate limiter instance
+_rate_limiter: SlidingWindowRateLimiter = None
+
+
+def get_rate_limiter() -> SlidingWindowRateLimiter:
+    """Get the global rate limiter instance."""
+    global _rate_limiter
+    if _rate_limiter is None:
+        _rate_limiter = SlidingWindowRateLimiter()
+    return _rate_limiter
+
+
+def init_rate_limiter(
+    requests_per_window: int = None,
+    window_seconds: int = None
+) -> SlidingWindowRateLimiter:
+    """Initialize the global rate limiter."""
+    global _rate_limiter
+    _rate_limiter = SlidingWindowRateLimiter(requests_per_window, window_seconds)
+    return _rate_limiter
diff --git a/modules/__init__.py b/modules/__init__.py
new file mode 100644
index 0000000..764f2b0
--- /dev/null
+++ b/modules/__init__.py
@@ -0,0 +1,22 @@
+"""
+Phase 2 Modules for IntelliWeather API
+
+This package contains the core business logic modules for Phase 2 features.
+"""
+
+from modules.geocode import GeocodingService, get_geocoding_service
+from modules.api_keys import APIKeyManager, get_api_key_manager
+from modules.i18n import I18nService, get_i18n_service, translate
+from modules.prediction import PredictionService, get_prediction_service
+
+__all__ = [
+    "GeocodingService",
+    "get_geocoding_service",
+    "APIKeyManager",
+    "get_api_key_manager",
+    "I18nService",
+    "get_i18n_service",
+    "translate",
+    "PredictionService",
+    "get_prediction_service",
+]
diff --git a/modules/api_keys.py b/modules/api_keys.py
new file mode 100644
index 0000000..ef9c038
--- /dev/null
+++ b/modules/api_keys.py
@@ -0,0 +1,320 @@
+"""
+API Key Management Module
+
+Provides secure API key generation, storage, and validation.
+"""
+
+import secrets
+import hashlib
+import uuid
+from typing import Optional, List, Dict, Any
+from datetime import datetime, timezone, timedelta
+from dataclasses import dataclass, asdict
+
+from config import settings
+from logging_config import get_logger
+from storage import get_storage
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class APIKey:
+    """API Key model."""
+    key_id: str
+    user_id: str
+    name: str
+    key_hash: str  # Only store hash, not the actual key
+    key_prefix: str  # First 8 chars for identification
+    created_at: str
+    expires_at: Optional[str]
+    last_used_at: Optional[str]
+    rate_limit: int
+    total_requests: int
+    is_active: bool
+    
+    @classmethod
+    def create(
+        cls,
+        user_id: str,
+        name: str,
+        rate_limit: int = None,
+        expires_in_days: int = None
+    ) -> tuple["APIKey", str]:
+        """
+        Create a new API key.
+        
+        Returns:
+            Tuple of (APIKey object, raw_key)
+        """
+        # Generate secure random key
+        raw_key = f"iw_live_{secrets.token_hex(24)}"
+        key_hash = hashlib.sha256(raw_key.encode()).hexdigest()
+        key_prefix = raw_key[:12]
+        
+        now = datetime.now(timezone.utc)
+        expires_at = None
+        if expires_in_days:
+            expires_at = (now + timedelta(days=expires_in_days)).isoformat()
+        
+        key = cls(
+            key_id=f"key_{uuid.uuid4().hex[:12]}",
+            user_id=user_id,
+            name=name,
+            key_hash=key_hash,
+            key_prefix=key_prefix,
+            created_at=now.isoformat(),
+            expires_at=expires_at,
+            last_used_at=None,
+            rate_limit=rate_limit or settings.API_KEY_RATE_LIMIT_DEFAULT,
+            total_requests=0,
+            is_active=True
+        )
+        
+        return key, raw_key
+    
+    def is_expired(self) -> bool:
+        """Check if the key has expired."""
+        if not self.expires_at:
+            return False
+        expires = datetime.fromisoformat(self.expires_at)
+        return datetime.now(timezone.utc) > expires
+    
+    def is_valid(self) -> bool:
+        """Check if the key is valid (active and not expired)."""
+        return self.is_active and not self.is_expired()
+
+
+class APIKeyManager:
+    """
+    Manager for API key operations.
+    
+    Features:
+    - Secure key generation and hashing
+    - Key validation
+    - Rate limit tracking per key
+    - Key revocation
+    """
+    
+    # CSV configuration
+    FILE_CONFIG = {
+        "filename": "api_keys.csv",
+        "headers": [
+            "key_id", "user_id", "name", "key_hash", "key_prefix",
+            "created_at", "expires_at", "last_used_at", "rate_limit",
+            "total_requests", "is_active"
+        ]
+    }
+    
+    def __init__(self):
+        """Initialize the API key manager."""
+        self._init_storage()
+        self._rate_limits: Dict[str, List[float]] = {}  # key_id -> list of timestamps
+        logger.info("API key manager initialized")
+    
+    def _init_storage(self) -> None:
+        """Initialize the API keys CSV file."""
+        import os
+        import csv
+        from pathlib import Path
+        
+        data_dir = settings.DATA_DIR
+        Path(data_dir).mkdir(parents=True, exist_ok=True)
+        
+        filepath = os.path.join(data_dir, self.FILE_CONFIG["filename"])
+        if not os.path.exists(filepath):
+            with open(filepath, "w", newline="", encoding="utf-8") as f:
+                writer = csv.writer(f)
+                writer.writerow(self.FILE_CONFIG["headers"])
+            logger.info("Created api_keys.csv")
+    
+    def _get_filepath(self) -> str:
+        """Get the CSV file path."""
+        import os
+        return os.path.join(settings.DATA_DIR, self.FILE_CONFIG["filename"])
+    
+    def _read_all(self) -> List[Dict[str, Any]]:
+        """Read all API keys from storage."""
+        import csv
+        with open(self._get_filepath(), "r", newline="", encoding="utf-8") as f:
+            return list(csv.DictReader(f))
+    
+    def _write_all(self, rows: List[Dict[str, Any]]) -> None:
+        """Write all API keys to storage."""
+        import csv
+        with open(self._get_filepath(), "w", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=self.FILE_CONFIG["headers"])
+            writer.writeheader()
+            writer.writerows(rows)
+    
+    def _append_row(self, row: Dict[str, Any]) -> None:
+        """Append a single row to storage."""
+        import csv
+        with open(self._get_filepath(), "a", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=self.FILE_CONFIG["headers"])
+            writer.writerow(row)
+    
+    def create_key(
+        self,
+        user_id: str,
+        name: str,
+        rate_limit: int = None,
+        expires_in_days: int = None
+    ) -> tuple[APIKey, str]:
+        """
+        Create a new API key for a user.
+        
+        Args:
+            user_id: User ID
+            name: Key name/description
+            rate_limit: Custom rate limit
+            expires_in_days: Key expiration
+            
+        Returns:
+            Tuple of (APIKey object, raw_key)
+        """
+        api_key, raw_key = APIKey.create(user_id, name, rate_limit, expires_in_days)
+        self._append_row(asdict(api_key))
+        logger.info(f"Created API key {api_key.key_id} for user {user_id}")
+        return api_key, raw_key
+    
+    def validate_key(self, raw_key: str) -> Optional[APIKey]:
+        """
+        Validate an API key.
+        
+        Args:
+            raw_key: The raw API key string
+            
+        Returns:
+            APIKey object if valid, None otherwise
+        """
+        if not raw_key:
+            return None
+        
+        key_hash = hashlib.sha256(raw_key.encode()).hexdigest()
+        
+        rows = self._read_all()
+        for row in rows:
+            if row["key_hash"] == key_hash:
+                row["rate_limit"] = int(row.get("rate_limit", settings.API_KEY_RATE_LIMIT_DEFAULT))
+                row["total_requests"] = int(row.get("total_requests", 0))
+                row["is_active"] = row.get("is_active", "True") == "True"
+                
+                api_key = APIKey(**row)
+                
+                if not api_key.is_valid():
+                    logger.warning(f"Invalid or expired API key: {api_key.key_prefix}")
+                    return None
+                
+                return api_key
+        
+        return None
+    
+    def record_usage(self, key_id: str) -> None:
+        """Record API key usage."""
+        rows = self._read_all()
+        for row in rows:
+            if row["key_id"] == key_id:
+                row["total_requests"] = str(int(row.get("total_requests", 0)) + 1)
+                row["last_used_at"] = datetime.now(timezone.utc).isoformat()
+                break
+        
+        self._write_all(rows)
+    
+    def check_rate_limit(self, api_key: APIKey) -> tuple[bool, int]:
+        """
+        Check if API key has exceeded rate limit.
+        
+        Args:
+            api_key: The API key to check
+            
+        Returns:
+            Tuple of (allowed: bool, remaining: int)
+        """
+        import time
+        
+        now = time.time()
+        window = 60  # 1 minute window
+        
+        key_id = api_key.key_id
+        if key_id not in self._rate_limits:
+            self._rate_limits[key_id] = []
+        
+        # Remove old timestamps
+        self._rate_limits[key_id] = [
+            ts for ts in self._rate_limits[key_id]
+            if now - ts < window
+        ]
+        
+        remaining = api_key.rate_limit - len(self._rate_limits[key_id])
+        
+        if remaining <= 0:
+            return False, 0
+        
+        self._rate_limits[key_id].append(now)
+        return True, remaining - 1
+    
+    def get_user_keys(self, user_id: str) -> List[APIKey]:
+        """Get all API keys for a user."""
+        rows = self._read_all()
+        keys = []
+        
+        for row in rows:
+            if row["user_id"] == user_id:
+                row["rate_limit"] = int(row.get("rate_limit", settings.API_KEY_RATE_LIMIT_DEFAULT))
+                row["total_requests"] = int(row.get("total_requests", 0))
+                row["is_active"] = row.get("is_active", "True") == "True"
+                keys.append(APIKey(**row))
+        
+        return keys
+    
+    def revoke_key(self, key_id: str, user_id: str) -> bool:
+        """
+        Revoke an API key.
+        
+        Args:
+            key_id: Key ID to revoke
+            user_id: User ID (for authorization)
+            
+        Returns:
+            True if revoked, False otherwise
+        """
+        rows = self._read_all()
+        found = False
+        
+        for row in rows:
+            if row["key_id"] == key_id and row["user_id"] == user_id:
+                row["is_active"] = "False"
+                found = True
+                break
+        
+        if found:
+            self._write_all(rows)
+            logger.info(f"Revoked API key: {key_id}")
+        
+        return found
+    
+    def get_key_by_id(self, key_id: str) -> Optional[APIKey]:
+        """Get an API key by ID."""
+        rows = self._read_all()
+        
+        for row in rows:
+            if row["key_id"] == key_id:
+                row["rate_limit"] = int(row.get("rate_limit", settings.API_KEY_RATE_LIMIT_DEFAULT))
+                row["total_requests"] = int(row.get("total_requests", 0))
+                row["is_active"] = row.get("is_active", "True") == "True"
+                return APIKey(**row)
+        
+        return None
+
+
+# Global manager instance
+_api_key_manager: Optional[APIKeyManager] = None
+
+
+def get_api_key_manager() -> APIKeyManager:
+    """Get the global API key manager instance."""
+    global _api_key_manager
+    if _api_key_manager is None:
+        _api_key_manager = APIKeyManager()
+    return _api_key_manager
diff --git a/modules/geocode.py b/modules/geocode.py
new file mode 100644
index 0000000..5e5a836
--- /dev/null
+++ b/modules/geocode.py
@@ -0,0 +1,270 @@
+"""
+Geocoding Service Module
+
+Provides geocoding and reverse geocoding functionality with caching.
+Uses Open-Meteo Geocoding API.
+"""
+
+import requests
+from typing import List, Optional, Dict, Any
+from datetime import datetime, timezone
+import hashlib
+
+from config import settings
+from logging_config import get_logger
+from cache import get_cache
+
+logger = get_logger(__name__)
+
+
+class GeocodingService:
+    """
+    Service for geocoding and reverse geocoding operations.
+    
+    Features:
+    - Forward geocoding (city name -> coordinates)
+    - Reverse geocoding (coordinates -> city name)
+    - Caching with configurable TTL
+    - Normalization and deduplication of results
+    """
+    
+    def __init__(self):
+        """Initialize the geocoding service."""
+        self._api_url = settings.GEOCODING_API_URL
+        self._cache_ttl = settings.GEOCODE_CACHE_TTL_SECONDS
+        self._timeout = 10
+        logger.info("Geocoding service initialized")
+    
+    def _generate_cache_key(self, query_type: str, **params) -> str:
+        """Generate a cache key for geocoding queries."""
+        param_str = "&".join(f"{k}={v}" for k, v in sorted(params.items()))
+        hash_str = hashlib.md5(param_str.encode()).hexdigest()[:8]
+        return f"geocode:{query_type}:{hash_str}"
+    
+    def _normalize_result(self, result: Dict[str, Any]) -> Dict[str, Any]:
+        """Normalize a geocoding result."""
+        return {
+            "id": result.get("id", 0),
+            "name": result.get("name", ""),
+            "latitude": round(result.get("latitude", 0), 4),
+            "longitude": round(result.get("longitude", 0), 4),
+            "country": result.get("country", ""),
+            "country_code": result.get("country_code"),
+            "admin1": result.get("admin1"),  # State/Province
+            "admin2": result.get("admin2"),  # County/District
+            "timezone": result.get("timezone"),
+            "population": result.get("population"),
+            "elevation": result.get("elevation"),
+            "feature_code": result.get("feature_code"),
+        }
+    
+    def _dedupe_results(self, results: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Remove duplicate results based on coordinates."""
+        seen = set()
+        unique = []
+        
+        for r in results:
+            key = (round(r["latitude"], 2), round(r["longitude"], 2))
+            if key not in seen:
+                seen.add(key)
+                unique.append(r)
+        
+        return unique
+    
+    def search(
+        self,
+        query: str,
+        limit: int = 5,
+        lang: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Search for locations by name.
+        
+        Args:
+            query: Search query (city name, etc.)
+            limit: Maximum number of results
+            lang: Language for results
+            
+        Returns:
+            Dict with results, query, count, and source
+        """
+        cache = get_cache()
+        cache_key = self._generate_cache_key("search", q=query.lower(), limit=limit)
+        
+        # Check cache
+        cached = cache.get(cache_key)
+        if cached:
+            logger.info(f"GEOCODE CACHE HIT for query: {query}")
+            return {**cached, "source": "cache"}
+        
+        # Fetch from API
+        logger.info(f"GEOCODE CACHE MISS for query: {query}. Fetching from API...")
+        
+        try:
+            params = {
+                "name": query,
+                "count": min(limit * 2, 20),  # Fetch extra for deduplication
+                "format": "json"
+            }
+            if lang:
+                params["language"] = lang
+            
+            response = requests.get(
+                self._api_url,
+                params=params,
+                timeout=self._timeout
+            )
+            
+            if response.status_code != 200:
+                logger.error(f"Geocoding API error: {response.status_code}")
+                return {
+                    "results": [],
+                    "query": query,
+                    "count": 0,
+                    "source": "error"
+                }
+            
+            data = response.json()
+            raw_results = data.get("results", [])
+            
+            # Normalize and dedupe
+            normalized = [self._normalize_result(r) for r in raw_results]
+            deduped = self._dedupe_results(normalized)[:limit]
+            
+            result = {
+                "results": deduped,
+                "query": query,
+                "count": len(deduped)
+            }
+            
+            # Cache the result
+            cache.set(cache_key, result, ttl=self._cache_ttl)
+            
+            return {**result, "source": "live"}
+            
+        except requests.exceptions.Timeout:
+            logger.error(f"Geocoding API timeout for query: {query}")
+            return {
+                "results": [],
+                "query": query,
+                "count": 0,
+                "source": "timeout"
+            }
+        except Exception as e:
+            logger.error(f"Geocoding error: {e}")
+            return {
+                "results": [],
+                "query": query,
+                "count": 0,
+                "source": "error"
+            }
+    
+    def reverse(
+        self,
+        lat: float,
+        lon: float
+    ) -> Dict[str, Any]:
+        """
+        Reverse geocode coordinates to a location.
+        
+        Args:
+            lat: Latitude
+            lon: Longitude
+            
+        Returns:
+            Dict with location info and source
+        """
+        # Round coordinates for caching
+        lat_rounded = round(lat, 2)
+        lon_rounded = round(lon, 2)
+        
+        cache = get_cache()
+        cache_key = self._generate_cache_key("reverse", lat=lat_rounded, lon=lon_rounded)
+        
+        # Check cache
+        cached = cache.get(cache_key)
+        if cached:
+            logger.info(f"REVERSE GEOCODE CACHE HIT for: {lat_rounded}, {lon_rounded}")
+            return {**cached, "source": "cache"}
+        
+        # For reverse geocoding, we search nearby and find closest
+        logger.info(f"REVERSE GEOCODE CACHE MISS for: {lat_rounded}, {lon_rounded}")
+        
+        try:
+            # Use a search with coordinates - Open-Meteo doesn't have direct reverse
+            # So we'll search for nearby locations
+            params = {
+                "name": f"{lat},{lon}",  # This won't work directly
+                "count": 1,
+                "format": "json"
+            }
+            
+            # Alternative: Use a different approach with the forecast API
+            # to get timezone/location info
+            forecast_url = settings.OPEN_METEO_API_URL
+            forecast_params = {
+                "latitude": lat,
+                "longitude": lon,
+                "current": "temperature_2m",
+                "timezone": "auto"
+            }
+            
+            response = requests.get(
+                forecast_url,
+                params=forecast_params,
+                timeout=self._timeout
+            )
+            
+            if response.status_code == 200:
+                data = response.json()
+                location = {
+                    "id": 0,
+                    "name": f"Location at {lat_rounded}, {lon_rounded}",
+                    "latitude": lat_rounded,
+                    "longitude": lon_rounded,
+                    "country": "",
+                    "country_code": None,
+                    "admin1": None,
+                    "admin2": None,
+                    "timezone": data.get("timezone"),
+                    "population": None,
+                    "elevation": data.get("elevation"),
+                    "feature_code": None
+                }
+                
+                result = {
+                    "location": location,
+                    "latitude": lat,
+                    "longitude": lon
+                }
+                
+                cache.set(cache_key, result, ttl=self._cache_ttl)
+                return {**result, "source": "live"}
+            
+            return {
+                "location": None,
+                "latitude": lat,
+                "longitude": lon,
+                "source": "error"
+            }
+            
+        except Exception as e:
+            logger.error(f"Reverse geocoding error: {e}")
+            return {
+                "location": None,
+                "latitude": lat,
+                "longitude": lon,
+                "source": "error"
+            }
+
+
+# Global service instance
+_geocoding_service: Optional[GeocodingService] = None
+
+
+def get_geocoding_service() -> GeocodingService:
+    """Get the global geocoding service instance."""
+    global _geocoding_service
+    if _geocoding_service is None:
+        _geocoding_service = GeocodingService()
+    return _geocoding_service
diff --git a/modules/growth/__init__.py b/modules/growth/__init__.py
new file mode 100644
index 0000000..79dc389
--- /dev/null
+++ b/modules/growth/__init__.py
@@ -0,0 +1,514 @@
+"""
+IntelliWeather - Growth Features Module
+
+Includes:
+- Analytics event tracking
+- Referral system
+- Shareable forecast links
+- Social preview image generation
+"""
+
+import uuid
+import hashlib
+import hmac
+import json
+from datetime import datetime, timezone, timedelta
+from typing import Optional, List, Dict, Any
+from dataclasses import dataclass, field
+from enum import Enum
+
+from pydantic import BaseModel
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+# ==================== ANALYTICS ====================
+
+class EventType(str, Enum):
+    """Analytics event types"""
+    PAGE_VIEW = "page_view"
+    SEARCH = "search"
+    WEATHER_FETCH = "weather_fetch"
+    FORECAST_VIEW = "forecast_view"
+    ALERT_VIEW = "alert_view"
+    SIGNUP = "signup"
+    LOGIN = "login"
+    SHARE = "share"
+    DOWNLOAD = "download"
+    API_CALL = "api_call"
+    ERROR = "error"
+
+
+@dataclass
+class AnalyticsEvent:
+    """Analytics event data"""
+    id: str
+    event_type: EventType
+    timestamp: datetime
+    user_id: Optional[str] = None
+    session_id: Optional[str] = None
+    properties: Dict[str, Any] = field(default_factory=dict)
+    
+    @classmethod
+    def create(
+        cls,
+        event_type: EventType,
+        user_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        **properties
+    ) -> "AnalyticsEvent":
+        return cls(
+            id=str(uuid.uuid4()),
+            event_type=event_type,
+            timestamp=datetime.now(timezone.utc),
+            user_id=user_id,
+            session_id=session_id,
+            properties=properties
+        )
+    
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "event_type": self.event_type.value,
+            "timestamp": self.timestamp.isoformat(),
+            "user_id": self.user_id,
+            "session_id": self.session_id,
+            "properties": self.properties
+        }
+
+
+class AnalyticsService:
+    """In-process analytics event capture"""
+    
+    def __init__(self, max_events: int = 10000):
+        self.events: List[AnalyticsEvent] = []
+        self.max_events = max_events
+        self.event_counts: Dict[str, int] = {}
+    
+    def track(
+        self,
+        event_type: EventType,
+        user_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        **properties
+    ) -> AnalyticsEvent:
+        """Track an analytics event"""
+        event = AnalyticsEvent.create(event_type, user_id, session_id, **properties)
+        
+        # Store event
+        self.events.append(event)
+        
+        # Update counts
+        key = event_type.value
+        self.event_counts[key] = self.event_counts.get(key, 0) + 1
+        
+        # Trim old events if needed
+        if len(self.events) > self.max_events:
+            self.events = self.events[-self.max_events:]
+        
+        logger.debug(f"Analytics event tracked: {event_type.value}")
+        return event
+    
+    def get_recent_events(
+        self,
+        event_type: Optional[EventType] = None,
+        limit: int = 100
+    ) -> List[dict]:
+        """Get recent events, optionally filtered by type"""
+        events = self.events
+        
+        if event_type:
+            events = [e for e in events if e.event_type == event_type]
+        
+        return [e.to_dict() for e in events[-limit:]]
+    
+    def get_counts(self) -> Dict[str, int]:
+        """Get event counts by type"""
+        return self.event_counts.copy()
+    
+    def get_top_searches(self, limit: int = 10) -> List[dict]:
+        """Get top search queries"""
+        search_events = [e for e in self.events if e.event_type == EventType.SEARCH]
+        
+        query_counts: Dict[str, int] = {}
+        for event in search_events:
+            query = event.properties.get("query", "").lower()
+            if query:
+                query_counts[query] = query_counts.get(query, 0) + 1
+        
+        sorted_queries = sorted(query_counts.items(), key=lambda x: x[1], reverse=True)
+        return [{"query": q, "count": c} for q, c in sorted_queries[:limit]]
+    
+    def get_stats(self) -> dict:
+        """Get analytics statistics"""
+        return {
+            "total_events": len(self.events),
+            "event_counts": self.event_counts,
+            "top_searches": self.get_top_searches(5),
+            "recent_events_count": len(self.events)
+        }
+
+
+# ==================== REFERRAL SYSTEM ====================
+
+@dataclass
+class ReferralCode:
+    """Referral code data"""
+    code: str
+    user_id: str
+    created_at: datetime
+    uses: int = 0
+    max_uses: Optional[int] = None
+    expires_at: Optional[datetime] = None
+    
+    def is_valid(self) -> bool:
+        """Check if referral code is still valid"""
+        if self.expires_at and datetime.now(timezone.utc) > self.expires_at:
+            return False
+        if self.max_uses and self.uses >= self.max_uses:
+            return False
+        return True
+
+
+@dataclass
+class Referral:
+    """Referral record"""
+    id: str
+    referrer_id: str
+    referred_id: str
+    code: str
+    created_at: datetime
+    status: str = "pending"  # pending, completed, rewarded
+
+
+class ReferralService:
+    """Referral system service"""
+    
+    def __init__(self):
+        self.codes: Dict[str, ReferralCode] = {}
+        self.referrals: List[Referral] = []
+        self.user_codes: Dict[str, str] = {}  # user_id -> code
+    
+    def generate_code(
+        self,
+        user_id: str,
+        max_uses: Optional[int] = None,
+        expires_days: Optional[int] = 30
+    ) -> ReferralCode:
+        """Generate a referral code for a user"""
+        # Check if user already has a code
+        if user_id in self.user_codes:
+            return self.codes[self.user_codes[user_id]]
+        
+        # Generate unique code
+        code = self._generate_unique_code(user_id)
+        
+        expires_at = None
+        if expires_days:
+            expires_at = datetime.now(timezone.utc) + timedelta(days=expires_days)
+        
+        referral_code = ReferralCode(
+            code=code,
+            user_id=user_id,
+            created_at=datetime.now(timezone.utc),
+            max_uses=max_uses,
+            expires_at=expires_at
+        )
+        
+        self.codes[code] = referral_code
+        self.user_codes[user_id] = code
+        
+        logger.info(f"Referral code generated for user {user_id}: {code}")
+        return referral_code
+    
+    def _generate_unique_code(self, user_id: str) -> str:
+        """Generate a unique referral code"""
+        data = f"{user_id}:{datetime.now().isoformat()}:{uuid.uuid4()}"
+        hash_val = hashlib.sha256(data.encode()).hexdigest()[:8].upper()
+        return f"IW-{hash_val}"
+    
+    def validate_code(self, code: str) -> Optional[ReferralCode]:
+        """Validate a referral code"""
+        referral_code = self.codes.get(code.upper())
+        if referral_code and referral_code.is_valid():
+            return referral_code
+        return None
+    
+    def use_code(self, code: str, referred_user_id: str) -> Optional[Referral]:
+        """Use a referral code"""
+        referral_code = self.validate_code(code)
+        if not referral_code:
+            return None
+        
+        # Don't allow self-referral
+        if referral_code.user_id == referred_user_id:
+            return None
+        
+        # Create referral record
+        referral = Referral(
+            id=str(uuid.uuid4()),
+            referrer_id=referral_code.user_id,
+            referred_id=referred_user_id,
+            code=code,
+            created_at=datetime.now(timezone.utc),
+            status="completed"
+        )
+        
+        # Update code usage
+        referral_code.uses += 1
+        
+        self.referrals.append(referral)
+        
+        logger.info(f"Referral code {code} used by {referred_user_id}")
+        return referral
+    
+    def get_user_referrals(self, user_id: str) -> List[Referral]:
+        """Get referrals made by a user"""
+        return [r for r in self.referrals if r.referrer_id == user_id]
+    
+    def get_user_code(self, user_id: str) -> Optional[ReferralCode]:
+        """Get a user's referral code"""
+        code = self.user_codes.get(user_id)
+        if code:
+            return self.codes.get(code)
+        return None
+    
+    def get_stats(self) -> dict:
+        """Get referral system statistics"""
+        return {
+            "total_codes": len(self.codes),
+            "total_referrals": len(self.referrals),
+            "active_codes": sum(1 for c in self.codes.values() if c.is_valid()),
+            "top_referrers": self._get_top_referrers(5)
+        }
+    
+    def _get_top_referrers(self, limit: int) -> List[dict]:
+        """Get top referrers by number of referrals"""
+        referrer_counts: Dict[str, int] = {}
+        for referral in self.referrals:
+            referrer_counts[referral.referrer_id] = referrer_counts.get(referral.referrer_id, 0) + 1
+        
+        sorted_referrers = sorted(referrer_counts.items(), key=lambda x: x[1], reverse=True)
+        return [{"user_id": u, "referrals": c} for u, c in sorted_referrers[:limit]]
+
+
+# ==================== SHAREABLE LINKS ====================
+
+@dataclass
+class ShareableLink:
+    """Shareable forecast link"""
+    token: str
+    lat: float
+    lon: float
+    location_name: str
+    created_at: datetime
+    expires_at: datetime
+    created_by: Optional[str] = None
+    view_count: int = 0
+    
+    def is_valid(self) -> bool:
+        """Check if link is still valid"""
+        return datetime.now(timezone.utc) < self.expires_at
+
+
+class ShareableLinkService:
+    """Service for creating and managing shareable forecast links"""
+    
+    def __init__(self, secret_key: str = None):
+        self.secret_key = secret_key or settings.SECRET_KEY
+        self.links: Dict[str, ShareableLink] = {}
+    
+    def create_link(
+        self,
+        lat: float,
+        lon: float,
+        location_name: str,
+        expires_hours: int = 168,  # 1 week default
+        created_by: Optional[str] = None
+    ) -> ShareableLink:
+        """Create a shareable forecast link"""
+        # Generate signed token
+        token = self._generate_token(lat, lon, location_name)
+        
+        link = ShareableLink(
+            token=token,
+            lat=lat,
+            lon=lon,
+            location_name=location_name,
+            created_at=datetime.now(timezone.utc),
+            expires_at=datetime.now(timezone.utc) + timedelta(hours=expires_hours),
+            created_by=created_by
+        )
+        
+        self.links[token] = link
+        
+        logger.info(f"Shareable link created: {token[:8]}...")
+        return link
+    
+    def _generate_token(self, lat: float, lon: float, location_name: str) -> str:
+        """Generate a signed token for the link"""
+        data = f"{lat}:{lon}:{location_name}:{datetime.now().isoformat()}"
+        signature = hmac.new(
+            self.secret_key.encode(),
+            data.encode(),
+            hashlib.sha256
+        ).hexdigest()[:32]  # Use 128 bits (32 hex chars) for security
+        
+        return f"s_{signature}"
+    
+    def get_link(self, token: str) -> Optional[ShareableLink]:
+        """Get a shareable link by token"""
+        link = self.links.get(token)
+        if link and link.is_valid():
+            link.view_count += 1
+            return link
+        return None
+    
+    def get_link_url(self, link: ShareableLink, base_url: str = "") -> str:
+        """Get the full URL for a shareable link"""
+        return f"{base_url}/s/{link.token}"
+    
+    def get_user_links(self, user_id: str) -> List[ShareableLink]:
+        """Get all links created by a user"""
+        return [l for l in self.links.values() if l.created_by == user_id and l.is_valid()]
+    
+    def cleanup_expired(self) -> int:
+        """Remove expired links"""
+        expired = [k for k, v in self.links.items() if not v.is_valid()]
+        for key in expired:
+            del self.links[key]
+        return len(expired)
+
+
+# ==================== SOCIAL PREVIEW ====================
+
+class SocialPreviewData(BaseModel):
+    """Data for generating social preview images"""
+    location: str
+    temperature: float
+    condition: str
+    icon: str
+    high: Optional[float] = None
+    low: Optional[float] = None
+    
+    def to_og_title(self) -> str:
+        """Generate Open Graph title"""
+        return f"Weather in {self.location} - {self.temperature}°C"
+    
+    def to_og_description(self) -> str:
+        """Generate Open Graph description"""
+        desc = f"Current: {self.condition}, {self.temperature}°C"
+        if self.high and self.low:
+            desc += f" | High: {self.high}°C, Low: {self.low}°C"
+        desc += " | IntelliWeather"
+        return desc
+
+
+class SocialPreviewService:
+    """Service for generating social preview metadata"""
+    
+    def generate_meta_tags(self, data: SocialPreviewData, url: str) -> str:
+        """Generate Open Graph and Twitter meta tags"""
+        tags = f"""
+<meta property="og:type" content="website">
+<meta property="og:title" content="{data.to_og_title()}">
+<meta property="og:description" content="{data.to_og_description()}">
+<meta property="og:url" content="{url}">
+<meta property="og:image" content="{url}/preview.png">
+<meta property="og:site_name" content="IntelliWeather">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="{data.to_og_title()}">
+<meta name="twitter:description" content="{data.to_og_description()}">
+<meta name="twitter:image" content="{url}/preview.png">
+"""
+        return tags.strip()
+    
+    def generate_preview_html(self, data: SocialPreviewData) -> str:
+        """Generate HTML for screenshot-based preview image generation"""
+        return f"""
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <style>
+        * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+        body {{
+            width: 1200px;
+            height: 630px;
+            font-family: 'Inter', system-ui, sans-serif;
+            background: linear-gradient(135deg, #4a1c6e, #7b4397);
+            color: white;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }}
+        .card {{
+            background: rgba(255, 255, 255, 0.1);
+            backdrop-filter: blur(20px);
+            border-radius: 24px;
+            padding: 48px;
+            text-align: center;
+            width: 80%;
+        }}
+        .icon {{ font-size: 120px; margin-bottom: 16px; }}
+        .temp {{ font-size: 96px; font-weight: 700; margin-bottom: 8px; }}
+        .location {{ font-size: 36px; opacity: 0.9; margin-bottom: 16px; }}
+        .condition {{ font-size: 24px; opacity: 0.8; }}
+        .range {{ font-size: 20px; opacity: 0.7; margin-top: 16px; }}
+        .brand {{ position: absolute; bottom: 24px; right: 24px; font-size: 18px; opacity: 0.7; }}
+    </style>
+</head>
+<body>
+    <div class="card">
+        <div class="icon">{data.icon}</div>
+        <div class="temp">{data.temperature}°C</div>
+        <div class="location">{data.location}</div>
+        <div class="condition">{data.condition}</div>
+        {"<div class='range'>H: " + str(data.high) + "°C | L: " + str(data.low) + "°C</div>" if data.high else ""}
+    </div>
+    <div class="brand">🌤️ IntelliWeather</div>
+</body>
+</html>
+"""
+
+
+# ==================== GLOBAL SERVICE INSTANCES ====================
+
+_analytics_service: Optional[AnalyticsService] = None
+_referral_service: Optional[ReferralService] = None
+_shareable_link_service: Optional[ShareableLinkService] = None
+_social_preview_service: Optional[SocialPreviewService] = None
+
+
+def get_analytics_service() -> AnalyticsService:
+    """Get analytics service singleton"""
+    global _analytics_service
+    if _analytics_service is None:
+        _analytics_service = AnalyticsService()
+    return _analytics_service
+
+
+def get_referral_service() -> ReferralService:
+    """Get referral service singleton"""
+    global _referral_service
+    if _referral_service is None:
+        _referral_service = ReferralService()
+    return _referral_service
+
+
+def get_shareable_link_service() -> ShareableLinkService:
+    """Get shareable link service singleton"""
+    global _shareable_link_service
+    if _shareable_link_service is None:
+        _shareable_link_service = ShareableLinkService()
+    return _shareable_link_service
+
+
+def get_social_preview_service() -> SocialPreviewService:
+    """Get social preview service singleton"""
+    global _social_preview_service
+    if _social_preview_service is None:
+        _social_preview_service = SocialPreviewService()
+    return _social_preview_service
diff --git a/modules/i18n.py b/modules/i18n.py
new file mode 100644
index 0000000..f6cc003
--- /dev/null
+++ b/modules/i18n.py
@@ -0,0 +1,492 @@
+"""
+Internationalization (i18n) Service Module
+
+Provides multi-language support for the IntelliWeather API.
+Supported languages: English (en), Hindi (hi), Urdu (ur), Arabic (ar), Spanish (es)
+"""
+
+import json
+import os
+from typing import Dict, Optional, Any
+from functools import lru_cache
+
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+# Default translations (embedded for reliability)
+DEFAULT_TRANSLATIONS = {
+    "en": {
+        "app_name": "IntelliWeather",
+        "tagline": "Your Premium Weather Companion",
+        "current_weather": "Current Weather",
+        "hourly_forecast": "Hourly Forecast",
+        "daily_forecast": "7-Day Forecast",
+        "feels_like": "Feels Like",
+        "humidity": "Humidity",
+        "wind": "Wind",
+        "pressure": "Pressure",
+        "uv_index": "UV Index",
+        "air_quality": "Air Quality",
+        "precipitation": "Precipitation",
+        "sunrise": "Sunrise",
+        "sunset": "Sunset",
+        "search_placeholder": "Search for a city...",
+        "loading": "Loading...",
+        "error": "Error",
+        "retry": "Retry",
+        "connected": "Connected",
+        "disconnected": "Disconnected",
+        "connecting": "Connecting",
+        "sign_in": "Sign In",
+        "sign_up": "Sign Up",
+        "sign_out": "Sign Out",
+        "email": "Email",
+        "password": "Password",
+        "welcome_back": "Welcome Back",
+        "create_account": "Create Account",
+        "dark_mode": "Dark Mode",
+        "light_mode": "Light Mode",
+        "language": "Language",
+        "settings": "Settings",
+        "alerts": "Weather Alerts",
+        "no_alerts": "No active weather alerts",
+        "severe_weather": "Severe Weather Warning",
+        "download_report": "Download Report",
+        "pdf": "PDF",
+        "excel": "Excel",
+        # Weather conditions
+        "clear_sky": "Clear Sky",
+        "partly_cloudy": "Partly Cloudy",
+        "cloudy": "Cloudy",
+        "overcast": "Overcast",
+        "fog": "Fog",
+        "drizzle": "Drizzle",
+        "rain": "Rain",
+        "heavy_rain": "Heavy Rain",
+        "snow": "Snow",
+        "heavy_snow": "Heavy Snow",
+        "thunderstorm": "Thunderstorm",
+        # Days of week
+        "monday": "Monday",
+        "tuesday": "Tuesday",
+        "wednesday": "Wednesday",
+        "thursday": "Thursday",
+        "friday": "Friday",
+        "saturday": "Saturday",
+        "sunday": "Sunday",
+        # Error messages
+        "error_fetch_weather": "Failed to fetch weather data",
+        "error_location": "Unable to get your location",
+        "error_invalid_city": "City not found",
+        "error_rate_limit": "Too many requests. Please try again later.",
+        "error_server": "Server error. Please try again."
+    },
+    "hi": {
+        "app_name": "इंटेलीवेदर",
+        "tagline": "आपका प्रीमियम मौसम साथी",
+        "current_weather": "वर्तमान मौसम",
+        "hourly_forecast": "प्रति घंटा पूर्वानुमान",
+        "daily_forecast": "7-दिन का पूर्वानुमान",
+        "feels_like": "अनुभव",
+        "humidity": "आर्द्रता",
+        "wind": "हवा",
+        "pressure": "दबाव",
+        "uv_index": "यूवी सूचकांक",
+        "air_quality": "वायु गुणवत्ता",
+        "precipitation": "वर्षा",
+        "sunrise": "सूर्योदय",
+        "sunset": "सूर्यास्त",
+        "search_placeholder": "शहर खोजें...",
+        "loading": "लोड हो रहा है...",
+        "error": "त्रुटि",
+        "retry": "पुनः प्रयास करें",
+        "connected": "कनेक्ट",
+        "disconnected": "डिस्कनेक्ट",
+        "connecting": "कनेक्ट हो रहा है",
+        "sign_in": "साइन इन",
+        "sign_up": "साइन अप",
+        "sign_out": "साइन आउट",
+        "email": "ईमेल",
+        "password": "पासवर्ड",
+        "welcome_back": "वापसी पर स्वागत है",
+        "create_account": "खाता बनाएं",
+        "dark_mode": "डार्क मोड",
+        "light_mode": "लाइट मोड",
+        "language": "भाषा",
+        "settings": "सेटिंग्स",
+        "alerts": "मौसम अलर्ट",
+        "no_alerts": "कोई सक्रिय मौसम अलर्ट नहीं",
+        "severe_weather": "गंभीर मौसम चेतावनी",
+        "download_report": "रिपोर्ट डाउनलोड करें",
+        "pdf": "पीडीएफ",
+        "excel": "एक्सेल",
+        "clear_sky": "साफ आसमान",
+        "partly_cloudy": "आंशिक बादल",
+        "cloudy": "बादल",
+        "overcast": "घनघोर बादल",
+        "fog": "कोहरा",
+        "drizzle": "बूंदाबांदी",
+        "rain": "बारिश",
+        "heavy_rain": "भारी बारिश",
+        "snow": "बर्फ",
+        "heavy_snow": "भारी बर्फ",
+        "thunderstorm": "तूफान",
+        "monday": "सोमवार",
+        "tuesday": "मंगलवार",
+        "wednesday": "बुधवार",
+        "thursday": "गुरुवार",
+        "friday": "शुक्रवार",
+        "saturday": "शनिवार",
+        "sunday": "रविवार",
+        "error_fetch_weather": "मौसम डेटा प्राप्त करने में विफल",
+        "error_location": "आपका स्थान प्राप्त करने में असमर्थ",
+        "error_invalid_city": "शहर नहीं मिला",
+        "error_rate_limit": "बहुत सारे अनुरोध। कृपया बाद में पुनः प्रयास करें।",
+        "error_server": "सर्वर त्रुटि। कृपया पुनः प्रयास करें।"
+    },
+    "ur": {
+        "app_name": "انٹیلی ویدر",
+        "tagline": "آپ کا پریمیم موسم ساتھی",
+        "current_weather": "موجودہ موسم",
+        "hourly_forecast": "گھنٹہ وار پیشگوئی",
+        "daily_forecast": "7 دن کی پیشگوئی",
+        "feels_like": "محسوس",
+        "humidity": "نمی",
+        "wind": "ہوا",
+        "pressure": "دباؤ",
+        "uv_index": "یو وی انڈیکس",
+        "air_quality": "ہوا کا معیار",
+        "precipitation": "بارش",
+        "sunrise": "طلوع آفتاب",
+        "sunset": "غروب آفتاب",
+        "search_placeholder": "شہر تلاش کریں...",
+        "loading": "لوڈ ہو رہا ہے...",
+        "error": "غلطی",
+        "retry": "دوبارہ کوشش کریں",
+        "connected": "منسلک",
+        "disconnected": "منقطع",
+        "connecting": "جڑ رہا ہے",
+        "sign_in": "سائن ان",
+        "sign_up": "سائن اپ",
+        "sign_out": "سائن آؤٹ",
+        "email": "ای میل",
+        "password": "پاس ورڈ",
+        "welcome_back": "واپسی پر خوش آمدید",
+        "create_account": "اکاؤنٹ بنائیں",
+        "dark_mode": "ڈارک موڈ",
+        "light_mode": "لائٹ موڈ",
+        "language": "زبان",
+        "settings": "ترتیبات",
+        "alerts": "موسمی الرٹس",
+        "no_alerts": "کوئی فعال موسمی الرٹ نہیں",
+        "severe_weather": "شدید موسم کی وارننگ",
+        "download_report": "رپورٹ ڈاؤن لوڈ کریں",
+        "pdf": "پی ڈی ایف",
+        "excel": "ایکسل",
+        "clear_sky": "صاف آسمان",
+        "partly_cloudy": "جزوی بادل",
+        "cloudy": "بادل",
+        "overcast": "گھنے بادل",
+        "fog": "دھند",
+        "drizzle": "ہلکی بارش",
+        "rain": "بارش",
+        "heavy_rain": "تیز بارش",
+        "snow": "برف",
+        "heavy_snow": "بھاری برف",
+        "thunderstorm": "طوفان",
+        "monday": "پیر",
+        "tuesday": "منگل",
+        "wednesday": "بدھ",
+        "thursday": "جمعرات",
+        "friday": "جمعہ",
+        "saturday": "ہفتہ",
+        "sunday": "اتوار",
+        "error_fetch_weather": "موسم کا ڈیٹا حاصل کرنے میں ناکام",
+        "error_location": "آپ کا مقام حاصل کرنے میں ناکام",
+        "error_invalid_city": "شہر نہیں ملا",
+        "error_rate_limit": "بہت زیادہ درخواستیں۔ براہ کرم بعد میں دوبارہ کوشش کریں۔",
+        "error_server": "سرور کی غلطی۔ براہ کرم دوبارہ کوشش کریں۔"
+    },
+    "ar": {
+        "app_name": "إنتلي ويذر",
+        "tagline": "رفيقك المميز للطقس",
+        "current_weather": "الطقس الحالي",
+        "hourly_forecast": "التوقعات بالساعة",
+        "daily_forecast": "توقعات 7 أيام",
+        "feels_like": "يشعر مثل",
+        "humidity": "الرطوبة",
+        "wind": "الرياح",
+        "pressure": "الضغط",
+        "uv_index": "مؤشر الأشعة فوق البنفسجية",
+        "air_quality": "جودة الهواء",
+        "precipitation": "الهطول",
+        "sunrise": "شروق الشمس",
+        "sunset": "غروب الشمس",
+        "search_placeholder": "ابحث عن مدينة...",
+        "loading": "جار التحميل...",
+        "error": "خطأ",
+        "retry": "إعادة المحاولة",
+        "connected": "متصل",
+        "disconnected": "غير متصل",
+        "connecting": "جار الاتصال",
+        "sign_in": "تسجيل الدخول",
+        "sign_up": "إنشاء حساب",
+        "sign_out": "تسجيل الخروج",
+        "email": "البريد الإلكتروني",
+        "password": "كلمة المرور",
+        "welcome_back": "مرحباً بعودتك",
+        "create_account": "إنشاء حساب",
+        "dark_mode": "الوضع الداكن",
+        "light_mode": "الوضع الفاتح",
+        "language": "اللغة",
+        "settings": "الإعدادات",
+        "alerts": "تنبيهات الطقس",
+        "no_alerts": "لا توجد تنبيهات طقس نشطة",
+        "severe_weather": "تحذير من طقس شديد",
+        "download_report": "تحميل التقرير",
+        "pdf": "بي دي إف",
+        "excel": "إكسل",
+        "clear_sky": "سماء صافية",
+        "partly_cloudy": "غائم جزئياً",
+        "cloudy": "غائم",
+        "overcast": "ملبد بالغيوم",
+        "fog": "ضباب",
+        "drizzle": "رذاذ",
+        "rain": "مطر",
+        "heavy_rain": "أمطار غزيرة",
+        "snow": "ثلج",
+        "heavy_snow": "ثلج كثيف",
+        "thunderstorm": "عاصفة رعدية",
+        "monday": "الإثنين",
+        "tuesday": "الثلاثاء",
+        "wednesday": "الأربعاء",
+        "thursday": "الخميس",
+        "friday": "الجمعة",
+        "saturday": "السبت",
+        "sunday": "الأحد",
+        "error_fetch_weather": "فشل في جلب بيانات الطقس",
+        "error_location": "تعذر الحصول على موقعك",
+        "error_invalid_city": "المدينة غير موجودة",
+        "error_rate_limit": "طلبات كثيرة جداً. يرجى المحاولة لاحقاً.",
+        "error_server": "خطأ في الخادم. يرجى المحاولة مرة أخرى."
+    },
+    "es": {
+        "app_name": "IntelliWeather",
+        "tagline": "Tu compañero premium del clima",
+        "current_weather": "Clima Actual",
+        "hourly_forecast": "Pronóstico por Hora",
+        "daily_forecast": "Pronóstico de 7 Días",
+        "feels_like": "Sensación Térmica",
+        "humidity": "Humedad",
+        "wind": "Viento",
+        "pressure": "Presión",
+        "uv_index": "Índice UV",
+        "air_quality": "Calidad del Aire",
+        "precipitation": "Precipitación",
+        "sunrise": "Amanecer",
+        "sunset": "Atardecer",
+        "search_placeholder": "Buscar una ciudad...",
+        "loading": "Cargando...",
+        "error": "Error",
+        "retry": "Reintentar",
+        "connected": "Conectado",
+        "disconnected": "Desconectado",
+        "connecting": "Conectando",
+        "sign_in": "Iniciar Sesión",
+        "sign_up": "Registrarse",
+        "sign_out": "Cerrar Sesión",
+        "email": "Correo Electrónico",
+        "password": "Contraseña",
+        "welcome_back": "Bienvenido de Nuevo",
+        "create_account": "Crear Cuenta",
+        "dark_mode": "Modo Oscuro",
+        "light_mode": "Modo Claro",
+        "language": "Idioma",
+        "settings": "Configuración",
+        "alerts": "Alertas del Clima",
+        "no_alerts": "Sin alertas activas del clima",
+        "severe_weather": "Advertencia de Clima Severo",
+        "download_report": "Descargar Informe",
+        "pdf": "PDF",
+        "excel": "Excel",
+        "clear_sky": "Cielo Despejado",
+        "partly_cloudy": "Parcialmente Nublado",
+        "cloudy": "Nublado",
+        "overcast": "Cubierto",
+        "fog": "Niebla",
+        "drizzle": "Llovizna",
+        "rain": "Lluvia",
+        "heavy_rain": "Lluvia Intensa",
+        "snow": "Nieve",
+        "heavy_snow": "Nevada Intensa",
+        "thunderstorm": "Tormenta Eléctrica",
+        "monday": "Lunes",
+        "tuesday": "Martes",
+        "wednesday": "Miércoles",
+        "thursday": "Jueves",
+        "friday": "Viernes",
+        "saturday": "Sábado",
+        "sunday": "Domingo",
+        "error_fetch_weather": "Error al obtener datos del clima",
+        "error_location": "No se pudo obtener tu ubicación",
+        "error_invalid_city": "Ciudad no encontrada",
+        "error_rate_limit": "Demasiadas solicitudes. Por favor, intenta más tarde.",
+        "error_server": "Error del servidor. Por favor, intenta de nuevo."
+    }
+}
+
+
+class I18nService:
+    """
+    Internationalization service for multi-language support.
+    
+    Features:
+    - Translation lookup with fallback to English
+    - Dynamic language switching
+    - JSON translation file support
+    """
+    
+    def __init__(self):
+        """Initialize the i18n service."""
+        self._translations: Dict[str, Dict[str, str]] = DEFAULT_TRANSLATIONS.copy()
+        self._default_lang = settings.DEFAULT_LANGUAGE
+        self._load_translation_files()
+        logger.info(f"I18n service initialized with languages: {list(self._translations.keys())}")
+    
+    def _load_translation_files(self) -> None:
+        """Load translation files from i18n directory."""
+        i18n_dir = os.path.join(os.path.dirname(__file__), "..", "i18n")
+        
+        if not os.path.exists(i18n_dir):
+            logger.debug("No i18n directory found, using embedded translations")
+            return
+        
+        for lang in settings.SUPPORTED_LANGUAGES:
+            filepath = os.path.join(i18n_dir, f"{lang}.json")
+            if os.path.exists(filepath):
+                try:
+                    with open(filepath, "r", encoding="utf-8") as f:
+                        file_translations = json.load(f)
+                        # Merge with defaults (file takes precedence)
+                        if lang in self._translations:
+                            self._translations[lang].update(file_translations)
+                        else:
+                            self._translations[lang] = file_translations
+                    logger.debug(f"Loaded translation file: {filepath}")
+                except Exception as e:
+                    logger.warning(f"Failed to load translation file {filepath}: {e}")
+    
+    def get_supported_languages(self) -> list:
+        """Get list of supported languages."""
+        return list(self._translations.keys())
+    
+    def translate(
+        self,
+        key: str,
+        lang: str = None,
+        **kwargs
+    ) -> str:
+        """
+        Translate a key to the specified language.
+        
+        Args:
+            key: Translation key
+            lang: Target language code
+            **kwargs: Format arguments for the translation
+            
+        Returns:
+            Translated string, or key if not found
+        """
+        lang = lang or self._default_lang
+        
+        # Try requested language
+        if lang in self._translations:
+            value = self._translations[lang].get(key)
+            if value:
+                if kwargs:
+                    try:
+                        return value.format(**kwargs)
+                    except KeyError:
+                        return value
+                return value
+        
+        # Fallback to default language
+        if lang != self._default_lang and self._default_lang in self._translations:
+            value = self._translations[self._default_lang].get(key)
+            if value:
+                if kwargs:
+                    try:
+                        return value.format(**kwargs)
+                    except KeyError:
+                        return value
+                return value
+        
+        # Return key if not found
+        return key
+    
+    def get_all_translations(self, lang: str = None) -> Dict[str, str]:
+        """Get all translations for a language."""
+        lang = lang or self._default_lang
+        return self._translations.get(lang, self._translations.get(self._default_lang, {}))
+    
+    def get_weather_description(self, weather_code: int, lang: str = None) -> str:
+        """
+        Get weather description for a WMO weather code.
+        
+        Args:
+            weather_code: WMO weather code
+            lang: Target language
+            
+        Returns:
+            Human-readable weather description
+        """
+        # WMO weather code mapping
+        code_map = {
+            0: "clear_sky",
+            1: "partly_cloudy",
+            2: "partly_cloudy",
+            3: "overcast",
+            45: "fog",
+            48: "fog",
+            51: "drizzle",
+            53: "drizzle",
+            55: "drizzle",
+            61: "rain",
+            63: "rain",
+            65: "heavy_rain",
+            71: "snow",
+            73: "snow",
+            75: "heavy_snow",
+            77: "snow",
+            80: "rain",
+            81: "rain",
+            82: "heavy_rain",
+            85: "snow",
+            86: "heavy_snow",
+            95: "thunderstorm",
+            96: "thunderstorm",
+            99: "thunderstorm"
+        }
+        
+        key = code_map.get(weather_code, "partly_cloudy")
+        return self.translate(key, lang)
+
+
+# Global service instance
+_i18n_service: Optional[I18nService] = None
+
+
+def get_i18n_service() -> I18nService:
+    """Get the global i18n service instance."""
+    global _i18n_service
+    if _i18n_service is None:
+        _i18n_service = I18nService()
+    return _i18n_service
+
+
+def translate(key: str, lang: str = None, **kwargs) -> str:
+    """Convenience function for translation."""
+    return get_i18n_service().translate(key, lang, **kwargs)
diff --git a/modules/prediction.py b/modules/prediction.py
new file mode 100644
index 0000000..fc64915
--- /dev/null
+++ b/modules/prediction.py
@@ -0,0 +1,439 @@
+"""
+ML Prediction Module
+
+Simple machine learning module for next-day temperature prediction.
+Uses linear regression on historical data from Open-Meteo.
+"""
+
+import os
+import json
+import pickle
+import random
+from typing import Optional, Dict, Any, List, Tuple
+from datetime import datetime, timezone, timedelta
+from dataclasses import dataclass
+
+import requests
+
+from config import settings
+from logging_config import get_logger
+from cache import get_cache
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class PredictionResult:
+    """Result of a temperature prediction."""
+    predicted_temperature: float
+    confidence_interval_low: float
+    confidence_interval_high: float
+    model_version: str
+    trained_at: str
+    historical_days_used: int
+    location: str
+
+
+class SimplePredictionModel:
+    """
+    Simple linear regression model for temperature prediction.
+    
+    Uses historical temperature data to predict next-day temperature.
+    Features include: day of year, previous day temps, trend.
+    """
+    
+    def __init__(self):
+        """Initialize the model."""
+        self.weights: Optional[List[float]] = None
+        self.bias: float = 0.0
+        self.version: str = "1.0.0"
+        self.trained_at: Optional[str] = None
+        self.feature_names = ["day_of_year_sin", "day_of_year_cos", "prev_temp", "temp_trend"]
+        self._random_seed = 42
+    
+    def _compute_features(self, data: List[Dict[str, Any]], index: int) -> Optional[List[float]]:
+        """
+        Compute features for a single data point.
+        
+        Args:
+            data: Historical data list
+            index: Index of current data point
+            
+        Returns:
+            List of features or None if not enough data
+        """
+        import math
+        
+        if index < 3:  # Need at least 3 previous days
+            return None
+        
+        current = data[index]
+        prev1 = data[index - 1]
+        prev2 = data[index - 2]
+        prev3 = data[index - 3]
+        
+        # Parse date
+        date = datetime.fromisoformat(current["date"])
+        day_of_year = date.timetuple().tm_yday
+        
+        # Cyclical encoding for day of year
+        day_sin = math.sin(2 * math.pi * day_of_year / 365)
+        day_cos = math.cos(2 * math.pi * day_of_year / 365)
+        
+        # Previous day temperature (mean)
+        prev_temp = (prev1.get("temperature_max", 20) + prev1.get("temperature_min", 10)) / 2
+        
+        # Temperature trend (difference over 3 days)
+        prev1_mean = (prev1.get("temperature_max", 20) + prev1.get("temperature_min", 10)) / 2
+        prev3_mean = (prev3.get("temperature_max", 20) + prev3.get("temperature_min", 10)) / 2
+        trend = (prev1_mean - prev3_mean) / 2
+        
+        return [day_sin, day_cos, prev_temp, trend]
+    
+    def train(self, data: List[Dict[str, Any]]) -> bool:
+        """
+        Train the model on historical data.
+        
+        Args:
+            data: List of daily weather data with date, temperature_max, temperature_min
+            
+        Returns:
+            True if training successful
+        """
+        random.seed(self._random_seed)
+        
+        if len(data) < 30:
+            logger.warning("Not enough data for training (need at least 30 days)")
+            return False
+        
+        # Prepare training data
+        X = []
+        y = []
+        
+        for i in range(3, len(data) - 1):
+            features = self._compute_features(data, i)
+            if features:
+                X.append(features)
+                # Target: next day mean temperature
+                next_day = data[i + 1]
+                target = (next_day.get("temperature_max", 20) + next_day.get("temperature_min", 10)) / 2
+                y.append(target)
+        
+        if len(X) < 10:
+            logger.warning("Not enough valid training samples")
+            return False
+        
+        # Simple gradient descent for linear regression
+        n_features = len(self.feature_names)
+        self.weights = [0.0] * n_features
+        self.bias = sum(y) / len(y)  # Initialize bias to mean
+        
+        learning_rate = 0.01
+        epochs = 100
+        
+        for _ in range(epochs):
+            for xi, yi in zip(X, y):
+                # Prediction
+                pred = self.bias + sum(w * f for w, f in zip(self.weights, xi))
+                
+                # Error
+                error = pred - yi
+                
+                # Update weights
+                for j in range(n_features):
+                    self.weights[j] -= learning_rate * error * xi[j]
+                self.bias -= learning_rate * error
+        
+        self.trained_at = datetime.now(timezone.utc).isoformat()
+        logger.info(f"Model trained with {len(X)} samples")
+        
+        return True
+    
+    def predict(self, features: List[float]) -> Tuple[float, float, float]:
+        """
+        Make a prediction.
+        
+        Args:
+            features: Input features
+            
+        Returns:
+            Tuple of (prediction, confidence_low, confidence_high)
+        """
+        if not self.weights:
+            raise ValueError("Model not trained")
+        
+        pred = self.bias + sum(w * f for w, f in zip(self.weights, features))
+        
+        # Simple confidence interval (±3°C)
+        confidence = 3.0
+        
+        return pred, pred - confidence, pred + confidence
+    
+    def save(self, filepath: str) -> None:
+        """Save model to file."""
+        model_data = {
+            "weights": self.weights,
+            "bias": self.bias,
+            "version": self.version,
+            "trained_at": self.trained_at,
+            "feature_names": self.feature_names
+        }
+        
+        with open(filepath, "w") as f:
+            json.dump(model_data, f)
+        
+        logger.info(f"Model saved to {filepath}")
+    
+    def load(self, filepath: str) -> bool:
+        """Load model from file."""
+        if not os.path.exists(filepath):
+            return False
+        
+        try:
+            with open(filepath, "r") as f:
+                model_data = json.load(f)
+            
+            self.weights = model_data["weights"]
+            self.bias = model_data["bias"]
+            self.version = model_data["version"]
+            self.trained_at = model_data["trained_at"]
+            self.feature_names = model_data["feature_names"]
+            
+            logger.info(f"Model loaded from {filepath}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to load model: {e}")
+            return False
+
+
+class PredictionService:
+    """
+    Service for weather predictions.
+    
+    Features:
+    - Train model on historical data
+    - Predict next-day temperature
+    - Cache predictions
+    """
+    
+    def __init__(self):
+        """Initialize the prediction service."""
+        self._model = SimplePredictionModel()
+        self._model_dir = os.path.join(settings.DATA_DIR, "models")
+        self._model_path = os.path.join(self._model_dir, "temp_model.json")
+        self._historical_url = settings.OPEN_METEO_HISTORICAL_URL
+        
+        # Create model directory
+        os.makedirs(self._model_dir, exist_ok=True)
+        
+        # Try to load existing model
+        self._model.load(self._model_path)
+        
+        logger.info("Prediction service initialized")
+    
+    def _fetch_historical_data(
+        self,
+        lat: float,
+        lon: float,
+        days: int = 365
+    ) -> Optional[List[Dict[str, Any]]]:
+        """Fetch historical weather data."""
+        end_date = datetime.now(timezone.utc).date() - timedelta(days=1)
+        start_date = end_date - timedelta(days=days)
+        
+        try:
+            params = {
+                "latitude": lat,
+                "longitude": lon,
+                "start_date": start_date.isoformat(),
+                "end_date": end_date.isoformat(),
+                "daily": "temperature_2m_max,temperature_2m_min",
+                "timezone": "auto"
+            }
+            
+            response = requests.get(
+                self._historical_url,
+                params=params,
+                timeout=30
+            )
+            
+            if response.status_code != 200:
+                logger.error(f"Historical API error: {response.status_code}")
+                return None
+            
+            data = response.json()
+            daily = data.get("daily", {})
+            
+            if not daily.get("time"):
+                return None
+            
+            result = []
+            for i, date in enumerate(daily["time"]):
+                result.append({
+                    "date": date,
+                    "temperature_max": daily["temperature_2m_max"][i],
+                    "temperature_min": daily["temperature_2m_min"][i]
+                })
+            
+            return result
+            
+        except Exception as e:
+            logger.error(f"Failed to fetch historical data: {e}")
+            return None
+    
+    def train_model(self, lat: float, lon: float) -> bool:
+        """
+        Train the model on historical data for a location.
+        
+        Args:
+            lat: Latitude
+            lon: Longitude
+            
+        Returns:
+            True if training successful
+        """
+        logger.info(f"Training model for location: {lat}, {lon}")
+        
+        # Fetch historical data
+        data = self._fetch_historical_data(lat, lon, settings.ML_HISTORICAL_DAYS)
+        
+        if not data:
+            logger.error("No historical data available for training")
+            return False
+        
+        # Train model
+        success = self._model.train(data)
+        
+        if success:
+            self._model.save(self._model_path)
+        
+        return success
+    
+    def predict_next_day(
+        self,
+        lat: float,
+        lon: float
+    ) -> Optional[PredictionResult]:
+        """
+        Predict next day temperature for a location.
+        
+        Args:
+            lat: Latitude
+            lon: Longitude
+            
+        Returns:
+            PredictionResult or None if prediction fails
+        """
+        cache = get_cache()
+        cache_key = f"prediction:{round(lat, 2)}:{round(lon, 2)}"
+        
+        # Check cache
+        cached = cache.get(cache_key)
+        if cached:
+            logger.info(f"PREDICTION CACHE HIT for {lat}, {lon}")
+            return PredictionResult(**cached)
+        
+        # Check if model is trained
+        if not self._model.weights:
+            # Try to train with recent data
+            logger.info("Model not trained, attempting to train...")
+            if not self.train_model(lat, lon):
+                # Use fallback prediction
+                return self._fallback_prediction(lat, lon)
+        
+        # Fetch recent data for features
+        recent_data = self._fetch_historical_data(lat, lon, 7)
+        
+        if not recent_data or len(recent_data) < 4:
+            return self._fallback_prediction(lat, lon)
+        
+        # Compute features using most recent data
+        features = self._model._compute_features(recent_data, len(recent_data) - 1)
+        
+        if not features:
+            return self._fallback_prediction(lat, lon)
+        
+        # Make prediction
+        try:
+            pred, low, high = self._model.predict(features)
+            
+            result = PredictionResult(
+                predicted_temperature=round(pred, 1),
+                confidence_interval_low=round(low, 1),
+                confidence_interval_high=round(high, 1),
+                model_version=self._model.version,
+                trained_at=self._model.trained_at or datetime.now(timezone.utc).isoformat(),
+                historical_days_used=settings.ML_HISTORICAL_DAYS,
+                location=f"{lat}, {lon}"
+            )
+            
+            # Cache prediction (1 hour)
+            cache.set(cache_key, result.__dict__, ttl=3600)
+            
+            return result
+            
+        except Exception as e:
+            logger.error(f"Prediction failed: {e}")
+            return self._fallback_prediction(lat, lon)
+    
+    def _fallback_prediction(self, lat: float, lon: float) -> PredictionResult:
+        """
+        Fallback prediction when model is unavailable.
+        
+        LIMITATIONS:
+        - Uses very simple latitude-based formula
+        - Does not account for:
+          - Hemisphere differences (same formula for N/S)
+          - Seasonal variations
+          - Longitude effects (coastal vs inland)
+          - Elevation
+          - Local climate patterns
+        
+        The formula: base_temp = 25 - abs(lat) * 0.5
+        - Equator (0°): ~25°C
+        - Tropics (±23°): ~13.5°C
+        - Temperate (±45°): ~2.5°C
+        - Polar (±90°): ~-20°C
+        
+        This provides a rough estimate better than no prediction,
+        but should be clearly marked as "fallback" quality.
+        
+        For better fallback predictions, consider:
+        - Historical climate averages per region
+        - Seasonal adjustments based on month
+        - More sophisticated climate models
+        """
+        # Simple climatological estimate based on latitude
+        base_temp = 25 - abs(lat) * 0.5
+        
+        return PredictionResult(
+            predicted_temperature=round(base_temp, 1),
+            confidence_interval_low=round(base_temp - 5, 1),
+            confidence_interval_high=round(base_temp + 5, 1),
+            model_version="fallback",
+            trained_at=datetime.now(timezone.utc).isoformat(),
+            historical_days_used=0,
+            location=f"{lat}, {lon}"
+        )
+    
+    def get_model_info(self) -> Dict[str, Any]:
+        """Get information about the current model."""
+        return {
+            "version": self._model.version,
+            "trained_at": self._model.trained_at,
+            "is_trained": self._model.weights is not None,
+            "feature_names": self._model.feature_names,
+            "model_path": self._model_path
+        }
+
+
+# Global service instance
+_prediction_service: Optional[PredictionService] = None
+
+
+def get_prediction_service() -> PredictionService:
+    """Get the global prediction service instance."""
+    global _prediction_service
+    if _prediction_service is None:
+        _prediction_service = PredictionService()
+    return _prediction_service
diff --git a/modules/reports/__init__.py b/modules/reports/__init__.py
new file mode 100644
index 0000000..2aa8422
--- /dev/null
+++ b/modules/reports/__init__.py
@@ -0,0 +1,10 @@
+"""
+Report Generation Modules
+
+Provides PDF and Excel report generation for weather data.
+"""
+
+from modules.reports.pdf_report import PDFReportGenerator
+from modules.reports.xlsx_report import ExcelReportGenerator
+
+__all__ = ["PDFReportGenerator", "ExcelReportGenerator"]
diff --git a/modules/reports/pdf_report.py b/modules/reports/pdf_report.py
new file mode 100644
index 0000000..794b913
--- /dev/null
+++ b/modules/reports/pdf_report.py
@@ -0,0 +1,331 @@
+"""
+PDF Report Generator
+
+Generates PDF weather reports with charts and formatted data.
+
+LIMITATIONS OF CURRENT IMPLEMENTATION:
+- Uses basic PDF structure without proper PDF library
+- Text only, no images or complex formatting
+- Fixed font (Courier)
+- Simple text-based charts instead of graphical charts
+- Limited to approximately one page of content
+
+FOR PRODUCTION USE:
+- Install reportlab: pip install reportlab
+- Replace _create_simple_pdf() with proper reportlab implementation
+- Add matplotlib for graphical charts: pip install matplotlib
+- Consider using weasyprint for HTML-to-PDF conversion
+"""
+
+import io
+import base64
+from typing import Dict, Any, List, Optional
+from datetime import datetime, timezone
+
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class PDFReportGenerator:
+    """
+    Generates PDF weather reports.
+    
+    Current implementation creates basic valid PDFs with:
+    - Weather data tables as plain text
+    - ASCII-based temperature charts
+    - Basic branding and metadata
+    
+    For production, upgrade to reportlab for:
+    - Rich formatting and fonts
+    - Graphical charts with matplotlib
+    - Multiple pages
+    - Images and logos
+    """
+    
+    def __init__(self):
+        """Initialize the PDF generator."""
+        self._branding = {
+            "title": "IntelliWeather Report",
+            "company": "IntelliWeather",
+            "tagline": "Your Premium Weather Companion"
+        }
+    
+    def generate(
+        self,
+        location: str,
+        weather_data: Dict[str, Any],
+        report_type: str = "daily"
+    ) -> bytes:
+        """
+        Generate a PDF report.
+        
+        Args:
+            location: Location name
+            weather_data: Weather data dict
+            report_type: "hourly" or "daily"
+            
+        Returns:
+            PDF content as bytes
+        """
+        # Generate a simple text-based PDF structure
+        # In production, use reportlab for proper PDF generation
+        
+        content = self._build_content(location, weather_data, report_type)
+        
+        # Create a minimal PDF structure
+        pdf_bytes = self._create_simple_pdf(content)
+        
+        return pdf_bytes
+    
+    def _build_content(
+        self,
+        location: str,
+        weather_data: Dict[str, Any],
+        report_type: str
+    ) -> str:
+        """Build the report content."""
+        now = datetime.now(timezone.utc)
+        
+        lines = []
+        lines.append("=" * 60)
+        lines.append(f"  {self._branding['title']}")
+        lines.append(f"  {self._branding['tagline']}")
+        lines.append("=" * 60)
+        lines.append("")
+        lines.append(f"Location: {location}")
+        lines.append(f"Report Type: {report_type.title()} Forecast")
+        lines.append(f"Generated: {now.strftime('%Y-%m-%d %H:%M:%S UTC')}")
+        lines.append("")
+        lines.append("-" * 60)
+        lines.append("")
+        
+        if report_type == "hourly":
+            lines.extend(self._format_hourly_data(weather_data))
+        else:
+            lines.extend(self._format_daily_data(weather_data))
+        
+        lines.append("")
+        lines.append("-" * 60)
+        lines.append("")
+        lines.append("Data Source: Open-Meteo API")
+        lines.append(f"Powered by {self._branding['company']}")
+        lines.append("")
+        
+        return "\n".join(lines)
+    
+    def _format_hourly_data(self, data: Dict[str, Any]) -> List[str]:
+        """Format hourly forecast data."""
+        lines = []
+        lines.append("HOURLY FORECAST")
+        lines.append("")
+        lines.append(f"{'Time':<20} {'Temp':<10} {'Humidity':<10} {'Precip %':<10}")
+        lines.append("-" * 50)
+        
+        hourly = data.get("hourly", [])
+        for hour in hourly[:24]:
+            time_str = hour.get("time", "")[:16]
+            temp = f"{hour.get('temperature', '--')}°"
+            humidity = f"{hour.get('humidity', '--')}%"
+            precip = f"{hour.get('precipitation_probability', '--')}%"
+            lines.append(f"{time_str:<20} {temp:<10} {humidity:<10} {precip:<10}")
+        
+        return lines
+    
+    def _format_daily_data(self, data: Dict[str, Any]) -> List[str]:
+        """Format daily forecast data."""
+        lines = []
+        lines.append("7-DAY FORECAST")
+        lines.append("")
+        lines.append(f"{'Date':<15} {'Max':<8} {'Min':<8} {'Precip':<10} {'Conditions':<15}")
+        lines.append("-" * 56)
+        
+        daily = data.get("daily", [])
+        for day in daily:
+            date_str = day.get("date", "")[:10]
+            max_temp = f"{day.get('temperature_max', '--')}°"
+            min_temp = f"{day.get('temperature_min', '--')}°"
+            precip = f"{day.get('precipitation_sum', 0):.1f}mm"
+            code = day.get("weather_code", 0)
+            conditions = self._get_condition_text(code)
+            lines.append(f"{date_str:<15} {max_temp:<8} {min_temp:<8} {precip:<10} {conditions:<15}")
+        
+        # Add simple temperature chart
+        lines.append("")
+        lines.append("TEMPERATURE TREND")
+        lines.append("")
+        lines.extend(self._create_text_chart(daily))
+        
+        return lines
+    
+    def _get_condition_text(self, code: int) -> str:
+        """Get text description for weather code."""
+        conditions = {
+            0: "Clear",
+            1: "Mostly Clear",
+            2: "Partly Cloudy",
+            3: "Overcast",
+            45: "Foggy",
+            48: "Fog",
+            51: "Light Drizzle",
+            53: "Drizzle",
+            55: "Heavy Drizzle",
+            61: "Light Rain",
+            63: "Rain",
+            65: "Heavy Rain",
+            71: "Light Snow",
+            73: "Snow",
+            75: "Heavy Snow",
+            80: "Rain Showers",
+            81: "Heavy Showers",
+            82: "Violent Showers",
+            95: "Thunderstorm",
+            96: "T-Storm + Hail",
+            99: "Severe T-Storm"
+        }
+        return conditions.get(code, "Unknown")
+    
+    def _create_text_chart(self, daily: List[Dict[str, Any]]) -> List[str]:
+        """Create a simple text-based temperature chart."""
+        if not daily:
+            return ["No data available"]
+        
+        lines = []
+        max_temps = [d.get("temperature_max", 0) for d in daily]
+        min_temps = [d.get("temperature_min", 0) for d in daily]
+        
+        if not max_temps:
+            return lines
+        
+        chart_max = max(max_temps) + 5
+        chart_min = min(min_temps) - 5
+        chart_range = max(chart_max - chart_min, 1)
+        chart_height = 10
+        
+        # Create chart rows
+        for row in range(chart_height, -1, -1):
+            threshold = chart_min + (row / chart_height) * chart_range
+            line = f"{threshold:5.0f}° |"
+            
+            for i, (max_t, min_t) in enumerate(zip(max_temps, min_temps)):
+                if max_t >= threshold > min_t:
+                    line += " ▓▓ "
+                elif max_t >= threshold and min_t >= threshold:
+                    line += " ██ "
+                else:
+                    line += "    "
+            
+            lines.append(line)
+        
+        # X-axis
+        lines.append("       +" + "----" * len(daily))
+        
+        # Day labels
+        label_line = "       "
+        for day in daily:
+            date = day.get("date", "")
+            if date:
+                label_line += f" {date[8:10]} "
+            else:
+                label_line += "    "
+        lines.append(label_line)
+        
+        return lines
+    
+    def _create_simple_pdf(self, content: str) -> bytes:
+        """
+        Create a minimal PDF structure.
+        
+        This creates a valid PDF with the content as text.
+        For production, use a proper library like reportlab.
+        """
+        # Escape special characters
+        content_escaped = content.replace("\\", "\\\\").replace("(", "\\(").replace(")", "\\)")
+        
+        # PDF structure
+        pdf_lines = [
+            "%PDF-1.4",
+            "1 0 obj",
+            "<<",
+            "/Type /Catalog",
+            "/Pages 2 0 R",
+            ">>",
+            "endobj",
+            "2 0 obj",
+            "<<",
+            "/Type /Pages",
+            "/Kids [3 0 R]",
+            "/Count 1",
+            ">>",
+            "endobj",
+            "3 0 obj",
+            "<<",
+            "/Type /Page",
+            "/Parent 2 0 R",
+            "/MediaBox [0 0 612 792]",
+            "/Contents 4 0 R",
+            "/Resources <<",
+            "/Font <<",
+            "/F1 5 0 R",
+            ">>",
+            ">>",
+            ">>",
+            "endobj",
+            "4 0 obj",
+            "<<",
+            "/Length 6 0 R",
+            ">>",
+            "stream",
+        ]
+        
+        # Build content stream
+        stream_content = "BT\n"
+        stream_content += "/F1 9 Tf\n"
+        y = 750
+        
+        for line in content.split("\n"):
+            if y < 50:
+                break
+            # Escape line for PDF
+            safe_line = line.replace("\\", "\\\\").replace("(", "\\(").replace(")", "\\)")
+            stream_content += f"1 0 0 1 50 {y} Tm\n"
+            stream_content += f"({safe_line}) Tj\n"
+            y -= 12
+        
+        stream_content += "ET\n"
+        
+        pdf_lines.append(stream_content)
+        pdf_lines.extend([
+            "endstream",
+            "endobj",
+            f"6 0 obj",
+            f"{len(stream_content)}",
+            "endobj",
+            "5 0 obj",
+            "<<",
+            "/Type /Font",
+            "/Subtype /Type1",
+            "/BaseFont /Courier",
+            ">>",
+            "endobj",
+            "xref",
+            "0 7",
+            "0000000000 65535 f ",
+            "0000000009 00000 n ",
+            "0000000058 00000 n ",
+            "0000000115 00000 n ",
+            "0000000266 00000 n ",
+            "0000000400 00000 n ",
+            "0000000480 00000 n ",
+            "trailer",
+            "<<",
+            "/Size 7",
+            "/Root 1 0 R",
+            ">>",
+            "startxref",
+            "500",
+            "%%EOF"
+        ])
+        
+        return "\n".join(pdf_lines).encode("latin-1")
diff --git a/modules/reports/xlsx_report.py b/modules/reports/xlsx_report.py
new file mode 100644
index 0000000..ed0c0e2
--- /dev/null
+++ b/modules/reports/xlsx_report.py
@@ -0,0 +1,256 @@
+"""
+Excel Report Generator
+
+Generates Excel weather reports with formatted data and charts.
+Uses openpyxl for Excel generation.
+"""
+
+import io
+from typing import Dict, Any, List, Optional
+from datetime import datetime, timezone
+
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class ExcelReportGenerator:
+    """
+    Generates Excel weather reports.
+    
+    Features:
+    - Formatted weather data sheets
+    - Multiple sheets for different data views
+    - Basic styling and headers
+    """
+    
+    def __init__(self):
+        """Initialize the Excel generator."""
+        self._branding = {
+            "title": "IntelliWeather Report",
+            "company": "IntelliWeather",
+            "tagline": "Your Premium Weather Companion"
+        }
+    
+    def generate(
+        self,
+        location: str,
+        weather_data: Dict[str, Any],
+        report_type: str = "daily"
+    ) -> bytes:
+        """
+        Generate an Excel report.
+        
+        Args:
+            location: Location name
+            weather_data: Weather data dict
+            report_type: "hourly" or "daily"
+            
+        Returns:
+            Excel content as bytes
+        """
+        try:
+            from openpyxl import Workbook
+            from openpyxl.styles import Font, Alignment, Border, Side, PatternFill
+            from openpyxl.utils import get_column_letter
+            
+            return self._generate_with_openpyxl(location, weather_data, report_type)
+        except ImportError:
+            logger.warning("openpyxl not available, generating CSV instead")
+            return self._generate_csv_fallback(location, weather_data, report_type)
+    
+    def _generate_with_openpyxl(
+        self,
+        location: str,
+        weather_data: Dict[str, Any],
+        report_type: str
+    ) -> bytes:
+        """Generate Excel using openpyxl."""
+        from openpyxl import Workbook
+        from openpyxl.styles import Font, Alignment, Border, Side, PatternFill
+        from openpyxl.utils import get_column_letter
+        
+        wb = Workbook()
+        ws = wb.active
+        ws.title = "Weather Report"
+        
+        # Styles
+        header_font = Font(bold=True, size=14)
+        title_font = Font(bold=True, size=16, color="4A1C6E")
+        cell_font = Font(size=11)
+        
+        header_fill = PatternFill(start_color="4A1C6E", end_color="4A1C6E", fill_type="solid")
+        header_font_white = Font(bold=True, color="FFFFFF")
+        
+        thin_border = Border(
+            left=Side(style='thin'),
+            right=Side(style='thin'),
+            top=Side(style='thin'),
+            bottom=Side(style='thin')
+        )
+        
+        # Title Section
+        ws['A1'] = self._branding['title']
+        ws['A1'].font = title_font
+        ws.merge_cells('A1:F1')
+        
+        ws['A2'] = f"Location: {location}"
+        ws['A2'].font = Font(size=12)
+        
+        ws['A3'] = f"Generated: {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}"
+        ws['A3'].font = Font(size=10, italic=True)
+        
+        ws['A4'] = f"Report Type: {report_type.title()} Forecast"
+        ws['A4'].font = Font(size=10)
+        
+        # Data section starts at row 6
+        start_row = 6
+        
+        if report_type == "hourly":
+            headers = ["Time", "Temperature (°C)", "Humidity (%)", "Wind (m/s)", "Precip. Prob. (%)", "Weather"]
+            data = weather_data.get("hourly", [])
+            
+            # Write headers
+            for col, header in enumerate(headers, 1):
+                cell = ws.cell(row=start_row, column=col, value=header)
+                cell.fill = header_fill
+                cell.font = header_font_white
+                cell.border = thin_border
+                cell.alignment = Alignment(horizontal='center')
+            
+            # Write data
+            for row_idx, hour in enumerate(data[:48], start_row + 1):
+                ws.cell(row=row_idx, column=1, value=hour.get("time", "")[:16]).border = thin_border
+                ws.cell(row=row_idx, column=2, value=hour.get("temperature")).border = thin_border
+                ws.cell(row=row_idx, column=3, value=hour.get("humidity")).border = thin_border
+                ws.cell(row=row_idx, column=4, value=hour.get("wind_speed")).border = thin_border
+                ws.cell(row=row_idx, column=5, value=hour.get("precipitation_probability")).border = thin_border
+                ws.cell(row=row_idx, column=6, value=self._get_condition(hour.get("weather_code", 0))).border = thin_border
+        
+        else:  # daily
+            headers = ["Date", "Max Temp (°C)", "Min Temp (°C)", "Precipitation (mm)", "Precip. Prob. (%)", "Sunrise", "Sunset", "Weather"]
+            data = weather_data.get("daily", [])
+            
+            # Write headers
+            for col, header in enumerate(headers, 1):
+                cell = ws.cell(row=start_row, column=col, value=header)
+                cell.fill = header_fill
+                cell.font = header_font_white
+                cell.border = thin_border
+                cell.alignment = Alignment(horizontal='center')
+            
+            # Write data
+            for row_idx, day in enumerate(data, start_row + 1):
+                ws.cell(row=row_idx, column=1, value=day.get("date")).border = thin_border
+                ws.cell(row=row_idx, column=2, value=day.get("temperature_max")).border = thin_border
+                ws.cell(row=row_idx, column=3, value=day.get("temperature_min")).border = thin_border
+                ws.cell(row=row_idx, column=4, value=day.get("precipitation_sum")).border = thin_border
+                ws.cell(row=row_idx, column=5, value=day.get("precipitation_probability_max")).border = thin_border
+                ws.cell(row=row_idx, column=6, value=day.get("sunrise", "")[-5:] if day.get("sunrise") else "").border = thin_border
+                ws.cell(row=row_idx, column=7, value=day.get("sunset", "")[-5:] if day.get("sunset") else "").border = thin_border
+                ws.cell(row=row_idx, column=8, value=self._get_condition(day.get("weather_code", 0))).border = thin_border
+        
+        # Adjust column widths
+        for col in range(1, len(headers) + 1):
+            ws.column_dimensions[get_column_letter(col)].width = 15
+        
+        # Add metadata sheet
+        ws_meta = wb.create_sheet("Metadata")
+        ws_meta['A1'] = "IntelliWeather Report Metadata"
+        ws_meta['A1'].font = title_font
+        
+        ws_meta['A3'] = "Data Source:"
+        ws_meta['B3'] = "Open-Meteo API"
+        
+        ws_meta['A4'] = "Report Generated:"
+        ws_meta['B4'] = datetime.now(timezone.utc).isoformat()
+        
+        ws_meta['A5'] = "Location:"
+        ws_meta['B5'] = location
+        
+        ws_meta['A6'] = "Latitude:"
+        ws_meta['B6'] = weather_data.get("latitude", "N/A")
+        
+        ws_meta['A7'] = "Longitude:"
+        ws_meta['B7'] = weather_data.get("longitude", "N/A")
+        
+        ws_meta['A8'] = "Timezone:"
+        ws_meta['B8'] = weather_data.get("timezone", "N/A")
+        
+        ws_meta['A10'] = "Powered by IntelliWeather"
+        ws_meta['A10'].font = Font(italic=True)
+        
+        # Save to bytes
+        output = io.BytesIO()
+        wb.save(output)
+        output.seek(0)
+        
+        return output.getvalue()
+    
+    def _generate_csv_fallback(
+        self,
+        location: str,
+        weather_data: Dict[str, Any],
+        report_type: str
+    ) -> bytes:
+        """Generate CSV as fallback when openpyxl is not available."""
+        import csv
+        
+        output = io.StringIO()
+        writer = csv.writer(output)
+        
+        # Header
+        writer.writerow([f"IntelliWeather Report - {location}"])
+        writer.writerow([f"Generated: {datetime.now(timezone.utc).isoformat()}"])
+        writer.writerow([])
+        
+        if report_type == "hourly":
+            writer.writerow(["Time", "Temperature (°C)", "Humidity (%)", "Wind (m/s)", "Precip. Prob. (%)"])
+            for hour in weather_data.get("hourly", [])[:48]:
+                writer.writerow([
+                    hour.get("time", ""),
+                    hour.get("temperature"),
+                    hour.get("humidity"),
+                    hour.get("wind_speed"),
+                    hour.get("precipitation_probability")
+                ])
+        else:
+            writer.writerow(["Date", "Max Temp (°C)", "Min Temp (°C)", "Precipitation (mm)", "Weather"])
+            for day in weather_data.get("daily", []):
+                writer.writerow([
+                    day.get("date"),
+                    day.get("temperature_max"),
+                    day.get("temperature_min"),
+                    day.get("precipitation_sum"),
+                    self._get_condition(day.get("weather_code", 0))
+                ])
+        
+        return output.getvalue().encode('utf-8')
+    
+    def _get_condition(self, code: int) -> str:
+        """Get text description for weather code."""
+        conditions = {
+            0: "Clear",
+            1: "Mostly Clear",
+            2: "Partly Cloudy",
+            3: "Overcast",
+            45: "Foggy",
+            48: "Fog",
+            51: "Light Drizzle",
+            53: "Drizzle",
+            55: "Heavy Drizzle",
+            61: "Light Rain",
+            63: "Rain",
+            65: "Heavy Rain",
+            71: "Light Snow",
+            73: "Snow",
+            75: "Heavy Snow",
+            80: "Rain Showers",
+            81: "Heavy Showers",
+            82: "Violent Showers",
+            95: "Thunderstorm",
+            96: "T-Storm + Hail",
+            99: "Severe T-Storm"
+        }
+        return conditions.get(code, "Unknown")
diff --git a/monitoring/alert_rules.yml b/monitoring/alert_rules.yml
new file mode 100644
index 0000000..010a3ac
--- /dev/null
+++ b/monitoring/alert_rules.yml
@@ -0,0 +1,120 @@
+# IntelliWeather Alertmanager Rules
+# Alert rules for monitoring the weather API service
+
+groups:
+  - name: intelliweather.rules
+    rules:
+      # High Error Rate Alert
+      - alert: HighErrorRate
+        expr: |
+          (
+            sum(rate(http_request_total{job="intelliweather", status=~"5.."}[5m]))
+            /
+            sum(rate(http_request_total{job="intelliweather"}[5m]))
+          ) > 0.05
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: "High error rate detected"
+          description: "Error rate is {{ $value | humanizePercentage }} over the last 5 minutes"
+
+      # High Latency Alert
+      - alert: HighLatency
+        expr: |
+          histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket{job="intelliweather"}[5m])) by (le))
+          > 2
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High API latency detected"
+          description: "95th percentile latency is {{ $value | humanizeDuration }}"
+
+      # Low Cache Hit Ratio
+      - alert: LowCacheHitRatio
+        expr: |
+          (
+            sum(rate(cache_hits_total{job="intelliweather"}[10m]))
+            /
+            (sum(rate(cache_hits_total{job="intelliweather"}[10m])) + sum(rate(cache_misses_total{job="intelliweather"}[10m])))
+          ) < 0.5
+        for: 15m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Low cache hit ratio"
+          description: "Cache hit ratio is {{ $value | humanizePercentage }}"
+
+      # Service Down
+      - alert: ServiceDown
+        expr: up{job="intelliweather"} == 0
+        for: 1m
+        labels:
+          severity: critical
+        annotations:
+          summary: "IntelliWeather service is down"
+          description: "The IntelliWeather API service has been down for more than 1 minute"
+
+      # High Memory Usage
+      - alert: HighMemoryUsage
+        expr: |
+          (
+            container_memory_usage_bytes{container="intelliweather"}
+            /
+            container_spec_memory_limit_bytes{container="intelliweather"}
+          ) > 0.85
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High memory usage"
+          description: "Memory usage is {{ $value | humanizePercentage }}"
+
+      # High CPU Usage
+      - alert: HighCPUUsage
+        expr: |
+          (
+            sum(rate(container_cpu_usage_seconds_total{container="intelliweather"}[5m]))
+            /
+            sum(container_spec_cpu_quota{container="intelliweather"} / container_spec_cpu_period{container="intelliweather"})
+          ) > 0.85
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High CPU usage"
+          description: "CPU usage is {{ $value | humanizePercentage }}"
+
+      # Pod Restart Alert
+      - alert: PodRestartingTooOften
+        expr: |
+          increase(kube_pod_container_status_restarts_total{container="intelliweather"}[1h]) > 3
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Pod restarting too frequently"
+          description: "Pod has restarted {{ $value }} times in the last hour"
+
+      # Rate Limiting Active
+      - alert: RateLimitingActive
+        expr: |
+          sum(rate(http_request_total{job="intelliweather", status="429"}[5m])) > 10
+        for: 5m
+        labels:
+          severity: info
+        annotations:
+          summary: "Rate limiting is active"
+          description: "{{ $value }} requests/sec are being rate limited"
+
+      # External API Failures
+      - alert: ExternalAPIFailures
+        expr: |
+          sum(rate(external_api_errors_total{job="intelliweather"}[5m])) > 1
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "External API failures detected"
+          description: "External API (Open-Meteo) is failing at {{ $value }} errors/sec"
diff --git a/monitoring/grafana-dashboard.json b/monitoring/grafana-dashboard.json
new file mode 100644
index 0000000..e0e7cbf
--- /dev/null
+++ b/monitoring/grafana-dashboard.json
@@ -0,0 +1,481 @@
+{
+  "annotations": {
+    "list": []
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 0,
+  "id": null,
+  "links": [],
+  "liveNow": false,
+  "panels": [
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${DS_PROMETHEUS}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "options": {
+        "legend": {
+          "calcs": ["mean", "max"],
+          "displayMode": "table",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "sum(rate(http_request_total{job=\"intelliweather\"}[5m])) by (method)",
+          "legendFormat": "{{method}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Request Rate by Method",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${DS_PROMETHEUS}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 0.5
+              },
+              {
+                "color": "red",
+                "value": 2
+              }
+            ]
+          },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 0
+      },
+      "id": 2,
+      "options": {
+        "legend": {
+          "calcs": ["mean", "max"],
+          "displayMode": "table",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.50, sum(rate(http_request_duration_seconds_bucket{job=\"intelliweather\"}[5m])) by (le))",
+          "legendFormat": "p50",
+          "refId": "A"
+        },
+        {
+          "expr": "histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket{job=\"intelliweather\"}[5m])) by (le))",
+          "legendFormat": "p95",
+          "refId": "B"
+        },
+        {
+          "expr": "histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket{job=\"intelliweather\"}[5m])) by (le))",
+          "legendFormat": "p99",
+          "refId": "C"
+        }
+      ],
+      "title": "Response Latency",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${DS_PROMETHEUS}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "thresholds"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "red",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 0.7
+              },
+              {
+                "color": "green",
+                "value": 0.85
+              }
+            ]
+          },
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 6,
+        "x": 0,
+        "y": 8
+      },
+      "id": 3,
+      "options": {
+        "orientation": "auto",
+        "reduceOptions": {
+          "calcs": ["lastNotNull"],
+          "fields": "",
+          "values": false
+        },
+        "showThresholdLabels": false,
+        "showThresholdMarkers": true
+      },
+      "targets": [
+        {
+          "expr": "sum(rate(cache_hits_total{job=\"intelliweather\"}[10m])) / (sum(rate(cache_hits_total{job=\"intelliweather\"}[10m])) + sum(rate(cache_misses_total{job=\"intelliweather\"}[10m])))",
+          "legendFormat": "Cache Hit Ratio",
+          "refId": "A"
+        }
+      ],
+      "title": "Cache Hit Ratio",
+      "type": "gauge"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${DS_PROMETHEUS}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "thresholds"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 6,
+        "x": 6,
+        "y": 8
+      },
+      "id": 4,
+      "options": {
+        "colorMode": "value",
+        "graphMode": "area",
+        "justifyMode": "auto",
+        "orientation": "auto",
+        "reduceOptions": {
+          "calcs": ["lastNotNull"],
+          "fields": "",
+          "values": false
+        },
+        "textMode": "auto"
+      },
+      "targets": [
+        {
+          "expr": "active_sessions{job=\"intelliweather\"}",
+          "legendFormat": "Active Sessions",
+          "refId": "A"
+        }
+      ],
+      "title": "Active Sessions",
+      "type": "stat"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${DS_PROMETHEUS}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 8
+      },
+      "id": 5,
+      "options": {
+        "legend": {
+          "calcs": ["sum"],
+          "displayMode": "table",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "sum(rate(http_request_total{job=\"intelliweather\"}[5m])) by (status)",
+          "legendFormat": "{{status}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Requests by Status Code",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${DS_PROMETHEUS}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 16
+      },
+      "id": 6,
+      "options": {
+        "legend": {
+          "calcs": ["sum"],
+          "displayMode": "table",
+          "placement": "bottom"
+        },
+        "tooltip": {
+          "mode": "single"
+        }
+      },
+      "targets": [
+        {
+          "expr": "sum(rate(http_request_total{job=\"intelliweather\"}[5m])) by (path)",
+          "legendFormat": "{{path}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Requests by Endpoint",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${DS_PROMETHEUS}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "thresholds"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 70
+              },
+              {
+                "color": "red",
+                "value": 90
+              }
+            ]
+          },
+          "unit": "percent"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 6,
+        "x": 12,
+        "y": 16
+      },
+      "id": 7,
+      "options": {
+        "orientation": "auto",
+        "reduceOptions": {
+          "calcs": ["lastNotNull"],
+          "fields": "",
+          "values": false
+        },
+        "showThresholdLabels": false,
+        "showThresholdMarkers": true
+      },
+      "targets": [
+        {
+          "expr": "(sum(rate(container_cpu_usage_seconds_total{container=\"intelliweather\"}[5m])) / sum(container_spec_cpu_quota{container=\"intelliweather\"} / container_spec_cpu_period{container=\"intelliweather\"})) * 100",
+          "legendFormat": "CPU",
+          "refId": "A"
+        }
+      ],
+      "title": "CPU Usage",
+      "type": "gauge"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "${DS_PROMETHEUS}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "thresholds"
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 70
+              },
+              {
+                "color": "red",
+                "value": 90
+              }
+            ]
+          },
+          "unit": "percent"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 6,
+        "x": 18,
+        "y": 16
+      },
+      "id": 8,
+      "options": {
+        "orientation": "auto",
+        "reduceOptions": {
+          "calcs": ["lastNotNull"],
+          "fields": "",
+          "values": false
+        },
+        "showThresholdLabels": false,
+        "showThresholdMarkers": true
+      },
+      "targets": [
+        {
+          "expr": "(container_memory_usage_bytes{container=\"intelliweather\"} / container_spec_memory_limit_bytes{container=\"intelliweather\"}) * 100",
+          "legendFormat": "Memory",
+          "refId": "A"
+        }
+      ],
+      "title": "Memory Usage",
+      "type": "gauge"
+    }
+  ],
+  "refresh": "30s",
+  "schemaVersion": 38,
+  "style": "dark",
+  "tags": ["weather", "api", "intelliweather"],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "timepicker": {},
+  "timezone": "",
+  "title": "IntelliWeather Dashboard",
+  "uid": "intelliweather",
+  "version": 1
+}
diff --git a/monitoring/prometheus.yml b/monitoring/prometheus.yml
new file mode 100644
index 0000000..5dc42ea
--- /dev/null
+++ b/monitoring/prometheus.yml
@@ -0,0 +1,62 @@
+# Prometheus Scrape Configuration for IntelliWeather
+# Add this to your prometheus.yml scrape_configs section
+
+global:
+  scrape_interval: 15s
+  evaluation_interval: 15s
+
+alerting:
+  alertmanagers:
+    - static_configs:
+        - targets:
+            - alertmanager:9093
+
+rule_files:
+  - "alert_rules.yml"
+
+scrape_configs:
+  # IntelliWeather API metrics
+  - job_name: 'intelliweather'
+    metrics_path: '/metrics/prometheus'
+    static_configs:
+      - targets: ['localhost:8000']
+    relabel_configs:
+      - source_labels: [__address__]
+        target_label: instance
+        replacement: 'intelliweather-api'
+
+  # Kubernetes service discovery (if running in k8s)
+  - job_name: 'kubernetes-pods'
+    kubernetes_sd_configs:
+      - role: pod
+    relabel_configs:
+      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
+        action: keep
+        regex: true
+      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
+        action: replace
+        target_label: __metrics_path__
+        regex: (.+)
+      - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
+        action: replace
+        regex: ([^:]+)(?::\d+)?;(\d+)
+        replacement: $1:$2
+        target_label: __address__
+      - action: labelmap
+        regex: __meta_kubernetes_pod_label_(.+)
+      - source_labels: [__meta_kubernetes_namespace]
+        action: replace
+        target_label: kubernetes_namespace
+      - source_labels: [__meta_kubernetes_pod_name]
+        action: replace
+        target_label: kubernetes_pod_name
+
+  # Redis metrics (if using Redis exporter)
+  - job_name: 'redis'
+    static_configs:
+      - targets: ['redis-exporter:9121']
+
+  # Node metrics
+  - job_name: 'node'
+    static_configs:
+      - targets: ['node-exporter:9100']
diff --git a/nginx.conf b/nginx.conf
new file mode 100644
index 0000000..a41f8de
--- /dev/null
+++ b/nginx.conf
@@ -0,0 +1,152 @@
+# NGINX Configuration for IntelliWeather Load Balancer
+#
+# Features:
+# - Load balancing across multiple app replicas
+# - Static file serving
+# - Gzip compression
+# - Request rate limiting
+# - Health check endpoint passthrough
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    # Basic settings
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+    sendfile on;
+    keepalive_timeout 65;
+
+    # Logging
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" "$http_x_forwarded_for" '
+                    'rt=$request_time uct="$upstream_connect_time" '
+                    'uht="$upstream_header_time" urt="$upstream_response_time"';
+    
+    access_log /var/log/nginx/access.log main;
+    error_log /var/log/nginx/error.log warn;
+
+    # Gzip compression
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
+    gzip_min_length 1000;
+
+    # Rate limiting zone
+    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
+
+    # Upstream - app servers
+    upstream app_servers {
+        # Round-robin load balancing (default)
+        # For sticky sessions, use: ip_hash;
+        server app:8000;
+        
+        # Health check settings
+        keepalive 32;
+    }
+
+    server {
+        listen 80;
+        server_name localhost;
+
+        # Security headers
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-XSS-Protection "1; mode=block" always;
+
+        # Health check endpoint (no rate limiting)
+        location /healthz {
+            proxy_pass http://app_servers;
+            proxy_http_version 1.1;
+            proxy_set_header Connection "";
+        }
+
+        # Metrics endpoint (no rate limiting)
+        location /metrics {
+            proxy_pass http://app_servers;
+            proxy_http_version 1.1;
+            proxy_set_header Connection "";
+        }
+
+        # API endpoints with rate limiting
+        location /weather {
+            limit_req zone=api_limit burst=20 nodelay;
+            proxy_pass http://app_servers;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+        }
+
+        location /hourly {
+            limit_req zone=api_limit burst=20 nodelay;
+            proxy_pass http://app_servers;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+        }
+
+        location /forecast {
+            limit_req zone=api_limit burst=20 nodelay;
+            proxy_pass http://app_servers;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+        }
+
+        location /aqi-alerts {
+            limit_req zone=api_limit burst=20 nodelay;
+            proxy_pass http://app_servers;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+        }
+
+        location /auth {
+            limit_req zone=api_limit burst=10 nodelay;
+            proxy_pass http://app_servers;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+        }
+
+        # Static files - served directly by NGINX
+        location /static {
+            alias /usr/share/nginx/html/static;
+            expires 1d;
+            add_header Cache-Control "public, immutable";
+        }
+
+        # Default - proxy to app
+        location / {
+            proxy_pass http://app_servers;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+        }
+
+        # Error pages
+        error_page 500 502 503 504 /50x.html;
+        location = /50x.html {
+            root /usr/share/nginx/html;
+        }
+    }
+}
diff --git a/notifications/__init__.py b/notifications/__init__.py
new file mode 100644
index 0000000..3529879
--- /dev/null
+++ b/notifications/__init__.py
@@ -0,0 +1,471 @@
+"""
+IntelliWeather - Notifications Module
+
+Pluggable notification system supporting:
+- Email (SMTP / SendGrid)
+- SMS (Twilio)
+- Web Push
+- In-App notifications
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Optional, Dict, Any
+from datetime import datetime, timezone
+from enum import Enum
+import uuid
+import json
+import os
+
+from pydantic import BaseModel, EmailStr
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class NotificationType(str, Enum):
+    """Notification types"""
+    EMAIL = "email"
+    SMS = "sms"
+    PUSH = "push"
+    IN_APP = "in_app"
+
+
+class NotificationPriority(str, Enum):
+    """Notification priority levels"""
+    LOW = "low"
+    NORMAL = "normal"
+    HIGH = "high"
+    URGENT = "urgent"
+
+
+class NotificationStatus(str, Enum):
+    """Notification delivery status"""
+    PENDING = "pending"
+    SENT = "sent"
+    DELIVERED = "delivered"
+    FAILED = "failed"
+    READ = "read"
+
+
+class NotificationTemplate(str, Enum):
+    """Pre-defined notification templates"""
+    WEATHER_ALERT = "weather_alert"
+    SEVERE_WEATHER = "severe_weather"
+    DAILY_FORECAST = "daily_forecast"
+    ACCOUNT_WELCOME = "account_welcome"
+    API_KEY_CREATED = "api_key_created"
+    RATE_LIMIT_WARNING = "rate_limit_warning"
+
+
+class Notification(BaseModel):
+    """Notification data model"""
+    id: str
+    type: NotificationType
+    user_id: Optional[str] = None
+    recipient: str  # email, phone, or user_id
+    subject: str
+    body: str
+    template_id: Optional[str] = None
+    priority: NotificationPriority = NotificationPriority.NORMAL
+    status: NotificationStatus = NotificationStatus.PENDING
+    metadata: Dict[str, Any] = {}
+    created_at: datetime
+    sent_at: Optional[datetime] = None
+    delivered_at: Optional[datetime] = None
+    read_at: Optional[datetime] = None
+    retry_count: int = 0
+    max_retries: int = 3
+    error_message: Optional[str] = None
+    
+    @classmethod
+    def create(
+        cls,
+        notification_type: NotificationType,
+        recipient: str,
+        subject: str,
+        body: str,
+        **kwargs
+    ) -> "Notification":
+        """Factory method to create a notification"""
+        return cls(
+            id=str(uuid.uuid4()),
+            type=notification_type,
+            recipient=recipient,
+            subject=subject,
+            body=body,
+            created_at=datetime.now(timezone.utc),
+            **kwargs
+        )
+
+
+class NotificationBackend(ABC):
+    """Abstract base class for notification backends"""
+    
+    @abstractmethod
+    async def send(self, notification: Notification) -> bool:
+        """Send a notification. Returns True on success."""
+        pass
+    
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if the backend is available and configured"""
+        pass
+
+
+class EmailBackend(NotificationBackend):
+    """Email notification backend supporting SMTP and SendGrid"""
+    
+    def __init__(self):
+        self.smtp_host = os.getenv("SMTP_HOST", "")
+        self.smtp_port = int(os.getenv("SMTP_PORT", "587"))
+        self.smtp_username = os.getenv("SMTP_USERNAME", "")
+        self.smtp_password = os.getenv("SMTP_PASSWORD", "")
+        self.sendgrid_api_key = os.getenv("SENDGRID_API_KEY", "")
+        self.from_email = os.getenv("FROM_EMAIL", "noreply@intelliweather.io")
+    
+    def is_available(self) -> bool:
+        return bool(self.sendgrid_api_key or (self.smtp_host and self.smtp_username))
+    
+    async def send(self, notification: Notification) -> bool:
+        if not self.is_available():
+            logger.warning("Email backend not configured")
+            return False
+        
+        try:
+            if self.sendgrid_api_key:
+                return await self._send_sendgrid(notification)
+            else:
+                return await self._send_smtp(notification)
+        except Exception as e:
+            logger.error(f"Failed to send email: {e}")
+            return False
+    
+    async def _send_sendgrid(self, notification: Notification) -> bool:
+        """Send email via SendGrid API"""
+        try:
+            import httpx
+            
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    "https://api.sendgrid.com/v3/mail/send",
+                    headers={
+                        "Authorization": f"Bearer {self.sendgrid_api_key}",
+                        "Content-Type": "application/json"
+                    },
+                    json={
+                        "personalizations": [{"to": [{"email": notification.recipient}]}],
+                        "from": {"email": self.from_email, "name": "IntelliWeather"},
+                        "subject": notification.subject,
+                        "content": [
+                            {"type": "text/plain", "value": notification.body},
+                            {"type": "text/html", "value": self._html_template(notification)}
+                        ]
+                    },
+                    timeout=30.0
+                )
+                return response.status_code in (200, 202)
+        except ImportError:
+            logger.error("httpx not installed for SendGrid")
+            return False
+    
+    async def _send_smtp(self, notification: Notification) -> bool:
+        """Send email via SMTP"""
+        try:
+            import smtplib
+            from email.mime.text import MIMEText
+            from email.mime.multipart import MIMEMultipart
+            
+            msg = MIMEMultipart("alternative")
+            msg["Subject"] = notification.subject
+            msg["From"] = self.from_email
+            msg["To"] = notification.recipient
+            
+            msg.attach(MIMEText(notification.body, "plain"))
+            msg.attach(MIMEText(self._html_template(notification), "html"))
+            
+            with smtplib.SMTP(self.smtp_host, self.smtp_port) as server:
+                server.starttls()
+                server.login(self.smtp_username, self.smtp_password)
+                server.sendmail(self.from_email, notification.recipient, msg.as_string())
+            
+            return True
+        except Exception as e:
+            logger.error(f"SMTP send failed: {e}")
+            return False
+    
+    def _html_template(self, notification: Notification) -> str:
+        """Generate HTML email template"""
+        return f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <style>
+                body {{ font-family: 'Inter', Arial, sans-serif; background: #f8fafc; padding: 20px; }}
+                .container {{ max-width: 600px; margin: 0 auto; background: white; border-radius: 16px; overflow: hidden; box-shadow: 0 4px 6px rgba(0,0,0,0.1); }}
+                .header {{ background: linear-gradient(135deg, #4a1c6e, #7b4397); padding: 30px; text-align: center; }}
+                .header h1 {{ color: white; margin: 0; font-size: 24px; }}
+                .content {{ padding: 30px; }}
+                .footer {{ background: #1e293b; color: #94a3b8; padding: 20px; text-align: center; font-size: 12px; }}
+                .btn {{ display: inline-block; background: #d4af37; color: #4a1c6e; padding: 12px 24px; border-radius: 8px; text-decoration: none; font-weight: 600; }}
+            </style>
+        </head>
+        <body>
+            <div class="container">
+                <div class="header">
+                    <h1>🌤️ IntelliWeather</h1>
+                </div>
+                <div class="content">
+                    <h2>{notification.subject}</h2>
+                    <p>{notification.body}</p>
+                </div>
+                <div class="footer">
+                    <p>© 2024 IntelliWeather. All rights reserved.</p>
+                    <p><a href="#" style="color: #d4af37;">Unsubscribe</a> | <a href="#" style="color: #d4af37;">Preferences</a></p>
+                </div>
+            </div>
+        </body>
+        </html>
+        """
+
+
+class SMSBackend(NotificationBackend):
+    """SMS notification backend using Twilio"""
+    
+    def __init__(self):
+        self.account_sid = os.getenv("TWILIO_ACCOUNT_SID", "")
+        self.auth_token = os.getenv("TWILIO_AUTH_TOKEN", "")
+        self.phone_number = os.getenv("TWILIO_PHONE_NUMBER", "")
+    
+    def is_available(self) -> bool:
+        return bool(self.account_sid and self.auth_token and self.phone_number)
+    
+    async def send(self, notification: Notification) -> bool:
+        if not self.is_available():
+            logger.warning("SMS backend not configured, using mock")
+            return self._mock_send(notification)
+        
+        try:
+            import httpx
+            
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    f"https://api.twilio.com/2010-04-01/Accounts/{self.account_sid}/Messages.json",
+                    auth=(self.account_sid, self.auth_token),
+                    data={
+                        "From": self.phone_number,
+                        "To": notification.recipient,
+                        "Body": f"{notification.subject}\n\n{notification.body}"
+                    },
+                    timeout=30.0
+                )
+                return response.status_code == 201
+        except Exception as e:
+            logger.error(f"Failed to send SMS: {e}")
+            return False
+    
+    def _mock_send(self, notification: Notification) -> bool:
+        """Mock SMS send for development/testing"""
+        logger.info(f"[MOCK SMS] To: {notification.recipient}, Subject: {notification.subject}")
+        return True
+
+
+class WebPushBackend(NotificationBackend):
+    """Web Push notification backend"""
+    
+    def __init__(self):
+        self.vapid_private_key = os.getenv("VAPID_PRIVATE_KEY", "")
+        self.vapid_public_key = os.getenv("VAPID_PUBLIC_KEY", "")
+        self.vapid_email = os.getenv("VAPID_EMAIL", "admin@intelliweather.io")
+    
+    def is_available(self) -> bool:
+        return bool(self.vapid_private_key and self.vapid_public_key)
+    
+    async def send(self, notification: Notification) -> bool:
+        if not self.is_available():
+            logger.warning("Web Push backend not configured, using mock")
+            return self._mock_send(notification)
+        
+        try:
+            # In production, use pywebpush
+            # from pywebpush import webpush
+            logger.info(f"[WEB PUSH] To: {notification.recipient}, Subject: {notification.subject}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to send web push: {e}")
+            return False
+    
+    def _mock_send(self, notification: Notification) -> bool:
+        """Mock web push for development/testing"""
+        logger.info(f"[MOCK WEB PUSH] To: {notification.recipient}, Subject: {notification.subject}")
+        return True
+
+
+class InAppBackend(NotificationBackend):
+    """In-app notification backend (stores in database/CSV)"""
+    
+    def __init__(self):
+        self.notifications: Dict[str, List[Notification]] = {}
+    
+    def is_available(self) -> bool:
+        return True
+    
+    async def send(self, notification: Notification) -> bool:
+        try:
+            user_id = notification.user_id or notification.recipient
+            if user_id not in self.notifications:
+                self.notifications[user_id] = []
+            
+            notification.status = NotificationStatus.DELIVERED
+            notification.delivered_at = datetime.now(timezone.utc)
+            self.notifications[user_id].append(notification)
+            
+            logger.info(f"[IN-APP] Notification stored for user: {user_id}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to store in-app notification: {e}")
+            return False
+    
+    def get_user_notifications(
+        self, 
+        user_id: str, 
+        unread_only: bool = False,
+        limit: int = 50
+    ) -> List[Notification]:
+        """Get notifications for a user"""
+        notifications = self.notifications.get(user_id, [])
+        
+        if unread_only:
+            notifications = [n for n in notifications if n.status != NotificationStatus.READ]
+        
+        return sorted(notifications, key=lambda n: n.created_at, reverse=True)[:limit]
+    
+    def mark_as_read(self, user_id: str, notification_id: str) -> bool:
+        """Mark a notification as read"""
+        notifications = self.notifications.get(user_id, [])
+        for notification in notifications:
+            if notification.id == notification_id:
+                notification.status = NotificationStatus.READ
+                notification.read_at = datetime.now(timezone.utc)
+                return True
+        return False
+
+
+class NotificationService:
+    """Main notification service that manages backends and delivery"""
+    
+    def __init__(self):
+        self.backends: Dict[NotificationType, NotificationBackend] = {
+            NotificationType.EMAIL: EmailBackend(),
+            NotificationType.SMS: SMSBackend(),
+            NotificationType.PUSH: WebPushBackend(),
+            NotificationType.IN_APP: InAppBackend(),
+        }
+        self.pending_notifications: List[Notification] = []
+    
+    async def send(
+        self,
+        notification_type: NotificationType,
+        recipient: str,
+        subject: str,
+        body: str,
+        **kwargs
+    ) -> Notification:
+        """Send a notification"""
+        notification = Notification.create(
+            notification_type=notification_type,
+            recipient=recipient,
+            subject=subject,
+            body=body,
+            **kwargs
+        )
+        
+        backend = self.backends.get(notification_type)
+        if not backend:
+            notification.status = NotificationStatus.FAILED
+            notification.error_message = f"No backend for type: {notification_type}"
+            return notification
+        
+        success = await backend.send(notification)
+        
+        if success:
+            notification.status = NotificationStatus.SENT
+            notification.sent_at = datetime.now(timezone.utc)
+        else:
+            notification.status = NotificationStatus.FAILED
+            notification.error_message = "Backend send failed"
+            self.pending_notifications.append(notification)
+        
+        return notification
+    
+    async def send_multi(
+        self,
+        types: List[NotificationType],
+        recipient: str,
+        subject: str,
+        body: str,
+        **kwargs
+    ) -> List[Notification]:
+        """Send notification via multiple channels"""
+        results = []
+        for notification_type in types:
+            notification = await self.send(notification_type, recipient, subject, body, **kwargs)
+            results.append(notification)
+        return results
+    
+    async def retry_failed(self) -> int:
+        """Retry failed notifications with exponential backoff"""
+        retried = 0
+        remaining = []
+        
+        for notification in self.pending_notifications:
+            if notification.retry_count >= notification.max_retries:
+                logger.warning(f"Notification {notification.id} exceeded max retries")
+                continue
+            
+            notification.retry_count += 1
+            backend = self.backends.get(notification.type)
+            
+            if backend and await backend.send(notification):
+                notification.status = NotificationStatus.SENT
+                notification.sent_at = datetime.now(timezone.utc)
+                retried += 1
+            else:
+                remaining.append(notification)
+        
+        self.pending_notifications = remaining
+        return retried
+    
+    def get_user_notifications(self, user_id: str, **kwargs) -> List[Notification]:
+        """Get in-app notifications for a user"""
+        in_app_backend = self.backends.get(NotificationType.IN_APP)
+        if isinstance(in_app_backend, InAppBackend):
+            return in_app_backend.get_user_notifications(user_id, **kwargs)
+        return []
+    
+    def mark_as_read(self, user_id: str, notification_id: str) -> bool:
+        """Mark a notification as read"""
+        in_app_backend = self.backends.get(NotificationType.IN_APP)
+        if isinstance(in_app_backend, InAppBackend):
+            return in_app_backend.mark_as_read(user_id, notification_id)
+        return False
+    
+    def get_available_channels(self) -> List[NotificationType]:
+        """Get list of available notification channels"""
+        return [
+            notification_type 
+            for notification_type, backend in self.backends.items() 
+            if backend.is_available()
+        ]
+
+
+# Global notification service instance
+_notification_service: Optional[NotificationService] = None
+
+
+def get_notification_service() -> NotificationService:
+    """Get or create the notification service singleton"""
+    global _notification_service
+    if _notification_service is None:
+        _notification_service = NotificationService()
+    return _notification_service
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..a26e454
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,54 @@
+# IntelliWeather API - Python Dependencies
+
+# Core Framework
+fastapi>=0.100.0
+uvicorn[standard]>=0.23.0
+gunicorn>=21.0.0
+
+# Configuration
+pydantic>=2.0.0
+pydantic-settings>=2.0.0
+python-dotenv>=1.0.0
+email-validator>=2.0.0
+
+# HTTP Client
+requests>=2.31.0
+httpx>=0.24.0
+
+# Database (optional PostgreSQL)
+psycopg2-binary>=2.9.0
+
+# Authentication
+passlib[bcrypt]>=1.7.0
+python-jose[cryptography]>=3.3.0
+
+# Caching (optional Redis backend)
+# redis>=4.5.0
+
+# Phase 2: Excel Reports
+openpyxl>=3.1.0
+
+# Phase 2: Charts (optional, for enhanced PDF reports)
+# matplotlib>=3.7.0
+# reportlab>=4.0.0
+
+# Phase 3: Observability
+prometheus-client>=0.17.0
+# sentry-sdk>=1.0.0
+
+# Phase 3: Background Jobs (optional)
+# rq>=1.15.0
+# celery>=5.3.0
+
+# Phase 3: Notifications (optional)
+# pywebpush>=1.14.0
+
+# Development & Testing
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+pytest-cov>=4.0.0
+
+# Linting (optional)
+# black>=23.0.0
+# flake8>=6.0.0
+# mypy>=1.0.0
diff --git a/routes/__init__.py b/routes/__init__.py
new file mode 100644
index 0000000..8563d1a
--- /dev/null
+++ b/routes/__init__.py
@@ -0,0 +1,38 @@
+"""
+Routes package initialization.
+
+Phase 1 Routes:
+- auth: Authentication endpoints
+
+Phase 2 Routes:
+- weather_v2: Enhanced weather endpoints (hourly, daily, historical)
+- geocode: Geocoding and reverse geocoding
+- alerts: Weather alerts and warnings
+- downloads: PDF/Excel report downloads
+- apikeys: API key management
+- predict: ML-based predictions
+- admin: Admin dashboard and analytics
+- i18n: Internationalization
+"""
+
+from routes.auth import router as auth_router
+from routes.weather_v2 import router as weather_v2_router
+from routes.geocode import router as geocode_router
+from routes.alerts import router as alerts_router
+from routes.downloads import router as downloads_router
+from routes.apikeys import router as apikeys_router
+from routes.predict import router as predict_router
+from routes.admin import router as admin_router
+from routes.i18n import router as i18n_router
+
+__all__ = [
+    "auth_router",
+    "weather_v2_router",
+    "geocode_router",
+    "alerts_router",
+    "downloads_router",
+    "apikeys_router",
+    "predict_router",
+    "admin_router",
+    "i18n_router",
+]
diff --git a/routes/admin.py b/routes/admin.py
new file mode 100644
index 0000000..fc93209
--- /dev/null
+++ b/routes/admin.py
@@ -0,0 +1,433 @@
+"""
+Admin Dashboard Routes
+
+Provides protected admin analytics and dashboard endpoints.
+"""
+
+from datetime import datetime, timezone, timedelta
+from typing import Dict, Any, List
+
+from fastapi import APIRouter, HTTPException, Request, Depends
+from fastapi.responses import HTMLResponse
+from pydantic import BaseModel, Field
+
+from config import settings
+from logging_config import get_logger
+from cache import get_cache
+from storage import get_storage
+from metrics import get_metrics
+from session_middleware import require_auth
+
+logger = get_logger(__name__)
+
+router = APIRouter(
+    prefix="/admin",
+    tags=["Admin"],
+    responses={
+        401: {"description": "Unauthorized"},
+        403: {"description": "Forbidden - Admin access required"}
+    }
+)
+
+
+class DashboardStats(BaseModel):
+    """Dashboard statistics model."""
+    total_users: int = Field(..., description="Total registered users")
+    active_sessions: int = Field(..., description="Currently active sessions")
+    logins_24h: int = Field(..., description="Logins in the last 24 hours")
+    cache_hit_rate: float = Field(..., description="Cache hit rate percentage")
+    cache_hits: int = Field(..., description="Total cache hits")
+    cache_misses: int = Field(..., description="Total cache misses")
+    cache_size: int = Field(..., description="Current cache size")
+    top_locations: List[Dict[str, Any]] = Field(..., description="Top searched locations")
+    alerts_count: int = Field(..., description="Active alerts count")
+    last_refresh: str = Field(..., description="Last data refresh timestamp")
+    system_uptime: str = Field(..., description="System uptime")
+    recent_errors: List[str] = Field(..., description="Recent error messages")
+
+
+class SystemHealth(BaseModel):
+    """System health status."""
+    status: str
+    storage_writable: bool
+    cache_operational: bool
+    sessions_operational: bool
+    api_reachable: bool
+    timestamp: str
+
+
+def check_admin(user) -> bool:
+    """
+    Check if user has admin privileges.
+    
+    Admin access is determined ONLY by the ADMIN_EMAILS configuration.
+    Set ADMIN_EMAILS environment variable with comma-separated admin emails.
+    """
+    return settings.is_admin(user.email)
+
+
+async def require_admin(user = Depends(require_auth)):
+    """Dependency to require admin access."""
+    if not check_admin(user):
+        raise HTTPException(
+            status_code=403,
+            detail="Admin access required"
+        )
+    return user
+
+
+@router.get(
+    "/api/stats",
+    response_model=DashboardStats,
+    summary="Get dashboard statistics",
+    description="Get aggregated statistics for the admin dashboard."
+)
+async def get_dashboard_stats(
+    request: Request,
+    user = Depends(require_admin)
+):
+    """Get dashboard statistics."""
+    storage = get_storage()
+    cache = get_cache()
+    metrics = get_metrics()
+    
+    # Get storage stats
+    storage_stats = storage.get_stats()
+    
+    # Get cache stats
+    cache_stats = cache.stats()
+    
+    # Get metrics
+    metrics_data = metrics.get_all()
+    
+    # Calculate cache hit rate
+    total_cache_requests = cache_stats["hits"] + cache_stats["misses"]
+    hit_rate = (cache_stats["hits"] / total_cache_requests * 100) if total_cache_requests > 0 else 0
+    
+    # Get top searched locations (mock data for now)
+    top_locations = [
+        {"name": "New York", "lat": 40.71, "lon": -74.01, "searches": 150},
+        {"name": "London", "lat": 51.51, "lon": -0.13, "searches": 120},
+        {"name": "Tokyo", "lat": 35.68, "lon": 139.65, "searches": 95},
+        {"name": "Paris", "lat": 48.86, "lon": 2.35, "searches": 80},
+        {"name": "Mumbai", "lat": 19.08, "lon": 72.88, "searches": 75}
+    ]
+    
+    return DashboardStats(
+        total_users=storage_stats["users_count"],
+        active_sessions=storage_stats["sessions_count"],
+        logins_24h=metrics_data.get("logins_24h", 0),
+        cache_hit_rate=round(hit_rate, 2),
+        cache_hits=cache_stats["hits"],
+        cache_misses=cache_stats["misses"],
+        cache_size=cache_stats["size"],
+        top_locations=top_locations,
+        alerts_count=metrics_data.get("active_alerts", 0),
+        last_refresh=datetime.now(timezone.utc).isoformat(),
+        system_uptime=metrics_data.get("uptime", "Unknown"),
+        recent_errors=[]
+    )
+
+
+@router.get(
+    "/api/health",
+    response_model=SystemHealth,
+    summary="Get system health status",
+    description="Check the health of all system components."
+)
+async def get_system_health(
+    request: Request,
+    user = Depends(require_admin)
+):
+    """Get detailed system health status."""
+    storage = get_storage()
+    cache = get_cache()
+    
+    # Check storage
+    storage_ok = storage.is_writable()
+    
+    # Check cache
+    try:
+        cache.set("health_check", "ok", ttl=10)
+        cache_ok = cache.get("health_check") == "ok"
+    except Exception:
+        cache_ok = False
+    
+    # Check API connectivity
+    api_ok = True
+    try:
+        import requests
+        response = requests.get(
+            f"{settings.OPEN_METEO_API_URL}?latitude=0&longitude=0&current=temperature_2m",
+            timeout=5
+        )
+        api_ok = response.status_code == 200
+    except Exception:
+        api_ok = False
+    
+    overall_status = "healthy" if all([storage_ok, cache_ok, api_ok]) else "degraded"
+    
+    return SystemHealth(
+        status=overall_status,
+        storage_writable=storage_ok,
+        cache_operational=cache_ok,
+        sessions_operational=True,
+        api_reachable=api_ok,
+        timestamp=datetime.now(timezone.utc).isoformat()
+    )
+
+
+@router.get(
+    "/api/metrics",
+    summary="Get detailed metrics",
+    description="Get detailed application metrics."
+)
+async def get_detailed_metrics(
+    request: Request,
+    user = Depends(require_admin)
+):
+    """Get detailed application metrics."""
+    metrics = get_metrics()
+    cache = get_cache()
+    storage = get_storage()
+    
+    return {
+        "counters": metrics.get_all(),
+        "cache": cache.stats(),
+        "storage": storage.get_stats(),
+        "timestamp": datetime.now(timezone.utc).isoformat()
+    }
+
+
+@router.post(
+    "/api/cache/clear",
+    summary="Clear application cache",
+    description="Clear all cached data. Use with caution."
+)
+async def clear_cache(
+    request: Request,
+    user = Depends(require_admin)
+):
+    """Clear the application cache."""
+    cache = get_cache()
+    cache.clear()
+    
+    logger.warning(f"Cache cleared by admin: {user.username}")
+    
+    return {
+        "message": "Cache cleared successfully",
+        "timestamp": datetime.now(timezone.utc).isoformat()
+    }
+
+
+@router.get(
+    "/dashboard",
+    response_class=HTMLResponse,
+    summary="Admin dashboard page",
+    description="Render the admin dashboard HTML page."
+)
+async def admin_dashboard(
+    request: Request,
+    user = Depends(require_admin)
+):
+    """Render the admin dashboard."""
+    html_content = """
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>IntelliWeather Admin Dashboard</title>
+        <style>
+            * { margin: 0; padding: 0; box-sizing: border-box; }
+            body {
+                font-family: 'Segoe UI', system-ui, sans-serif;
+                background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+                min-height: 100vh;
+                color: #fff;
+            }
+            .header {
+                background: rgba(255,255,255,0.1);
+                backdrop-filter: blur(10px);
+                padding: 1rem 2rem;
+                display: flex;
+                justify-content: space-between;
+                align-items: center;
+            }
+            .header h1 { font-size: 1.5rem; color: #d4af37; }
+            .container { max-width: 1400px; margin: 0 auto; padding: 2rem; }
+            .stats-grid {
+                display: grid;
+                grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+                gap: 1.5rem;
+                margin-bottom: 2rem;
+            }
+            .stat-card {
+                background: rgba(255,255,255,0.1);
+                backdrop-filter: blur(10px);
+                border-radius: 12px;
+                padding: 1.5rem;
+                border: 1px solid rgba(255,255,255,0.1);
+            }
+            .stat-card h3 { color: #888; font-size: 0.9rem; margin-bottom: 0.5rem; }
+            .stat-card .value { font-size: 2rem; font-weight: bold; color: #d4af37; }
+            .section { margin-bottom: 2rem; }
+            .section h2 { margin-bottom: 1rem; color: #d4af37; }
+            .table {
+                width: 100%;
+                background: rgba(255,255,255,0.1);
+                border-radius: 12px;
+                overflow: hidden;
+            }
+            .table th, .table td { padding: 1rem; text-align: left; }
+            .table th { background: rgba(0,0,0,0.3); }
+            .table tr:hover { background: rgba(255,255,255,0.05); }
+            .health-badge {
+                display: inline-block;
+                padding: 0.25rem 0.75rem;
+                border-radius: 20px;
+                font-size: 0.8rem;
+            }
+            .health-badge.healthy { background: #10b981; }
+            .health-badge.degraded { background: #f59e0b; }
+            .btn {
+                background: #d4af37;
+                color: #000;
+                border: none;
+                padding: 0.75rem 1.5rem;
+                border-radius: 8px;
+                cursor: pointer;
+                font-weight: 600;
+            }
+            .btn:hover { background: #b8960c; }
+            #loading { text-align: center; padding: 2rem; }
+        </style>
+    </head>
+    <body>
+        <div class="header">
+            <h1>👑 IntelliWeather Admin</h1>
+            <span id="user-info">Loading...</span>
+        </div>
+        
+        <div class="container">
+            <div id="loading">Loading dashboard data...</div>
+            
+            <div id="dashboard" style="display: none;">
+                <div class="stats-grid">
+                    <div class="stat-card">
+                        <h3>Total Users</h3>
+                        <div class="value" id="total-users">-</div>
+                    </div>
+                    <div class="stat-card">
+                        <h3>Active Sessions</h3>
+                        <div class="value" id="active-sessions">-</div>
+                    </div>
+                    <div class="stat-card">
+                        <h3>Cache Hit Rate</h3>
+                        <div class="value" id="cache-hit-rate">-</div>
+                    </div>
+                    <div class="stat-card">
+                        <h3>Cache Size</h3>
+                        <div class="value" id="cache-size">-</div>
+                    </div>
+                </div>
+                
+                <div class="section">
+                    <h2>System Health</h2>
+                    <div id="health-status">Loading...</div>
+                </div>
+                
+                <div class="section">
+                    <h2>Top Searched Locations</h2>
+                    <table class="table">
+                        <thead>
+                            <tr>
+                                <th>Location</th>
+                                <th>Coordinates</th>
+                                <th>Searches</th>
+                            </tr>
+                        </thead>
+                        <tbody id="top-locations">
+                        </tbody>
+                    </table>
+                </div>
+                
+                <div class="section">
+                    <h2>Actions</h2>
+                    <button class="btn" onclick="clearCache()">Clear Cache</button>
+                    <button class="btn" onclick="refreshData()">Refresh Data</button>
+                </div>
+            </div>
+        </div>
+        
+        <script>
+            async function loadDashboard() {
+                try {
+                    const [statsRes, healthRes] = await Promise.all([
+                        fetch('/admin/api/stats'),
+                        fetch('/admin/api/health')
+                    ]);
+                    
+                    if (!statsRes.ok || !healthRes.ok) {
+                        throw new Error('Failed to load data');
+                    }
+                    
+                    const stats = await statsRes.json();
+                    const health = await healthRes.json();
+                    
+                    document.getElementById('loading').style.display = 'none';
+                    document.getElementById('dashboard').style.display = 'block';
+                    
+                    document.getElementById('total-users').textContent = stats.total_users;
+                    document.getElementById('active-sessions').textContent = stats.active_sessions;
+                    document.getElementById('cache-hit-rate').textContent = stats.cache_hit_rate + '%';
+                    document.getElementById('cache-size').textContent = stats.cache_size;
+                    
+                    const healthHtml = `
+                        <span class="health-badge ${health.status}">${health.status.toUpperCase()}</span>
+                        <ul style="margin-top: 1rem; margin-left: 1rem;">
+                            <li>Storage: ${health.storage_writable ? '✅' : '❌'}</li>
+                            <li>Cache: ${health.cache_operational ? '✅' : '❌'}</li>
+                            <li>API: ${health.api_reachable ? '✅' : '❌'}</li>
+                        </ul>
+                    `;
+                    document.getElementById('health-status').innerHTML = healthHtml;
+                    
+                    const locationsHtml = stats.top_locations.map(loc => `
+                        <tr>
+                            <td>${loc.name}</td>
+                            <td>${loc.lat}, ${loc.lon}</td>
+                            <td>${loc.searches}</td>
+                        </tr>
+                    `).join('');
+                    document.getElementById('top-locations').innerHTML = locationsHtml;
+                    
+                } catch (error) {
+                    document.getElementById('loading').textContent = 'Error loading dashboard: ' + error.message;
+                }
+            }
+            
+            async function clearCache() {
+                if (!confirm('Are you sure you want to clear the cache?')) return;
+                try {
+                    const res = await fetch('/admin/api/cache/clear', { method: 'POST' });
+                    if (res.ok) {
+                        alert('Cache cleared successfully');
+                        refreshData();
+                    }
+                } catch (error) {
+                    alert('Error: ' + error.message);
+                }
+            }
+            
+            function refreshData() {
+                loadDashboard();
+            }
+            
+            loadDashboard();
+        </script>
+    </body>
+    </html>
+    """
+    
+    return HTMLResponse(content=html_content)
diff --git a/routes/alerts.py b/routes/alerts.py
new file mode 100644
index 0000000..6dfd0a2
--- /dev/null
+++ b/routes/alerts.py
@@ -0,0 +1,284 @@
+"""
+Weather Alerts Routes
+
+Provides weather alerts and warnings for locations.
+"""
+
+import uuid
+from datetime import datetime, timezone
+from typing import List, Optional
+
+import requests
+from fastapi import APIRouter, HTTPException, Query, Request, Depends
+
+from config import settings
+from logging_config import get_logger
+from cache import get_cache
+from metrics import get_metrics
+from session_middleware import require_auth
+from storage import get_storage
+from schemas.alerts import (
+    WeatherAlert,
+    AlertsResponse,
+    AlertSeverity,
+    AlertsRefreshResponse
+)
+
+logger = get_logger(__name__)
+
+router = APIRouter(
+    prefix="/alerts",
+    tags=["Weather Alerts"],
+    responses={
+        400: {"description": "Bad Request"},
+        429: {"description": "Rate Limited"},
+        503: {"description": "Alerts Service Unavailable"}
+    }
+)
+
+
+def _get_weather_alerts(lat: float, lon: float) -> List[WeatherAlert]:
+    """
+    Fetch weather alerts for a location.
+    
+    CURRENT IMPLEMENTATION:
+    This generates simulated alerts based on current weather conditions
+    since Open-Meteo doesn't have a dedicated alerts API.
+    
+    ALERT GENERATION THRESHOLDS:
+    - Thunderstorm: weather_code in [95, 96, 99]
+      - Code 99 (severe thunderstorm with hail) = SEVERE severity
+      - Codes 95, 96 = MODERATE severity
+    
+    - High Wind: wind_speed > 60 km/h
+      - wind_speed > 90 km/h = SEVERE severity
+      - wind_speed > 60 km/h = MODERATE severity
+    
+    - Heavy Precipitation: precipitation > 10 mm/hour
+      - Always MODERATE severity
+    
+    - Winter Weather: weather_code in [71, 73, 75, 77, 85, 86]
+      - Codes 75, 86 (heavy snow) = MODERATE severity
+      - Other codes = MINOR severity
+    
+    FOR PRODUCTION USE:
+    Integrate with real alert sources:
+    - NWS API (US): https://www.weather.gov/documentation/services-web-api
+    - MeteoAlarm (Europe): https://meteoalarm.org/
+    - Environment Canada Weather Alerts
+    - Japan Meteorological Agency
+    
+    These provide official government-issued warnings with:
+    - Accurate timing (start/end)
+    - Affected geographic areas
+    - Official severity classifications
+    - Detailed instructions
+    """
+    try:
+        # Fetch current weather to generate condition-based alerts
+        params = {
+            "latitude": lat,
+            "longitude": lon,
+            "current": "weather_code,temperature_2m,wind_speed_10m,precipitation",
+            "timezone": "auto"
+        }
+        
+        response = requests.get(
+            settings.OPEN_METEO_API_URL,
+            params=params,
+            timeout=10
+        )
+        
+        if response.status_code != 200:
+            return []
+        
+        data = response.json()
+        current = data.get("current", {})
+        
+        alerts = []
+        weather_code = current.get("weather_code", 0)
+        wind_speed = current.get("wind_speed_10m", 0)
+        precipitation = current.get("precipitation", 0)
+        
+        # Generate alerts based on conditions
+        now = datetime.now(timezone.utc)
+        
+        # Thunderstorm alerts
+        if weather_code in [95, 96, 99]:
+            alerts.append(WeatherAlert(
+                id=f"alert-{uuid.uuid4().hex[:8]}",
+                event="Thunderstorm Warning",
+                headline="Thunderstorm activity detected in your area",
+                description="A thunderstorm is currently affecting this location. Lightning, heavy rain, and gusty winds are possible.",
+                severity=AlertSeverity.SEVERE if weather_code == 99 else AlertSeverity.MODERATE,
+                start=now.isoformat(),
+                end=(now.replace(hour=now.hour + 3)).isoformat(),
+                areas_affected=[f"Area near {lat}, {lon}"],
+                sender="IntelliWeather Alerts",
+                instruction="Seek shelter indoors and stay away from windows."
+            ))
+        
+        # High wind alerts
+        if wind_speed > 60:  # km/h
+            severity = AlertSeverity.SEVERE if wind_speed > 90 else AlertSeverity.MODERATE
+            alerts.append(WeatherAlert(
+                id=f"alert-{uuid.uuid4().hex[:8]}",
+                event="High Wind Warning",
+                headline=f"High winds of {wind_speed:.0f} km/h expected",
+                description=f"Sustained winds of {wind_speed:.0f} km/h are affecting this area. Gusts may be even higher.",
+                severity=severity,
+                start=now.isoformat(),
+                areas_affected=[f"Area near {lat}, {lon}"],
+                sender="IntelliWeather Alerts",
+                instruction="Secure loose outdoor objects. Avoid unnecessary travel."
+            ))
+        
+        # Heavy precipitation alert
+        if precipitation > 10:  # mm/hour
+            alerts.append(WeatherAlert(
+                id=f"alert-{uuid.uuid4().hex[:8]}",
+                event="Heavy Precipitation Warning",
+                headline="Heavy precipitation in progress",
+                description=f"Precipitation rate of {precipitation:.1f} mm/hour. Flash flooding possible in low-lying areas.",
+                severity=AlertSeverity.MODERATE,
+                start=now.isoformat(),
+                areas_affected=[f"Area near {lat}, {lon}"],
+                sender="IntelliWeather Alerts",
+                instruction="Avoid flooded roads. Turn around, don't drown."
+            ))
+        
+        # Heavy snow/freezing conditions
+        if weather_code in [71, 73, 75, 77, 85, 86]:
+            alerts.append(WeatherAlert(
+                id=f"alert-{uuid.uuid4().hex[:8]}",
+                event="Winter Weather Advisory",
+                headline="Snow or winter weather conditions",
+                description="Winter weather conditions are affecting this area. Roads may be slippery.",
+                severity=AlertSeverity.MODERATE if weather_code in [75, 86] else AlertSeverity.MINOR,
+                start=now.isoformat(),
+                areas_affected=[f"Area near {lat}, {lon}"],
+                sender="IntelliWeather Alerts",
+                instruction="Drive with caution. Allow extra travel time."
+            ))
+        
+        return alerts
+        
+    except Exception as e:
+        logger.error(f"Failed to fetch weather alerts: {e}")
+        return []
+
+
+@router.get(
+    "",
+    response_model=AlertsResponse,
+    summary="Get weather alerts for a location",
+    description="""
+    Get active weather alerts and warnings for a specific location.
+    
+    **Parameters:**
+    - `lat`: Latitude (-90 to 90)
+    - `lon`: Longitude (-180 to 180)
+    
+    **Alert types include:**
+    - Thunderstorm warnings
+    - High wind warnings
+    - Heavy precipitation alerts
+    - Winter weather advisories
+    
+    **Example:**
+    ```
+    curl "https://api.example.com/alerts?lat=40.7128&lon=-74.006"
+    ```
+    """
+)
+async def get_alerts(
+    request: Request,
+    lat: float = Query(..., ge=-90, le=90, description="Latitude"),
+    lon: float = Query(..., ge=-180, le=180, description="Longitude")
+):
+    """Get weather alerts for a location."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("alerts_requests")
+    
+    lat_norm = round(lat, 2)
+    lon_norm = round(lon, 2)
+    
+    cache_key = f"alerts:{lat_norm}:{lon_norm}"
+    cache = get_cache()
+    
+    cached = cache.get(cache_key)
+    if cached:
+        metrics.increment("cache_hits")
+        logger.info(f"ALERTS CACHE HIT for {lat_norm}, {lon_norm}")
+        return AlertsResponse(**cached)
+    
+    metrics.increment("cache_misses")
+    logger.info(f"ALERTS CACHE MISS for {lat_norm}, {lon_norm}")
+    
+    alerts = _get_weather_alerts(lat_norm, lon_norm)
+    
+    result = AlertsResponse(
+        latitude=lat_norm,
+        longitude=lon_norm,
+        location_name=f"Location at {lat_norm}, {lon_norm}",
+        alerts=alerts,
+        count=len(alerts),
+        last_updated=datetime.now(timezone.utc).isoformat(),
+        source="live"
+    )
+    
+    # Cache for 15 minutes
+    cache.set(cache_key, result.model_dump(), ttl=900)
+    
+    return result
+
+
+@router.post(
+    "/refresh",
+    response_model=AlertsRefreshResponse,
+    summary="Manually refresh alerts for popular locations",
+    description="Admin endpoint to trigger immediate alert refresh for popular locations."
+)
+async def refresh_alerts(
+    request: Request,
+    user = Depends(require_auth)
+):
+    """Manually refresh alerts for popular locations."""
+    metrics = get_metrics()
+    metrics.increment("alerts_refresh_requests")
+    
+    locations = settings.parse_popular_locations()
+    cache = get_cache()
+    
+    total_alerts = 0
+    refreshed = 0
+    
+    for loc in locations:
+        lat = loc["lat"]
+        lon = loc["lon"]
+        
+        alerts = _get_weather_alerts(lat, lon)
+        total_alerts += len(alerts)
+        
+        cache_key = f"alerts:{lat}:{lon}"
+        result = AlertsResponse(
+            latitude=lat,
+            longitude=lon,
+            location_name=loc["name"],
+            alerts=alerts,
+            count=len(alerts),
+            last_updated=datetime.now(timezone.utc).isoformat(),
+            source="refresh"
+        )
+        
+        cache.set(cache_key, result.model_dump(), ttl=900)
+        refreshed += 1
+    
+    logger.info(f"Refreshed alerts for {refreshed} locations, found {total_alerts} alerts")
+    
+    return AlertsRefreshResponse(
+        refreshed_locations=refreshed,
+        alerts_found=total_alerts,
+        timestamp=datetime.now(timezone.utc).isoformat()
+    )
diff --git a/routes/apikeys.py b/routes/apikeys.py
new file mode 100644
index 0000000..c601752
--- /dev/null
+++ b/routes/apikeys.py
@@ -0,0 +1,229 @@
+"""
+API Keys Routes
+
+Provides endpoints for API key management.
+"""
+
+from datetime import datetime, timezone
+from typing import List
+
+from fastapi import APIRouter, HTTPException, Query, Request, Depends, Header
+
+from config import settings
+from logging_config import get_logger
+from metrics import get_metrics
+from session_middleware import require_auth, get_session
+from modules.api_keys import get_api_key_manager
+from schemas.api_keys import (
+    APIKeyCreate,
+    APIKeyResponse,
+    APIKeyCreated,
+    APIKeyList
+)
+
+logger = get_logger(__name__)
+
+router = APIRouter(
+    prefix="/apikeys",
+    tags=["API Keys"],
+    responses={
+        401: {"description": "Unauthorized"},
+        403: {"description": "Forbidden"},
+        429: {"description": "Rate Limited"}
+    }
+)
+
+
+@router.post(
+    "",
+    response_model=APIKeyCreated,
+    summary="Create a new API key",
+    description="""
+    Create a new API key for accessing weather endpoints.
+    
+    **Important:** The full API key is only shown once upon creation.
+    Store it securely as it cannot be retrieved later.
+    
+    **Parameters:**
+    - `name`: Descriptive name for the key
+    - `rate_limit`: Custom rate limit (requests/min), optional
+    - `expires_in_days`: Key expiration in days, optional
+    """
+)
+async def create_api_key(
+    request: Request,
+    key_data: APIKeyCreate,
+    user = Depends(require_auth)
+):
+    """Create a new API key."""
+    metrics = get_metrics()
+    metrics.increment("apikey_create_requests")
+    
+    manager = get_api_key_manager()
+    
+    api_key, raw_key = manager.create_key(
+        user_id=user.user_id,
+        name=key_data.name,
+        rate_limit=key_data.rate_limit,
+        expires_in_days=key_data.expires_in_days
+    )
+    
+    logger.info(f"Created API key {api_key.key_id} for user {user.user_id}")
+    
+    return APIKeyCreated(
+        key_id=api_key.key_id,
+        name=api_key.name,
+        api_key=raw_key,
+        created_at=api_key.created_at,
+        expires_at=api_key.expires_at,
+        rate_limit=api_key.rate_limit,
+        warning="Store this key securely. It will not be shown again."
+    )
+
+
+@router.get(
+    "",
+    response_model=APIKeyList,
+    summary="List your API keys",
+    description="Get a list of all API keys associated with your account."
+)
+async def list_api_keys(
+    request: Request,
+    user = Depends(require_auth)
+):
+    """List all API keys for the authenticated user."""
+    metrics = get_metrics()
+    metrics.increment("apikey_list_requests")
+    
+    manager = get_api_key_manager()
+    keys = manager.get_user_keys(user.user_id)
+    
+    key_responses = [
+        APIKeyResponse(
+            key_id=key.key_id,
+            name=key.name,
+            key_prefix=key.key_prefix,
+            created_at=key.created_at,
+            expires_at=key.expires_at,
+            last_used_at=key.last_used_at,
+            rate_limit=key.rate_limit,
+            total_requests=key.total_requests,
+            is_active=key.is_active
+        )
+        for key in keys
+    ]
+    
+    return APIKeyList(
+        keys=key_responses,
+        count=len(key_responses)
+    )
+
+
+@router.delete(
+    "/{key_id}",
+    summary="Revoke an API key",
+    description="Revoke (deactivate) an API key. This action cannot be undone."
+)
+async def revoke_api_key(
+    request: Request,
+    key_id: str,
+    user = Depends(require_auth)
+):
+    """Revoke an API key."""
+    metrics = get_metrics()
+    metrics.increment("apikey_revoke_requests")
+    
+    manager = get_api_key_manager()
+    success = manager.revoke_key(key_id, user.user_id)
+    
+    if not success:
+        raise HTTPException(
+            status_code=404,
+            detail="API key not found or you don't have permission to revoke it"
+        )
+    
+    logger.info(f"Revoked API key {key_id}")
+    
+    return {"message": "API key revoked successfully", "key_id": key_id}
+
+
+@router.get(
+    "/{key_id}",
+    response_model=APIKeyResponse,
+    summary="Get API key details",
+    description="Get details about a specific API key."
+)
+async def get_api_key(
+    request: Request,
+    key_id: str,
+    user = Depends(require_auth)
+):
+    """Get details about an API key."""
+    manager = get_api_key_manager()
+    key = manager.get_key_by_id(key_id)
+    
+    if not key or key.user_id != user.user_id:
+        raise HTTPException(
+            status_code=404,
+            detail="API key not found"
+        )
+    
+    return APIKeyResponse(
+        key_id=key.key_id,
+        name=key.name,
+        key_prefix=key.key_prefix,
+        created_at=key.created_at,
+        expires_at=key.expires_at,
+        last_used_at=key.last_used_at,
+        rate_limit=key.rate_limit,
+        total_requests=key.total_requests,
+        is_active=key.is_active
+    )
+
+
+# Dependency for API key authentication
+async def verify_api_key(
+    x_api_key: str = Header(None, alias="X-API-Key"),
+    apikey: str = Query(None)
+):
+    """
+    Verify API key from header or query parameter.
+    
+    Usage in routes:
+    ```python
+    @router.get("/protected")
+    async def protected_endpoint(api_key = Depends(verify_api_key)):
+        ...
+    ```
+    """
+    key = x_api_key or apikey
+    
+    if not key:
+        raise HTTPException(
+            status_code=401,
+            detail="API key required. Provide via X-API-Key header or apikey query parameter."
+        )
+    
+    manager = get_api_key_manager()
+    api_key = manager.validate_key(key)
+    
+    if not api_key:
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid or expired API key"
+        )
+    
+    # Check rate limit
+    allowed, remaining = manager.check_rate_limit(api_key)
+    
+    if not allowed:
+        raise HTTPException(
+            status_code=429,
+            detail="API key rate limit exceeded",
+            headers={"Retry-After": "60", "X-RateLimit-Remaining": "0"}
+        )
+    
+    # Record usage
+    manager.record_usage(api_key.key_id)
+    
+    return api_key
diff --git a/routes/auth.py b/routes/auth.py
new file mode 100644
index 0000000..2482030
--- /dev/null
+++ b/routes/auth.py
@@ -0,0 +1,364 @@
+"""
+Authentication Routes
+
+This module provides endpoints for:
+- User signup
+- User login
+- User logout
+- Session management
+"""
+
+from datetime import datetime, timezone
+from typing import Optional
+from fastapi import APIRouter, Request, Response, HTTPException, status, Depends
+from pydantic import BaseModel, EmailStr, Field, field_validator
+from passlib.context import CryptContext
+from storage import get_storage, User, SearchHistory
+from session_middleware import (
+    get_session,
+    require_auth,
+    get_session_middleware,
+    SessionData
+)
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# Password hashing context
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# Router
+router = APIRouter(prefix="/auth", tags=["Authentication"])
+
+
+# ==================== PYDANTIC MODELS ====================
+
+class SignupRequest(BaseModel):
+    """Request model for user signup."""
+    username: str = Field(..., min_length=3, max_length=50)
+    email: EmailStr
+    password: str = Field(..., min_length=8, max_length=100)
+    
+    @field_validator("username")
+    @classmethod
+    def validate_username(cls, v: str) -> str:
+        """Validate username format."""
+        if not v.replace("_", "").replace("-", "").isalnum():
+            raise ValueError("Username can only contain letters, numbers, underscores, and hyphens")
+        return v.lower()
+    
+    @field_validator("password")
+    @classmethod
+    def validate_password(cls, v: str) -> str:
+        """Validate password strength."""
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain at least one uppercase letter")
+        if not any(c.islower() for c in v):
+            raise ValueError("Password must contain at least one lowercase letter")
+        if not any(c.isdigit() for c in v):
+            raise ValueError("Password must contain at least one digit")
+        return v
+
+
+class LoginRequest(BaseModel):
+    """Request model for user login."""
+    email: EmailStr
+    password: str
+
+
+class UserResponse(BaseModel):
+    """Response model for user data."""
+    user_id: str
+    username: str
+    email: str
+    created_at: str
+    is_active: bool
+
+
+class AuthResponse(BaseModel):
+    """Response model for authentication."""
+    success: bool
+    message: str
+    user: Optional[UserResponse] = None
+
+
+class SearchHistoryRequest(BaseModel):
+    """Request model for adding search history."""
+    query: str
+    lat: float
+    lon: float
+
+
+class SearchHistoryResponse(BaseModel):
+    """Response model for search history."""
+    id: str
+    query: str
+    lat: float
+    lon: float
+    searched_at: str
+
+
+# ==================== HELPER FUNCTIONS ====================
+
+def hash_password(password: str) -> str:
+    """Hash a password using bcrypt."""
+    return pwd_context.hash(password)
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+# ==================== ENDPOINTS ====================
+
+@router.post("/signup", response_model=AuthResponse, status_code=status.HTTP_201_CREATED)
+async def signup(request: Request, response: Response, data: SignupRequest):
+    """
+    Register a new user account.
+    
+    - **username**: Unique username (3-50 characters)
+    - **email**: Valid email address
+    - **password**: Strong password (8+ characters with mixed case and numbers)
+    """
+    storage = get_storage()
+    
+    # Check if email already exists
+    existing_user = storage.get_user_by_email(data.email)
+    if existing_user:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Email already registered"
+        )
+    
+    # Check if username already exists
+    existing_user = storage.get_user_by_username(data.username)
+    if existing_user:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Username already taken"
+        )
+    
+    # Create user
+    hashed_password = hash_password(data.password)
+    user = User.create(
+        username=data.username,
+        email=data.email,
+        hashed_password=hashed_password
+    )
+    
+    try:
+        storage.create_user(user)
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+    
+    # Create session
+    session_middleware = get_session_middleware()
+    if session_middleware:
+        session_middleware.create_session(user.user_id, response)
+    
+    logger.info(f"User registered: {user.username}")
+    
+    return AuthResponse(
+        success=True,
+        message="Account created successfully",
+        user=UserResponse(
+            user_id=user.user_id,
+            username=user.username,
+            email=user.email,
+            created_at=user.created_at,
+            is_active=user.is_active
+        )
+    )
+
+
+@router.post("/login", response_model=AuthResponse)
+async def login(request: Request, response: Response, data: LoginRequest):
+    """
+    Authenticate a user and create a session.
+    
+    - **email**: Registered email address
+    - **password**: Account password
+    """
+    storage = get_storage()
+    
+    # Find user by email
+    user = storage.get_user_by_email(data.email)
+    
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid email or password"
+        )
+    
+    # Verify password
+    if not verify_password(data.password, user.hashed_password):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid email or password"
+        )
+    
+    # Check if user is active
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Account is deactivated"
+        )
+    
+    # Create session
+    session_middleware = get_session_middleware()
+    if session_middleware:
+        session_middleware.create_session(user.user_id, response)
+    
+    logger.info(f"User logged in: {user.username}")
+    
+    return AuthResponse(
+        success=True,
+        message="Login successful",
+        user=UserResponse(
+            user_id=user.user_id,
+            username=user.username,
+            email=user.email,
+            created_at=user.created_at,
+            is_active=user.is_active
+        )
+    )
+
+
+@router.post("/logout", response_model=AuthResponse)
+async def logout(request: Request, response: Response):
+    """
+    Log out the current user and invalidate the session.
+    """
+    session_data = get_session(request)
+    
+    if not session_data.is_authenticated:
+        return AuthResponse(
+            success=True,
+            message="No active session"
+        )
+    
+    # Destroy session
+    session_middleware = get_session_middleware()
+    if session_middleware and session_data.session:
+        session_middleware.destroy_session(session_data.session.session_id, response)
+    
+    logger.info(f"User logged out: {session_data.user_id}")
+    
+    return AuthResponse(
+        success=True,
+        message="Logged out successfully"
+    )
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_current_user(
+    request: Request,
+    session: SessionData = Depends(require_auth)
+):
+    """
+    Get the current authenticated user's information.
+    
+    Requires authentication.
+    """
+    storage = get_storage()
+    user = storage.get_user_by_id(session.user_id)
+    
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+    
+    return UserResponse(
+        user_id=user.user_id,
+        username=user.username,
+        email=user.email,
+        created_at=user.created_at,
+        is_active=user.is_active
+    )
+
+
+@router.get("/session")
+async def get_session_info(request: Request):
+    """
+    Get current session information.
+    
+    Returns session status and expiration info if authenticated.
+    """
+    session_data = get_session(request)
+    
+    if not session_data.is_authenticated:
+        return {
+            "authenticated": False,
+            "message": "No active session"
+        }
+    
+    return {
+        "authenticated": True,
+        "user_id": session_data.user_id,
+        "session_id": session_data.session.session_id if session_data.session else None,
+        "expires_at": session_data.session.expires_at if session_data.session else None
+    }
+
+
+@router.post("/search-history", response_model=SearchHistoryResponse)
+async def add_search_history(
+    request: Request,
+    data: SearchHistoryRequest,
+    session: SessionData = Depends(require_auth)
+):
+    """
+    Add a search to the user's history.
+    
+    Requires authentication.
+    """
+    storage = get_storage()
+    
+    entry = SearchHistory.create(
+        user_id=session.user_id,
+        query=data.query,
+        lat=data.lat,
+        lon=data.lon
+    )
+    
+    storage.add_search_history(entry)
+    
+    return SearchHistoryResponse(
+        id=entry.id,
+        query=entry.query,
+        lat=entry.lat,
+        lon=entry.lon,
+        searched_at=entry.searched_at
+    )
+
+
+@router.get("/search-history", response_model=list[SearchHistoryResponse])
+async def get_search_history(
+    request: Request,
+    limit: int = 10,
+    session: SessionData = Depends(require_auth)
+):
+    """
+    Get the user's search history.
+    
+    Requires authentication.
+    """
+    storage = get_storage()
+    
+    history = storage.get_user_search_history(session.user_id, limit)
+    
+    return [
+        SearchHistoryResponse(
+            id=entry.id,
+            query=entry.query,
+            lat=entry.lat,
+            lon=entry.lon,
+            searched_at=entry.searched_at
+        )
+        for entry in history
+    ]
diff --git a/routes/downloads.py b/routes/downloads.py
new file mode 100644
index 0000000..a90ab60
--- /dev/null
+++ b/routes/downloads.py
@@ -0,0 +1,222 @@
+"""
+Download Routes - PDF and Excel Report Downloads
+
+Provides endpoints for downloading weather reports in PDF and Excel formats.
+"""
+
+from datetime import datetime, timezone
+from typing import Literal
+
+import requests
+from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi.responses import Response, StreamingResponse
+
+from config import settings
+from logging_config import get_logger
+from cache import get_cache
+from metrics import get_metrics
+from modules.reports import PDFReportGenerator, ExcelReportGenerator
+
+logger = get_logger(__name__)
+
+router = APIRouter(
+    prefix="/weather/download",
+    tags=["Downloads"],
+    responses={
+        400: {"description": "Bad Request"},
+        429: {"description": "Rate Limited"},
+        503: {"description": "Service Unavailable"}
+    }
+)
+
+
+def _fetch_weather_data(lat: float, lon: float, report_range: str, days: int) -> dict:
+    """Fetch weather data for report generation."""
+    lat_norm = round(lat, 2)
+    lon_norm = round(lon, 2)
+    
+    try:
+        if report_range == "hourly":
+            params = {
+                "latitude": lat_norm,
+                "longitude": lon_norm,
+                "hourly": "temperature_2m,relative_humidity_2m,precipitation_probability,wind_speed_10m,weather_code",
+                "forecast_days": min(days, 3),
+                "timezone": "auto"
+            }
+            
+            response = requests.get(
+                settings.OPEN_METEO_API_URL,
+                params=params,
+                timeout=15
+            )
+            
+            if response.status_code != 200:
+                return None
+            
+            data = response.json()
+            hourly = data.get("hourly", {})
+            
+            hourly_list = []
+            times = hourly.get("time", [])
+            for i, time in enumerate(times):
+                hourly_list.append({
+                    "time": time,
+                    "temperature": hourly.get("temperature_2m", [0])[i],
+                    "humidity": hourly.get("relative_humidity_2m", [0])[i],
+                    "precipitation_probability": hourly.get("precipitation_probability", [0])[i],
+                    "wind_speed": hourly.get("wind_speed_10m", [0])[i],
+                    "weather_code": hourly.get("weather_code", [0])[i]
+                })
+            
+            return {
+                "latitude": data.get("latitude"),
+                "longitude": data.get("longitude"),
+                "timezone": data.get("timezone"),
+                "hourly": hourly_list
+            }
+        
+        else:  # daily
+            params = {
+                "latitude": lat_norm,
+                "longitude": lon_norm,
+                "daily": "weather_code,temperature_2m_max,temperature_2m_min,precipitation_sum,precipitation_probability_max,sunrise,sunset",
+                "forecast_days": min(days, 14),
+                "timezone": "auto"
+            }
+            
+            response = requests.get(
+                settings.OPEN_METEO_API_URL,
+                params=params,
+                timeout=15
+            )
+            
+            if response.status_code != 200:
+                return None
+            
+            data = response.json()
+            daily = data.get("daily", {})
+            
+            daily_list = []
+            dates = daily.get("time", [])
+            for i, date in enumerate(dates):
+                daily_list.append({
+                    "date": date,
+                    "temperature_max": daily.get("temperature_2m_max", [0])[i],
+                    "temperature_min": daily.get("temperature_2m_min", [0])[i],
+                    "precipitation_sum": daily.get("precipitation_sum", [0])[i],
+                    "precipitation_probability_max": daily.get("precipitation_probability_max", [0])[i],
+                    "weather_code": daily.get("weather_code", [0])[i],
+                    "sunrise": daily.get("sunrise", [""])[i],
+                    "sunset": daily.get("sunset", [""])[i]
+                })
+            
+            return {
+                "latitude": data.get("latitude"),
+                "longitude": data.get("longitude"),
+                "timezone": data.get("timezone"),
+                "daily": daily_list
+            }
+    
+    except Exception as e:
+        logger.error(f"Failed to fetch weather data for report: {e}")
+        return None
+
+
+@router.get(
+    "",
+    summary="Download weather report",
+    description="""
+    Download weather data as PDF or Excel report.
+    
+    **Parameters:**
+    - `lat`: Latitude (-90 to 90)
+    - `lon`: Longitude (-180 to 180)
+    - `type`: Report format (pdf or excel)
+    - `range`: Data range (hourly or daily)
+    - `days`: Number of days (1-14)
+    
+    **Example:**
+    ```
+    curl "https://api.example.com/weather/download?lat=40.7128&lon=-74.006&type=pdf&range=daily&days=7" -o report.pdf
+    ```
+    
+    **PDF Report includes:**
+    - Formatted weather tables
+    - Simple temperature charts
+    - Location metadata
+    
+    **Excel Report includes:**
+    - Weather data sheet with styling
+    - Metadata sheet
+    - Column headers and formatting
+    """
+)
+async def download_report(
+    request: Request,
+    lat: float = Query(..., ge=-90, le=90, description="Latitude"),
+    lon: float = Query(..., ge=-180, le=180, description="Longitude"),
+    type: Literal["pdf", "excel"] = Query("pdf", description="Report format"),
+    range: Literal["hourly", "daily"] = Query("daily", description="Data range"),
+    days: int = Query(7, ge=1, le=14, description="Number of days")
+):
+    """Download weather report as PDF or Excel."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("download_requests")
+    
+    lat_norm = round(lat, 2)
+    lon_norm = round(lon, 2)
+    
+    # Check cache for generated report
+    cache_key = f"report:{type}:{range}:{lat_norm}:{lon_norm}:{days}"
+    cache = get_cache()
+    
+    cached = cache.get(cache_key)
+    if cached:
+        metrics.increment("cache_hits")
+        logger.info(f"REPORT CACHE HIT for {lat_norm}, {lon_norm}")
+        report_bytes = cached["data"]
+        content_type = cached["content_type"]
+        filename = cached["filename"]
+    else:
+        metrics.increment("cache_misses")
+        logger.info(f"REPORT CACHE MISS for {lat_norm}, {lon_norm}")
+        
+        # Fetch weather data
+        weather_data = _fetch_weather_data(lat_norm, lon_norm, range, days)
+        
+        if not weather_data:
+            raise HTTPException(
+                status_code=503,
+                detail="Failed to fetch weather data for report"
+            )
+        
+        location = f"Location ({lat_norm}, {lon_norm})"
+        
+        # Generate report
+        if type == "pdf":
+            generator = PDFReportGenerator()
+            report_bytes = generator.generate(location, weather_data, range)
+            content_type = "application/pdf"
+            filename = f"weather_report_{lat_norm}_{lon_norm}_{range}.pdf"
+        else:
+            generator = ExcelReportGenerator()
+            report_bytes = generator.generate(location, weather_data, range)
+            content_type = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+            filename = f"weather_report_{lat_norm}_{lon_norm}_{range}.xlsx"
+        
+        # Cache the generated report
+        cache.set(cache_key, {
+            "data": report_bytes,
+            "content_type": content_type,
+            "filename": filename
+        }, ttl=settings.REPORTS_CACHE_TTL_SECONDS)
+    
+    return Response(
+        content=report_bytes,
+        media_type=content_type,
+        headers={
+            "Content-Disposition": f"attachment; filename={filename}"
+        }
+    )
diff --git a/routes/geocode.py b/routes/geocode.py
new file mode 100644
index 0000000..417d8e7
--- /dev/null
+++ b/routes/geocode.py
@@ -0,0 +1,135 @@
+"""
+Geocoding Routes
+
+Provides geocoding and reverse geocoding endpoints.
+"""
+
+from fastapi import APIRouter, HTTPException, Query, Request
+
+from config import settings
+from logging_config import get_logger
+from metrics import get_metrics
+from modules.geocode import get_geocoding_service
+from schemas.geocode import (
+    GeocodeSearchResponse,
+    ReverseGeocodeResponse,
+    GeoLocation
+)
+
+logger = get_logger(__name__)
+
+router = APIRouter(
+    prefix="/geocode",
+    tags=["Geocoding"],
+    responses={
+        400: {"description": "Bad Request"},
+        429: {"description": "Rate Limited"},
+        503: {"description": "Geocoding Service Unavailable"}
+    }
+)
+
+
+@router.get(
+    "/search",
+    response_model=GeocodeSearchResponse,
+    summary="Search for locations by name",
+    description="""
+    Search for locations by city name, place name, or other geographic identifiers.
+    
+    **Parameters:**
+    - `q`: Search query (city name, etc.)
+    - `limit`: Maximum results (1-20, default 5)
+    - `lang`: Language for results (optional)
+    
+    **Example:**
+    ```
+    curl "https://api.example.com/geocode/search?q=New York&limit=5"
+    ```
+    
+    **Response includes:**
+    - Location name
+    - Coordinates (latitude, longitude)
+    - Country and administrative regions
+    - Timezone
+    - Population (when available)
+    """
+)
+async def search_locations(
+    request: Request,
+    q: str = Query(..., min_length=1, max_length=200, description="Search query"),
+    limit: int = Query(5, ge=1, le=20, description="Maximum results"),
+    lang: str = Query(None, description="Language code (en, hi, ar, etc.)")
+):
+    """Search for locations by name."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("geocode_search_requests")
+    
+    geocoding = get_geocoding_service()
+    result = geocoding.search(q, limit, lang)
+    
+    if result.get("source") == "error":
+        raise HTTPException(
+            status_code=503,
+            detail="Geocoding service temporarily unavailable"
+        )
+    
+    # Convert to response model
+    locations = [
+        GeoLocation(**loc) for loc in result.get("results", [])
+    ]
+    
+    return GeocodeSearchResponse(
+        results=locations,
+        query=result.get("query", q),
+        count=len(locations),
+        source=result.get("source", "live")
+    )
+
+
+@router.get(
+    "/reverse",
+    response_model=ReverseGeocodeResponse,
+    summary="Reverse geocode coordinates",
+    description="""
+    Get location information for a set of coordinates.
+    
+    **Parameters:**
+    - `lat`: Latitude (-90 to 90)
+    - `lon`: Longitude (-180 to 180)
+    
+    **Example:**
+    ```
+    curl "https://api.example.com/geocode/reverse?lat=40.7128&lon=-74.006"
+    ```
+    """
+)
+async def reverse_geocode(
+    request: Request,
+    lat: float = Query(..., ge=-90, le=90, description="Latitude"),
+    lon: float = Query(..., ge=-180, le=180, description="Longitude")
+):
+    """Reverse geocode coordinates to location information."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("geocode_reverse_requests")
+    
+    geocoding = get_geocoding_service()
+    result = geocoding.reverse(lat, lon)
+    
+    if result.get("source") == "error":
+        raise HTTPException(
+            status_code=503,
+            detail="Geocoding service temporarily unavailable"
+        )
+    
+    location = None
+    if result.get("location"):
+        location = GeoLocation(**result["location"])
+    
+    return ReverseGeocodeResponse(
+        location=location,
+        latitude=result.get("latitude", lat),
+        longitude=result.get("longitude", lon),
+        source=result.get("source", "live")
+    )
diff --git a/routes/growth.py b/routes/growth.py
new file mode 100644
index 0000000..a16ceda
--- /dev/null
+++ b/routes/growth.py
@@ -0,0 +1,413 @@
+"""
+IntelliWeather - Growth Routes
+
+Endpoints for analytics, referrals, and shareable links.
+"""
+
+from fastapi import APIRouter, Request, Response, HTTPException, Depends
+from typing import Optional, List
+from pydantic import BaseModel
+
+from modules.growth import (
+    get_analytics_service,
+    get_referral_service,
+    get_shareable_link_service,
+    get_social_preview_service,
+    EventType,
+    SocialPreviewData
+)
+from session_middleware import require_auth
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+router = APIRouter(prefix="/growth", tags=["Growth"])
+
+
+# ==================== SCHEMAS ====================
+
+class TrackEventRequest(BaseModel):
+    """Track event request body"""
+    event_type: str
+    properties: dict = {}
+
+
+class CreateShareLinkRequest(BaseModel):
+    """Create shareable link request"""
+    lat: float
+    lon: float
+    location_name: str
+    expires_hours: int = 168  # 1 week
+
+
+class ReferralCodeResponse(BaseModel):
+    """Referral code response"""
+    code: str
+    uses: int
+    max_uses: Optional[int]
+    expires_at: Optional[str]
+    referral_url: str
+
+
+class ShareableLinkResponse(BaseModel):
+    """Shareable link response"""
+    token: str
+    url: str
+    location_name: str
+    expires_at: str
+    view_count: int
+
+
+# ==================== ANALYTICS ENDPOINTS ====================
+
+@router.post("/analytics/track")
+async def track_event(
+    request: Request,
+    body: TrackEventRequest
+):
+    """
+    Track an analytics event.
+    
+    Used by frontend to track user interactions.
+    """
+    if not settings.FEATURE_ANALYTICS:
+        raise HTTPException(status_code=503, detail="Analytics is disabled")
+    
+    try:
+        event_type = EventType(body.event_type)
+    except ValueError:
+        raise HTTPException(status_code=400, detail=f"Invalid event type: {body.event_type}")
+    
+    analytics = get_analytics_service()
+    
+    # Get session info if available
+    session = getattr(request.state, "session", None)
+    user_id = session.user_id if session and session.is_authenticated else None
+    session_id = session.session_id if session else None
+    
+    event = analytics.track(
+        event_type=event_type,
+        user_id=user_id,
+        session_id=session_id,
+        **body.properties
+    )
+    
+    return {"status": "tracked", "event_id": event.id}
+
+
+@router.get("/analytics/stats")
+async def get_analytics_stats(request: Request):
+    """
+    Get analytics statistics.
+    
+    Returns event counts and top searches.
+    """
+    if not settings.FEATURE_ANALYTICS:
+        raise HTTPException(status_code=503, detail="Analytics is disabled")
+    
+    analytics = get_analytics_service()
+    return analytics.get_stats()
+
+
+@router.get("/analytics/events")
+async def get_recent_events(
+    request: Request,
+    event_type: Optional[str] = None,
+    limit: int = 50
+):
+    """
+    Get recent analytics events.
+    
+    Optionally filter by event type.
+    """
+    if not settings.FEATURE_ANALYTICS:
+        raise HTTPException(status_code=503, detail="Analytics is disabled")
+    
+    analytics = get_analytics_service()
+    
+    filter_type = None
+    if event_type:
+        try:
+            filter_type = EventType(event_type)
+        except ValueError:
+            pass
+    
+    events = analytics.get_recent_events(event_type=filter_type, limit=limit)
+    return {"events": events, "count": len(events)}
+
+
+# ==================== REFERRAL ENDPOINTS ====================
+
+@router.get("/referral/code")
+async def get_referral_code(
+    request: Request,
+    user_id: str = Depends(require_auth)
+):
+    """
+    Get or create a referral code for the current user.
+    """
+    if not settings.FEATURE_REFERRALS:
+        raise HTTPException(status_code=503, detail="Referrals are disabled")
+    
+    referrals = get_referral_service()
+    
+    # Check if user already has a code
+    existing = referrals.get_user_code(user_id)
+    if existing:
+        code = existing
+    else:
+        code = referrals.generate_code(user_id)
+    
+    base_url = str(request.base_url).rstrip("/")
+    referral_url = f"{base_url}/signup?ref={code.code}"
+    
+    return ReferralCodeResponse(
+        code=code.code,
+        uses=code.uses,
+        max_uses=code.max_uses,
+        expires_at=code.expires_at.isoformat() if code.expires_at else None,
+        referral_url=referral_url
+    )
+
+
+@router.get("/referral/validate/{code}")
+async def validate_referral_code(code: str):
+    """
+    Validate a referral code.
+    """
+    if not settings.FEATURE_REFERRALS:
+        raise HTTPException(status_code=503, detail="Referrals are disabled")
+    
+    referrals = get_referral_service()
+    referral_code = referrals.validate_code(code)
+    
+    if not referral_code:
+        raise HTTPException(status_code=404, detail="Invalid or expired referral code")
+    
+    return {
+        "valid": True,
+        "code": referral_code.code,
+        "remaining_uses": (referral_code.max_uses - referral_code.uses) if referral_code.max_uses else None
+    }
+
+
+@router.post("/referral/use/{code}")
+async def use_referral_code(
+    code: str,
+    request: Request,
+    user_id: str = Depends(require_auth)
+):
+    """
+    Use a referral code (called during signup).
+    """
+    if not settings.FEATURE_REFERRALS:
+        raise HTTPException(status_code=503, detail="Referrals are disabled")
+    
+    referrals = get_referral_service()
+    referral = referrals.use_code(code, user_id)
+    
+    if not referral:
+        raise HTTPException(status_code=400, detail="Could not use referral code")
+    
+    return {
+        "status": "success",
+        "referral_id": referral.id,
+        "referrer_id": referral.referrer_id
+    }
+
+
+@router.get("/referral/stats")
+async def get_referral_stats(
+    request: Request,
+    user_id: str = Depends(require_auth)
+):
+    """
+    Get referral statistics for the current user.
+    """
+    if not settings.FEATURE_REFERRALS:
+        raise HTTPException(status_code=503, detail="Referrals are disabled")
+    
+    referrals = get_referral_service()
+    
+    user_code = referrals.get_user_code(user_id)
+    user_referrals = referrals.get_user_referrals(user_id)
+    
+    return {
+        "code": user_code.code if user_code else None,
+        "total_referrals": len(user_referrals),
+        "referrals": [
+            {
+                "referred_id": r.referred_id,
+                "created_at": r.created_at.isoformat(),
+                "status": r.status
+            }
+            for r in user_referrals
+        ]
+    }
+
+
+# ==================== SHAREABLE LINKS ENDPOINTS ====================
+
+@router.post("/share/create")
+async def create_share_link(
+    body: CreateShareLinkRequest,
+    request: Request
+):
+    """
+    Create a shareable forecast link.
+    """
+    if not settings.FEATURE_SHAREABLE_LINKS:
+        raise HTTPException(status_code=503, detail="Shareable links are disabled")
+    
+    links = get_shareable_link_service()
+    
+    # Get user ID if authenticated
+    session = getattr(request.state, "session", None)
+    user_id = session.user_id if session and session.is_authenticated else None
+    
+    link = links.create_link(
+        lat=body.lat,
+        lon=body.lon,
+        location_name=body.location_name,
+        expires_hours=body.expires_hours,
+        created_by=user_id
+    )
+    
+    base_url = str(request.base_url).rstrip("/")
+    
+    return ShareableLinkResponse(
+        token=link.token,
+        url=f"{base_url}/s/{link.token}",
+        location_name=link.location_name,
+        expires_at=link.expires_at.isoformat(),
+        view_count=link.view_count
+    )
+
+
+@router.get("/share/{token}")
+async def get_share_link(token: str, request: Request):
+    """
+    Get shareable link data.
+    """
+    if not settings.FEATURE_SHAREABLE_LINKS:
+        raise HTTPException(status_code=503, detail="Shareable links are disabled")
+    
+    links = get_shareable_link_service()
+    link = links.get_link(token)
+    
+    if not link:
+        raise HTTPException(status_code=404, detail="Link not found or expired")
+    
+    return {
+        "lat": link.lat,
+        "lon": link.lon,
+        "location_name": link.location_name,
+        "created_at": link.created_at.isoformat(),
+        "expires_at": link.expires_at.isoformat(),
+        "view_count": link.view_count
+    }
+
+
+@router.get("/share/my/links")
+async def get_my_share_links(
+    request: Request,
+    user_id: str = Depends(require_auth)
+):
+    """
+    Get all shareable links created by the current user.
+    """
+    if not settings.FEATURE_SHAREABLE_LINKS:
+        raise HTTPException(status_code=503, detail="Shareable links are disabled")
+    
+    links = get_shareable_link_service()
+    user_links = links.get_user_links(user_id)
+    
+    base_url = str(request.base_url).rstrip("/")
+    
+    return {
+        "links": [
+            {
+                "token": l.token,
+                "url": f"{base_url}/s/{l.token}",
+                "location_name": l.location_name,
+                "created_at": l.created_at.isoformat(),
+                "expires_at": l.expires_at.isoformat(),
+                "view_count": l.view_count
+            }
+            for l in user_links
+        ]
+    }
+
+
+# ==================== SOCIAL PREVIEW ENDPOINTS ====================
+
+@router.get("/preview/meta")
+async def get_social_preview_meta(
+    request: Request,
+    location: str,
+    temperature: float,
+    condition: str,
+    icon: str = "🌤️",
+    high: Optional[float] = None,
+    low: Optional[float] = None
+):
+    """
+    Get Open Graph meta tags for social sharing.
+    """
+    if not settings.FEATURE_SOCIAL_PREVIEW:
+        raise HTTPException(status_code=503, detail="Social previews are disabled")
+    
+    preview = get_social_preview_service()
+    
+    data = SocialPreviewData(
+        location=location,
+        temperature=temperature,
+        condition=condition,
+        icon=icon,
+        high=high,
+        low=low
+    )
+    
+    url = str(request.url)
+    tags = preview.generate_meta_tags(data, url)
+    
+    return {
+        "meta_tags": tags,
+        "og_title": data.to_og_title(),
+        "og_description": data.to_og_description()
+    }
+
+
+@router.get("/preview/image")
+async def get_social_preview_image(
+    request: Request,
+    location: str,
+    temperature: float,
+    condition: str,
+    icon: str = "🌤️",
+    high: Optional[float] = None,
+    low: Optional[float] = None
+):
+    """
+    Get HTML for rendering social preview image.
+    
+    Use this with a headless browser (Puppeteer/Playwright) to generate preview images.
+    """
+    if not settings.FEATURE_SOCIAL_PREVIEW:
+        raise HTTPException(status_code=503, detail="Social previews are disabled")
+    
+    preview = get_social_preview_service()
+    
+    data = SocialPreviewData(
+        location=location,
+        temperature=temperature,
+        condition=condition,
+        icon=icon,
+        high=high,
+        low=low
+    )
+    
+    html = preview.generate_preview_html(data)
+    
+    return Response(content=html, media_type="text/html")
diff --git a/routes/i18n.py b/routes/i18n.py
new file mode 100644
index 0000000..4e247cb
--- /dev/null
+++ b/routes/i18n.py
@@ -0,0 +1,129 @@
+"""
+Internationalization (i18n) Routes
+
+Provides endpoints for translation management and language selection.
+"""
+
+from typing import Dict, List
+
+from fastapi import APIRouter, Query, Request
+from pydantic import BaseModel, Field
+
+from config import settings
+from logging_config import get_logger
+from modules.i18n import get_i18n_service
+
+logger = get_logger(__name__)
+
+router = APIRouter(
+    prefix="/i18n",
+    tags=["Internationalization"],
+)
+
+
+class TranslationsResponse(BaseModel):
+    """Response model for translations."""
+    language: str = Field(..., description="Language code")
+    translations: Dict[str, str] = Field(..., description="Translation key-value pairs")
+
+
+class SupportedLanguagesResponse(BaseModel):
+    """Response model for supported languages."""
+    languages: List[str] = Field(..., description="List of supported language codes")
+    default: str = Field(..., description="Default language code")
+
+
+@router.get(
+    "/languages",
+    response_model=SupportedLanguagesResponse,
+    summary="Get supported languages",
+    description="Get a list of all supported language codes."
+)
+async def get_supported_languages(request: Request):
+    """Get list of supported languages."""
+    i18n = get_i18n_service()
+    
+    return SupportedLanguagesResponse(
+        languages=i18n.get_supported_languages(),
+        default=settings.DEFAULT_LANGUAGE
+    )
+
+
+@router.get(
+    "/translations",
+    response_model=TranslationsResponse,
+    summary="Get translations for a language",
+    description="""
+    Get all UI translations for a specific language.
+    
+    **Supported languages:**
+    - en: English (default)
+    - hi: Hindi
+    - ur: Urdu
+    - ar: Arabic
+    - es: Spanish
+    """
+)
+async def get_translations(
+    request: Request,
+    lang: str = Query(None, description="Language code (defaults to en)")
+):
+    """Get translations for a language."""
+    i18n = get_i18n_service()
+    language = lang or settings.DEFAULT_LANGUAGE
+    
+    if language not in i18n.get_supported_languages():
+        language = settings.DEFAULT_LANGUAGE
+    
+    translations = i18n.get_all_translations(language)
+    
+    return TranslationsResponse(
+        language=language,
+        translations=translations
+    )
+
+
+@router.get(
+    "/translate",
+    summary="Translate a single key",
+    description="Translate a single key to the specified language."
+)
+async def translate_key(
+    request: Request,
+    key: str = Query(..., description="Translation key"),
+    lang: str = Query(None, description="Language code")
+):
+    """Translate a single key."""
+    i18n = get_i18n_service()
+    language = lang or settings.DEFAULT_LANGUAGE
+    
+    translation = i18n.translate(key, language)
+    
+    return {
+        "key": key,
+        "language": language,
+        "translation": translation
+    }
+
+
+@router.get(
+    "/weather-description",
+    summary="Get localized weather description",
+    description="Get a human-readable weather description for a WMO weather code."
+)
+async def get_weather_description(
+    request: Request,
+    code: int = Query(..., ge=0, le=99, description="WMO weather code"),
+    lang: str = Query(None, description="Language code")
+):
+    """Get localized weather description for a weather code."""
+    i18n = get_i18n_service()
+    language = lang or settings.DEFAULT_LANGUAGE
+    
+    description = i18n.get_weather_description(code, language)
+    
+    return {
+        "weather_code": code,
+        "language": language,
+        "description": description
+    }
diff --git a/routes/predict.py b/routes/predict.py
new file mode 100644
index 0000000..5dcdd55
--- /dev/null
+++ b/routes/predict.py
@@ -0,0 +1,167 @@
+"""
+Prediction Routes
+
+Provides ML-based weather prediction endpoints.
+"""
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from pydantic import BaseModel, Field
+
+from config import settings
+from logging_config import get_logger
+from metrics import get_metrics
+from modules.prediction import get_prediction_service, PredictionResult
+
+logger = get_logger(__name__)
+
+router = APIRouter(
+    prefix="/predict",
+    tags=["ML Prediction"],
+    responses={
+        400: {"description": "Bad Request"},
+        503: {"description": "Prediction Service Unavailable"}
+    }
+)
+
+
+class PredictionResponse(BaseModel):
+    """Response model for temperature prediction."""
+    predicted_temperature: float = Field(..., description="Predicted temperature in Celsius")
+    confidence_interval_low: float = Field(..., description="Lower bound of confidence interval")
+    confidence_interval_high: float = Field(..., description="Upper bound of confidence interval")
+    model_version: str = Field(..., description="Version of the prediction model")
+    trained_at: str = Field(..., description="When the model was last trained")
+    historical_days_used: int = Field(..., description="Number of historical days used for training")
+    location: str = Field(..., description="Location coordinates")
+    generated_at: str = Field(..., description="When this prediction was generated")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "predicted_temperature": 22.5,
+                "confidence_interval_low": 19.5,
+                "confidence_interval_high": 25.5,
+                "model_version": "1.0.0",
+                "trained_at": "2024-01-15T00:00:00Z",
+                "historical_days_used": 365,
+                "location": "40.71, -74.01",
+                "generated_at": "2024-01-15T12:00:00Z"
+            }
+        }
+
+
+class ModelInfoResponse(BaseModel):
+    """Response model for model information."""
+    version: str
+    trained_at: Optional[str]
+    is_trained: bool
+    feature_names: list
+    model_path: str
+
+
+@router.get(
+    "/nextday",
+    response_model=PredictionResponse,
+    summary="Predict next-day temperature",
+    description="""
+    Get a prediction for tomorrow's mean temperature at a location.
+    
+    **Parameters:**
+    - `lat`: Latitude (-90 to 90)
+    - `lon`: Longitude (-180 to 180)
+    
+    **Model Details:**
+    - Uses linear regression on historical temperature data
+    - Features include: day of year (cyclical), previous temperatures, trend
+    - Confidence interval represents ±3°C uncertainty
+    
+    **Note:** This is a simple demonstration model. For production use,
+    consider more sophisticated approaches.
+    
+    **Example:**
+    ```
+    curl "https://api.example.com/predict/nextday?lat=40.7128&lon=-74.006"
+    ```
+    """
+)
+async def predict_next_day_temperature(
+    request: Request,
+    lat: float = Query(..., ge=-90, le=90, description="Latitude"),
+    lon: float = Query(..., ge=-180, le=180, description="Longitude")
+):
+    """Predict next-day mean temperature for a location."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("prediction_requests")
+    
+    prediction_service = get_prediction_service()
+    
+    result = prediction_service.predict_next_day(lat, lon)
+    
+    if not result:
+        raise HTTPException(
+            status_code=503,
+            detail="Prediction service temporarily unavailable"
+        )
+    
+    return PredictionResponse(
+        predicted_temperature=result.predicted_temperature,
+        confidence_interval_low=result.confidence_interval_low,
+        confidence_interval_high=result.confidence_interval_high,
+        model_version=result.model_version,
+        trained_at=result.trained_at,
+        historical_days_used=result.historical_days_used,
+        location=result.location,
+        generated_at=datetime.now(timezone.utc).isoformat()
+    )
+
+
+@router.get(
+    "/model/info",
+    response_model=ModelInfoResponse,
+    summary="Get prediction model information",
+    description="Get information about the current prediction model."
+)
+async def get_model_info(request: Request):
+    """Get information about the prediction model."""
+    prediction_service = get_prediction_service()
+    info = prediction_service.get_model_info()
+    
+    return ModelInfoResponse(**info)
+
+
+@router.post(
+    "/model/train",
+    summary="Train prediction model",
+    description="""
+    Trigger model training for a specific location.
+    
+    **Note:** Training uses historical data from Open-Meteo and may take a few seconds.
+    """
+)
+async def train_model(
+    request: Request,
+    lat: float = Query(..., ge=-90, le=90, description="Latitude"),
+    lon: float = Query(..., ge=-180, le=180, description="Longitude")
+):
+    """Train the prediction model for a location."""
+    metrics = get_metrics()
+    metrics.increment("model_train_requests")
+    
+    prediction_service = get_prediction_service()
+    success = prediction_service.train_model(lat, lon)
+    
+    if not success:
+        raise HTTPException(
+            status_code=503,
+            detail="Failed to train model. Historical data may be unavailable."
+        )
+    
+    return {
+        "message": "Model trained successfully",
+        "location": f"{lat}, {lon}",
+        "timestamp": datetime.now(timezone.utc).isoformat()
+    }
diff --git a/routes/weather_v2.py b/routes/weather_v2.py
new file mode 100644
index 0000000..943f940
--- /dev/null
+++ b/routes/weather_v2.py
@@ -0,0 +1,546 @@
+"""
+Weather V2 Routes - Phase 2 Enhanced Weather Endpoints
+
+Provides hourly, daily, and historical weather data with CSV/JSON format support.
+"""
+
+import csv
+import io
+from datetime import datetime, timezone, date, timedelta
+from typing import Optional, Literal
+
+import requests
+from fastapi import APIRouter, HTTPException, Query, Request, Response
+from fastapi.responses import StreamingResponse
+
+from config import settings
+from logging_config import get_logger
+from cache import get_cache, generate_weather_cache_key
+from metrics import get_metrics
+from schemas.weather import (
+    WeatherUnits,
+    ResponseFormat,
+    HourlyWeatherResponse,
+    DailyWeatherResponse,
+    HistoricalWeatherResponse,
+    HourlyDataPoint,
+    DailyDataPoint
+)
+
+logger = get_logger(__name__)
+
+router = APIRouter(
+    prefix="/weather",
+    tags=["Weather V2"],
+    responses={
+        400: {"description": "Bad Request"},
+        429: {"description": "Rate Limited"},
+        500: {"description": "Internal Server Error"},
+        503: {"description": "External API Unavailable"}
+    }
+)
+
+
+def normalize_coordinates(lat: float, lon: float) -> tuple:
+    """Normalize coordinates to 2 decimal places."""
+    return round(lat, 2), round(lon, 2)
+
+
+def convert_temperature(temp_c: float, units: WeatherUnits) -> float:
+    """Convert temperature to specified units."""
+    if units == WeatherUnits.IMPERIAL:
+        return round(temp_c * 9 / 5 + 32, 1)
+    return round(temp_c, 1)
+
+
+def convert_wind_speed(speed_kmh: float, units: WeatherUnits) -> float:
+    """Convert wind speed to specified units."""
+    if units == WeatherUnits.IMPERIAL:
+        return round(speed_kmh * 0.621371, 1)  # to mph
+    return round(speed_kmh / 3.6, 1)  # to m/s
+
+
+@router.get(
+    "/hourly",
+    response_model=HourlyWeatherResponse,
+    summary="Get hourly weather forecast",
+    description="""
+    Get hourly weather forecast for a location.
+    
+    **Parameters:**
+    - `lat`: Latitude (-90 to 90)
+    - `lon`: Longitude (-180 to 180)
+    - `hours`: Forecast hours (24, 48, or 72)
+    - `units`: metric (default) or imperial
+    - `format`: json (default) or csv
+    
+    **Response:**
+    Returns hourly forecast data including temperature, humidity, wind, precipitation probability.
+    
+    **Example:**
+    ```
+    curl "https://api.example.com/weather/hourly?lat=40.7128&lon=-74.006&hours=24"
+    ```
+    """
+)
+async def get_hourly_forecast(
+    request: Request,
+    lat: float = Query(..., ge=-90, le=90, description="Latitude"),
+    lon: float = Query(..., ge=-180, le=180, description="Longitude"),
+    hours: Literal[24, 48, 72] = Query(24, description="Forecast hours"),
+    units: WeatherUnits = Query(WeatherUnits.METRIC, description="Unit system"),
+    format: ResponseFormat = Query(ResponseFormat.JSON, description="Response format")
+):
+    """Get hourly weather forecast."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("hourly_v2_requests")
+    
+    lat_norm, lon_norm = normalize_coordinates(lat, lon)
+    cache_key = f"weather:hourly_v2:{lat_norm}:{lon_norm}:{hours}"
+    
+    cache = get_cache()
+    cached = cache.get(cache_key)
+    
+    if cached:
+        metrics.increment("cache_hits")
+        logger.info(f"CACHE HIT for hourly v2 at {lat_norm}, {lon_norm}")
+        data = cached
+        source = "cache"
+    else:
+        metrics.increment("cache_misses")
+        logger.info(f"CACHE MISS for hourly v2 at {lat_norm}, {lon_norm}")
+        
+        # Fetch from Open-Meteo
+        try:
+            params = {
+                "latitude": lat_norm,
+                "longitude": lon_norm,
+                "hourly": "temperature_2m,apparent_temperature,relative_humidity_2m,precipitation_probability,precipitation,wind_speed_10m,wind_direction_10m,cloud_cover,weather_code,uv_index,visibility,pressure_msl",
+                "forecast_days": (hours // 24) + 1,
+                "timezone": "auto"
+            }
+            
+            response = requests.get(
+                settings.OPEN_METEO_API_URL,
+                params=params,
+                timeout=10
+            )
+            
+            if response.status_code != 200:
+                raise HTTPException(
+                    status_code=503,
+                    detail="Weather service temporarily unavailable"
+                )
+            
+            api_data = response.json()
+            hourly = api_data.get("hourly", {})
+            
+            data = {
+                "latitude": api_data.get("latitude"),
+                "longitude": api_data.get("longitude"),
+                "timezone": api_data.get("timezone"),
+                "hourly_raw": hourly
+            }
+            
+            cache.set(cache_key, data, ttl=1800)  # 30 min cache
+            source = "live"
+            
+        except requests.exceptions.Timeout:
+            raise HTTPException(
+                status_code=503,
+                detail="Weather service timeout. Please try again."
+            )
+        except requests.exceptions.RequestException as e:
+            logger.error(f"API request failed: {e}")
+            raise HTTPException(
+                status_code=503,
+                detail="Weather service unavailable"
+            )
+    
+    # Process data
+    hourly_raw = data.get("hourly_raw", {})
+    times = hourly_raw.get("time", [])[:hours]
+    
+    hourly_data = []
+    for i, time in enumerate(times):
+        hourly_data.append(HourlyDataPoint(
+            time=time,
+            temperature=convert_temperature(hourly_raw.get("temperature_2m", [0])[i] or 0, units),
+            feels_like=convert_temperature(hourly_raw.get("apparent_temperature", [0])[i] or 0, units),
+            humidity=hourly_raw.get("relative_humidity_2m", [0])[i],
+            precipitation=hourly_raw.get("precipitation", [0])[i],
+            precipitation_probability=hourly_raw.get("precipitation_probability", [0])[i],
+            wind_speed=convert_wind_speed(hourly_raw.get("wind_speed_10m", [0])[i] or 0, units),
+            wind_direction=hourly_raw.get("wind_direction_10m", [0])[i],
+            cloud_cover=hourly_raw.get("cloud_cover", [0])[i],
+            weather_code=hourly_raw.get("weather_code", [0])[i],
+            uv_index=hourly_raw.get("uv_index", [0])[i],
+            visibility=hourly_raw.get("visibility", [0])[i],
+            pressure=hourly_raw.get("pressure_msl", [0])[i]
+        ))
+    
+    result = HourlyWeatherResponse(
+        latitude=data.get("latitude", lat_norm),
+        longitude=data.get("longitude", lon_norm),
+        timezone=data.get("timezone", "UTC"),
+        units=units,
+        generated_at=datetime.now(timezone.utc).isoformat(),
+        source=source,
+        hourly=hourly_data
+    )
+    
+    # Return CSV if requested
+    if format == ResponseFormat.CSV:
+        return _hourly_to_csv(result)
+    
+    return result
+
+
+@router.get(
+    "/daily",
+    response_model=DailyWeatherResponse,
+    summary="Get daily weather forecast",
+    description="""
+    Get daily weather forecast for a location.
+    
+    **Parameters:**
+    - `lat`: Latitude (-90 to 90)
+    - `lon`: Longitude (-180 to 180)
+    - `days`: Forecast days (7 or 14)
+    - `units`: metric (default) or imperial
+    - `format`: json (default) or csv
+    """
+)
+async def get_daily_forecast(
+    request: Request,
+    lat: float = Query(..., ge=-90, le=90, description="Latitude"),
+    lon: float = Query(..., ge=-180, le=180, description="Longitude"),
+    days: Literal[7, 14] = Query(7, description="Forecast days"),
+    units: WeatherUnits = Query(WeatherUnits.METRIC, description="Unit system"),
+    format: ResponseFormat = Query(ResponseFormat.JSON, description="Response format")
+):
+    """Get daily weather forecast."""
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("daily_v2_requests")
+    
+    lat_norm, lon_norm = normalize_coordinates(lat, lon)
+    cache_key = f"weather:daily_v2:{lat_norm}:{lon_norm}:{days}"
+    
+    cache = get_cache()
+    cached = cache.get(cache_key)
+    
+    if cached:
+        metrics.increment("cache_hits")
+        logger.info(f"CACHE HIT for daily v2 at {lat_norm}, {lon_norm}")
+        data = cached
+        source = "cache"
+    else:
+        metrics.increment("cache_misses")
+        logger.info(f"CACHE MISS for daily v2 at {lat_norm}, {lon_norm}")
+        
+        try:
+            params = {
+                "latitude": lat_norm,
+                "longitude": lon_norm,
+                "daily": "weather_code,temperature_2m_max,temperature_2m_min,precipitation_sum,precipitation_probability_max,wind_speed_10m_max,sunrise,sunset,uv_index_max",
+                "forecast_days": days,
+                "timezone": "auto"
+            }
+            
+            response = requests.get(
+                settings.OPEN_METEO_API_URL,
+                params=params,
+                timeout=10
+            )
+            
+            if response.status_code != 200:
+                raise HTTPException(
+                    status_code=503,
+                    detail="Weather service temporarily unavailable"
+                )
+            
+            api_data = response.json()
+            daily = api_data.get("daily", {})
+            
+            data = {
+                "latitude": api_data.get("latitude"),
+                "longitude": api_data.get("longitude"),
+                "timezone": api_data.get("timezone"),
+                "daily_raw": daily
+            }
+            
+            cache.set(cache_key, data, ttl=3600)  # 1 hour cache
+            source = "live"
+            
+        except requests.exceptions.Timeout:
+            raise HTTPException(
+                status_code=503,
+                detail="Weather service timeout. Please try again."
+            )
+        except requests.exceptions.RequestException as e:
+            logger.error(f"API request failed: {e}")
+            raise HTTPException(
+                status_code=503,
+                detail="Weather service unavailable"
+            )
+    
+    # Process data
+    daily_raw = data.get("daily_raw", {})
+    dates = daily_raw.get("time", [])
+    
+    daily_data = []
+    for i, date_str in enumerate(dates):
+        daily_data.append(DailyDataPoint(
+            date=date_str,
+            temperature_max=convert_temperature(daily_raw.get("temperature_2m_max", [0])[i] or 0, units),
+            temperature_min=convert_temperature(daily_raw.get("temperature_2m_min", [0])[i] or 0, units),
+            precipitation_sum=daily_raw.get("precipitation_sum", [0])[i],
+            precipitation_probability_max=daily_raw.get("precipitation_probability_max", [0])[i],
+            wind_speed_max=convert_wind_speed(daily_raw.get("wind_speed_10m_max", [0])[i] or 0, units),
+            weather_code=daily_raw.get("weather_code", [0])[i],
+            sunrise=daily_raw.get("sunrise", [""])[i],
+            sunset=daily_raw.get("sunset", [""])[i],
+            uv_index_max=daily_raw.get("uv_index_max", [0])[i]
+        ))
+    
+    result = DailyWeatherResponse(
+        latitude=data.get("latitude", lat_norm),
+        longitude=data.get("longitude", lon_norm),
+        timezone=data.get("timezone", "UTC"),
+        units=units,
+        generated_at=datetime.now(timezone.utc).isoformat(),
+        source=source,
+        daily=daily_data
+    )
+    
+    if format == ResponseFormat.CSV:
+        return _daily_to_csv(result)
+    
+    return result
+
+
+@router.get(
+    "/historical",
+    response_model=HistoricalWeatherResponse,
+    summary="Get historical weather data",
+    description="""
+    Get historical weather data for a location.
+    
+    **Parameters:**
+    - `lat`: Latitude (-90 to 90)
+    - `lon`: Longitude (-180 to 180)
+    - `start`: Start date (YYYY-MM-DD)
+    - `end`: End date (YYYY-MM-DD)
+    - `units`: metric (default) or imperial
+    - `format`: json (default) or csv
+    
+    **Constraints:**
+    - Date range cannot exceed 365 days
+    - End date must be after start date
+    """
+)
+async def get_historical_weather(
+    request: Request,
+    lat: float = Query(..., ge=-90, le=90, description="Latitude"),
+    lon: float = Query(..., ge=-180, le=180, description="Longitude"),
+    start: date = Query(..., description="Start date (YYYY-MM-DD)"),
+    end: date = Query(..., description="End date (YYYY-MM-DD)"),
+    units: WeatherUnits = Query(WeatherUnits.METRIC, description="Unit system"),
+    format: ResponseFormat = Query(ResponseFormat.JSON, description="Response format")
+):
+    """Get historical weather data."""
+    # Validate date range
+    if end < start:
+        raise HTTPException(
+            status_code=400,
+            detail="End date must be after start date"
+        )
+    
+    if (end - start).days > 365:
+        raise HTTPException(
+            status_code=400,
+            detail="Date range cannot exceed 365 days"
+        )
+    
+    metrics = get_metrics()
+    metrics.increment("total_requests")
+    metrics.increment("historical_requests")
+    
+    lat_norm, lon_norm = normalize_coordinates(lat, lon)
+    cache_key = f"weather:historical:{lat_norm}:{lon_norm}:{start}:{end}"
+    
+    cache = get_cache()
+    cached = cache.get(cache_key)
+    
+    if cached:
+        metrics.increment("cache_hits")
+        logger.info(f"CACHE HIT for historical at {lat_norm}, {lon_norm}")
+        data = cached
+        source = "cache"
+    else:
+        metrics.increment("cache_misses")
+        logger.info(f"CACHE MISS for historical at {lat_norm}, {lon_norm}")
+        
+        try:
+            params = {
+                "latitude": lat_norm,
+                "longitude": lon_norm,
+                "start_date": start.isoformat(),
+                "end_date": end.isoformat(),
+                "daily": "weather_code,temperature_2m_max,temperature_2m_min,precipitation_sum,wind_speed_10m_max,sunrise,sunset",
+                "timezone": "auto"
+            }
+            
+            response = requests.get(
+                settings.OPEN_METEO_HISTORICAL_URL,
+                params=params,
+                timeout=30
+            )
+            
+            if response.status_code != 200:
+                raise HTTPException(
+                    status_code=503,
+                    detail="Historical weather service temporarily unavailable"
+                )
+            
+            api_data = response.json()
+            daily = api_data.get("daily", {})
+            
+            data = {
+                "latitude": api_data.get("latitude"),
+                "longitude": api_data.get("longitude"),
+                "timezone": api_data.get("timezone"),
+                "daily_raw": daily
+            }
+            
+            cache.set(cache_key, data, ttl=86400)  # 24 hour cache for historical
+            source = "live"
+            
+        except requests.exceptions.Timeout:
+            raise HTTPException(
+                status_code=503,
+                detail="Historical weather service timeout. Please try again."
+            )
+        except requests.exceptions.RequestException as e:
+            logger.error(f"API request failed: {e}")
+            raise HTTPException(
+                status_code=503,
+                detail="Historical weather service unavailable"
+            )
+    
+    # Process data
+    daily_raw = data.get("daily_raw", {})
+    dates = daily_raw.get("time", [])
+    
+    daily_data = []
+    for i, date_str in enumerate(dates):
+        daily_data.append(DailyDataPoint(
+            date=date_str,
+            temperature_max=convert_temperature(daily_raw.get("temperature_2m_max", [0])[i] or 0, units),
+            temperature_min=convert_temperature(daily_raw.get("temperature_2m_min", [0])[i] or 0, units),
+            precipitation_sum=daily_raw.get("precipitation_sum", [0])[i],
+            wind_speed_max=convert_wind_speed(daily_raw.get("wind_speed_10m_max", [0])[i] or 0, units),
+            weather_code=daily_raw.get("weather_code", [0])[i],
+            sunrise=daily_raw.get("sunrise", [""])[i] if daily_raw.get("sunrise") else None,
+            sunset=daily_raw.get("sunset", [""])[i] if daily_raw.get("sunset") else None
+        ))
+    
+    result = HistoricalWeatherResponse(
+        latitude=data.get("latitude", lat_norm),
+        longitude=data.get("longitude", lon_norm),
+        timezone=data.get("timezone", "UTC"),
+        units=units,
+        start_date=start.isoformat(),
+        end_date=end.isoformat(),
+        generated_at=datetime.now(timezone.utc).isoformat(),
+        source=source,
+        daily=daily_data
+    )
+    
+    if format == ResponseFormat.CSV:
+        return _historical_to_csv(result)
+    
+    return result
+
+
+def _hourly_to_csv(data: HourlyWeatherResponse) -> StreamingResponse:
+    """Convert hourly response to CSV."""
+    output = io.StringIO()
+    writer = csv.writer(output)
+    
+    # Header
+    writer.writerow([
+        "time", "temperature", "feels_like", "humidity", "precipitation",
+        "precipitation_probability", "wind_speed", "wind_direction",
+        "cloud_cover", "weather_code", "uv_index", "pressure"
+    ])
+    
+    # Data
+    for h in data.hourly:
+        writer.writerow([
+            h.time, h.temperature, h.feels_like, h.humidity, h.precipitation,
+            h.precipitation_probability, h.wind_speed, h.wind_direction,
+            h.cloud_cover, h.weather_code, h.uv_index, h.pressure
+        ])
+    
+    output.seek(0)
+    
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": f"attachment; filename=hourly_forecast_{data.latitude}_{data.longitude}.csv"}
+    )
+
+
+def _daily_to_csv(data: DailyWeatherResponse) -> StreamingResponse:
+    """Convert daily response to CSV."""
+    output = io.StringIO()
+    writer = csv.writer(output)
+    
+    writer.writerow([
+        "date", "temperature_max", "temperature_min", "precipitation_sum",
+        "precipitation_probability_max", "wind_speed_max", "weather_code",
+        "sunrise", "sunset", "uv_index_max"
+    ])
+    
+    for d in data.daily:
+        writer.writerow([
+            d.date, d.temperature_max, d.temperature_min, d.precipitation_sum,
+            d.precipitation_probability_max, d.wind_speed_max, d.weather_code,
+            d.sunrise, d.sunset, d.uv_index_max
+        ])
+    
+    output.seek(0)
+    
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": f"attachment; filename=daily_forecast_{data.latitude}_{data.longitude}.csv"}
+    )
+
+
+def _historical_to_csv(data: HistoricalWeatherResponse) -> StreamingResponse:
+    """Convert historical response to CSV."""
+    output = io.StringIO()
+    writer = csv.writer(output)
+    
+    writer.writerow([
+        "date", "temperature_max", "temperature_min", "precipitation_sum",
+        "wind_speed_max", "weather_code", "sunrise", "sunset"
+    ])
+    
+    for d in data.daily:
+        writer.writerow([
+            d.date, d.temperature_max, d.temperature_min, d.precipitation_sum,
+            d.wind_speed_max, d.weather_code, d.sunrise, d.sunset
+        ])
+    
+    output.seek(0)
+    
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={"Content-Disposition": f"attachment; filename=historical_{data.latitude}_{data.longitude}_{data.start_date}_{data.end_date}.csv"}
+    )
diff --git a/schemas/__init__.py b/schemas/__init__.py
new file mode 100644
index 0000000..fbfec61
--- /dev/null
+++ b/schemas/__init__.py
@@ -0,0 +1,66 @@
+"""
+Pydantic Schemas for IntelliWeather API
+
+This module provides request/response models with validation and OpenAPI documentation.
+"""
+
+from schemas.weather import (
+    HourlyWeatherRequest,
+    HourlyWeatherResponse,
+    DailyWeatherRequest,
+    DailyWeatherResponse,
+    HistoricalWeatherRequest,
+    HistoricalWeatherResponse,
+    HourlyDataPoint,
+    DailyDataPoint,
+    WeatherUnits,
+    ResponseFormat
+)
+
+from schemas.geocode import (
+    GeocodeSearchRequest,
+    GeocodeSearchResponse,
+    ReverseGeocodeRequest,
+    ReverseGeocodeResponse,
+    GeoLocation
+)
+
+from schemas.alerts import (
+    WeatherAlert,
+    AlertsResponse,
+    AlertSeverity
+)
+
+from schemas.api_keys import (
+    APIKeyCreate,
+    APIKeyResponse,
+    APIKeyList
+)
+
+__all__ = [
+    # Weather
+    "HourlyWeatherRequest",
+    "HourlyWeatherResponse",
+    "DailyWeatherRequest",
+    "DailyWeatherResponse",
+    "HistoricalWeatherRequest",
+    "HistoricalWeatherResponse",
+    "HourlyDataPoint",
+    "DailyDataPoint",
+    "WeatherUnits",
+    "ResponseFormat",
+    # Geocode
+    "GeocodeSearchRequest",
+    "GeocodeSearchResponse",
+    "ReverseGeocodeRequest",
+    "ReverseGeocodeResponse",
+    "GeoLocation",
+    # Alerts
+    "WeatherAlert",
+    "AlertsResponse",
+    "AlertSeverity",
+    # API Keys
+    "APIKeyCreate",
+    "APIKeyResponse",
+    "APIKeyList",
+]
diff --git a/schemas/alerts.py b/schemas/alerts.py
new file mode 100644
index 0000000..82f875a
--- /dev/null
+++ b/schemas/alerts.py
@@ -0,0 +1,110 @@
+"""
+Weather Alerts Schemas
+
+Provides Pydantic models for weather alerts and warnings.
+"""
+
+from datetime import datetime
+from typing import List, Optional
+from enum import Enum
+from pydantic import BaseModel, Field
+
+
+class AlertSeverity(str, Enum):
+    """Alert severity levels."""
+    EXTREME = "extreme"
+    SEVERE = "severe"
+    MODERATE = "moderate"
+    MINOR = "minor"
+    UNKNOWN = "unknown"
+
+
+class AlertUrgency(str, Enum):
+    """Alert urgency levels."""
+    IMMEDIATE = "immediate"
+    EXPECTED = "expected"
+    FUTURE = "future"
+    PAST = "past"
+    UNKNOWN = "unknown"
+
+
+class AlertCertainty(str, Enum):
+    """Alert certainty levels."""
+    OBSERVED = "observed"
+    LIKELY = "likely"
+    POSSIBLE = "possible"
+    UNLIKELY = "unlikely"
+    UNKNOWN = "unknown"
+
+
+class WeatherAlert(BaseModel):
+    """Weather alert model."""
+    id: str = Field(..., description="Unique alert ID")
+    event: str = Field(..., description="Alert event type", example="Severe Thunderstorm Warning")
+    headline: str = Field(..., description="Alert headline")
+    description: str = Field(..., description="Detailed description")
+    severity: AlertSeverity = Field(..., description="Alert severity level")
+    urgency: Optional[AlertUrgency] = Field(None, description="Alert urgency")
+    certainty: Optional[AlertCertainty] = Field(None, description="Alert certainty")
+    start: str = Field(..., description="Alert start time (ISO 8601)")
+    end: Optional[str] = Field(None, description="Alert end time (ISO 8601)")
+    areas_affected: List[str] = Field(default_factory=list, description="Affected areas")
+    sender: Optional[str] = Field(None, description="Alert sender/source")
+    instruction: Optional[str] = Field(None, description="Safety instructions")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "id": "alert-12345",
+                "event": "Severe Thunderstorm Warning",
+                "headline": "Severe Thunderstorm Warning issued for New York County",
+                "description": "The National Weather Service has issued a severe thunderstorm warning...",
+                "severity": "severe",
+                "urgency": "immediate",
+                "certainty": "observed",
+                "start": "2024-01-15T14:00:00Z",
+                "end": "2024-01-15T18:00:00Z",
+                "areas_affected": ["New York County", "Kings County"],
+                "sender": "NWS New York NY",
+                "instruction": "Move to an interior room on the lowest floor of a building."
+            }
+        }
+
+
+class AlertsResponse(BaseModel):
+    """Response model for alerts endpoint."""
+    latitude: float = Field(..., description="Queried latitude")
+    longitude: float = Field(..., description="Queried longitude")
+    location_name: Optional[str] = Field(None, description="Location name")
+    alerts: List[WeatherAlert] = Field(default_factory=list, description="Active alerts")
+    count: int = Field(..., description="Number of active alerts")
+    last_updated: str = Field(..., description="When alerts were last fetched")
+    source: str = Field(..., description="Data source (cache/live)")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "latitude": 40.7128,
+                "longitude": -74.006,
+                "location_name": "New York",
+                "alerts": [],
+                "count": 0,
+                "last_updated": "2024-01-15T12:00:00Z",
+                "source": "live"
+            }
+        }
+
+
+class AlertsRefreshRequest(BaseModel):
+    """Request to manually refresh alerts."""
+    locations: Optional[List[str]] = Field(
+        None, 
+        description="Specific locations to refresh (lat,lon format). If empty, refreshes popular locations."
+    )
+
+
+class AlertsRefreshResponse(BaseModel):
+    """Response for alerts refresh."""
+    refreshed_locations: int = Field(..., description="Number of locations refreshed")
+    alerts_found: int = Field(..., description="Total alerts found")
+    timestamp: str = Field(..., description="Refresh timestamp")
diff --git a/schemas/api_keys.py b/schemas/api_keys.py
new file mode 100644
index 0000000..1e21251
--- /dev/null
+++ b/schemas/api_keys.py
@@ -0,0 +1,115 @@
+"""
+API Keys Schemas
+
+Provides Pydantic models for API key management.
+"""
+
+from datetime import datetime
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+
+class APIKeyCreate(BaseModel):
+    """Request model for creating a new API key."""
+    name: str = Field(..., min_length=1, max_length=100, description="Key name/description", example="My App Key")
+    rate_limit: Optional[int] = Field(None, ge=1, le=10000, description="Custom rate limit (requests/min)")
+    expires_in_days: Optional[int] = Field(None, ge=1, le=365, description="Key expiration in days")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "name": "Production API Key",
+                "rate_limit": 100,
+                "expires_in_days": 90
+            }
+        }
+
+
+class APIKeyResponse(BaseModel):
+    """Response model for a single API key."""
+    key_id: str = Field(..., description="Unique key identifier")
+    name: str = Field(..., description="Key name/description")
+    key_prefix: str = Field(..., description="First 8 characters of the key", example="iw_live_")
+    created_at: str = Field(..., description="When the key was created")
+    expires_at: Optional[str] = Field(None, description="When the key expires")
+    last_used_at: Optional[str] = Field(None, description="When the key was last used")
+    rate_limit: int = Field(..., description="Rate limit (requests/min)")
+    total_requests: int = Field(0, description="Total requests made with this key")
+    is_active: bool = Field(True, description="Whether the key is active")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "key_id": "key_abc123",
+                "name": "Production API Key",
+                "key_prefix": "iw_live_",
+                "created_at": "2024-01-15T12:00:00Z",
+                "expires_at": "2024-04-15T12:00:00Z",
+                "last_used_at": "2024-01-15T14:30:00Z",
+                "rate_limit": 100,
+                "total_requests": 1523,
+                "is_active": True
+            }
+        }
+
+
+class APIKeyCreated(BaseModel):
+    """Response when a new API key is created (includes full key)."""
+    key_id: str = Field(..., description="Unique key identifier")
+    name: str = Field(..., description="Key name/description")
+    api_key: str = Field(..., description="The full API key (only shown once!)")
+    created_at: str = Field(..., description="When the key was created")
+    expires_at: Optional[str] = Field(None, description="When the key expires")
+    rate_limit: int = Field(..., description="Rate limit (requests/min)")
+    warning: str = Field(
+        "Store this key securely. It will not be shown again.",
+        description="Important warning"
+    )
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "key_id": "key_abc123",
+                "name": "Production API Key",
+                "api_key": "iw_live_sk_1234567890abcdef",
+                "created_at": "2024-01-15T12:00:00Z",
+                "expires_at": "2024-04-15T12:00:00Z",
+                "rate_limit": 100,
+                "warning": "Store this key securely. It will not be shown again."
+            }
+        }
+
+
+class APIKeyList(BaseModel):
+    """Response model for listing API keys."""
+    keys: List[APIKeyResponse] = Field(..., description="List of API keys")
+    count: int = Field(..., description="Total number of keys")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "keys": [
+                    {
+                        "key_id": "key_abc123",
+                        "name": "Production API Key",
+                        "key_prefix": "iw_live_",
+                        "created_at": "2024-01-15T12:00:00Z",
+                        "rate_limit": 100,
+                        "is_active": True
+                    }
+                ],
+                "count": 1
+            }
+        }
+
+
+class APIKeyRevoke(BaseModel):
+    """Request to revoke an API key."""
+    key_id: str = Field(..., description="Key ID to revoke")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "key_id": "key_abc123"
+            }
+        }
diff --git a/schemas/geocode.py b/schemas/geocode.py
new file mode 100644
index 0000000..f8dd8e4
--- /dev/null
+++ b/schemas/geocode.py
@@ -0,0 +1,104 @@
+"""
+Geocoding Schemas
+
+Provides Pydantic models for geocoding and reverse geocoding endpoints.
+"""
+
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+
+class GeoLocation(BaseModel):
+    """Geographic location with metadata."""
+    id: int = Field(..., description="Unique location ID")
+    name: str = Field(..., description="Location name", example="New York")
+    latitude: float = Field(..., description="Latitude", example=40.7128)
+    longitude: float = Field(..., description="Longitude", example=-74.006)
+    country: str = Field(..., description="Country name", example="United States")
+    country_code: Optional[str] = Field(None, description="ISO country code", example="US")
+    admin1: Optional[str] = Field(None, description="State/Province", example="New York")
+    admin2: Optional[str] = Field(None, description="County/District", example="New York County")
+    timezone: Optional[str] = Field(None, description="Timezone", example="America/New_York")
+    population: Optional[int] = Field(None, description="Population", example=8336817)
+    elevation: Optional[float] = Field(None, description="Elevation in meters", example=10)
+    feature_code: Optional[str] = Field(None, description="GeoNames feature code", example="PPL")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "id": 5128581,
+                "name": "New York",
+                "latitude": 40.7128,
+                "longitude": -74.006,
+                "country": "United States",
+                "country_code": "US",
+                "admin1": "New York",
+                "timezone": "America/New_York",
+                "population": 8336817
+            }
+        }
+
+
+class GeocodeSearchRequest(BaseModel):
+    """Request model for geocode search."""
+    q: str = Field(..., min_length=1, max_length=200, description="Search query", example="New York")
+    limit: int = Field(5, ge=1, le=20, description="Maximum results to return")
+    lang: Optional[str] = Field(None, description="Language for results", example="en")
+
+
+class GeocodeSearchResponse(BaseModel):
+    """Response model for geocode search."""
+    results: List[GeoLocation] = Field(..., description="List of matching locations")
+    query: str = Field(..., description="Original search query")
+    count: int = Field(..., description="Number of results returned")
+    source: str = Field(..., description="Data source (cache/live)", example="cache")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "results": [
+                    {
+                        "id": 5128581,
+                        "name": "New York",
+                        "latitude": 40.7128,
+                        "longitude": -74.006,
+                        "country": "United States",
+                        "country_code": "US",
+                        "timezone": "America/New_York"
+                    }
+                ],
+                "query": "New York",
+                "count": 1,
+                "source": "live"
+            }
+        }
+
+
+class ReverseGeocodeRequest(BaseModel):
+    """Request model for reverse geocoding."""
+    lat: float = Field(..., ge=-90, le=90, description="Latitude", example=40.7128)
+    lon: float = Field(..., ge=-180, le=180, description="Longitude", example=-74.006)
+
+
+class ReverseGeocodeResponse(BaseModel):
+    """Response model for reverse geocoding."""
+    location: Optional[GeoLocation] = Field(None, description="Nearest location")
+    latitude: float = Field(..., description="Queried latitude")
+    longitude: float = Field(..., description="Queried longitude")
+    source: str = Field(..., description="Data source (cache/live)")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "location": {
+                    "id": 5128581,
+                    "name": "New York",
+                    "latitude": 40.7128,
+                    "longitude": -74.006,
+                    "country": "United States"
+                },
+                "latitude": 40.7128,
+                "longitude": -74.006,
+                "source": "cache"
+            }
+        }
diff --git a/schemas/weather.py b/schemas/weather.py
new file mode 100644
index 0000000..43fb04d
--- /dev/null
+++ b/schemas/weather.py
@@ -0,0 +1,186 @@
+"""
+Weather Schemas for Phase 2 API Endpoints
+
+Provides Pydantic models for hourly, daily, and historical weather data.
+"""
+
+from datetime import date, datetime
+from typing import List, Optional, Literal
+from enum import Enum
+from pydantic import BaseModel, Field, field_validator
+
+
+class WeatherUnits(str, Enum):
+    """Units for weather measurements."""
+    METRIC = "metric"
+    IMPERIAL = "imperial"
+
+
+class ResponseFormat(str, Enum):
+    """Response format options."""
+    JSON = "json"
+    CSV = "csv"
+
+
+class HourlyDataPoint(BaseModel):
+    """Single hourly weather data point."""
+    time: str = Field(..., description="ISO 8601 timestamp", example="2024-01-15T14:00")
+    temperature: float = Field(..., description="Temperature", example=22.5)
+    feels_like: Optional[float] = Field(None, description="Feels like temperature", example=21.0)
+    humidity: Optional[int] = Field(None, description="Relative humidity %", example=65)
+    precipitation: Optional[float] = Field(None, description="Precipitation amount", example=0.0)
+    precipitation_probability: Optional[int] = Field(None, description="Precipitation probability %", example=10)
+    wind_speed: Optional[float] = Field(None, description="Wind speed", example=5.2)
+    wind_direction: Optional[int] = Field(None, description="Wind direction degrees", example=180)
+    cloud_cover: Optional[int] = Field(None, description="Cloud cover %", example=40)
+    weather_code: Optional[int] = Field(None, description="WMO weather code", example=1)
+    uv_index: Optional[float] = Field(None, description="UV index", example=3.5)
+    visibility: Optional[float] = Field(None, description="Visibility in meters/miles", example=10000)
+    pressure: Optional[float] = Field(None, description="Sea level pressure", example=1013.25)
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "time": "2024-01-15T14:00",
+                "temperature": 22.5,
+                "feels_like": 21.0,
+                "humidity": 65,
+                "precipitation": 0.0,
+                "precipitation_probability": 10,
+                "wind_speed": 5.2,
+                "wind_direction": 180,
+                "cloud_cover": 40,
+                "weather_code": 1,
+                "uv_index": 3.5,
+                "visibility": 10000,
+                "pressure": 1013.25
+            }
+        }
+
+
+class DailyDataPoint(BaseModel):
+    """Single daily weather data point."""
+    date: str = Field(..., description="Date in YYYY-MM-DD format", example="2024-01-15")
+    temperature_max: float = Field(..., description="Maximum temperature", example=25.0)
+    temperature_min: float = Field(..., description="Minimum temperature", example=15.0)
+    temperature_mean: Optional[float] = Field(None, description="Mean temperature", example=20.0)
+    precipitation_sum: Optional[float] = Field(None, description="Total precipitation", example=2.5)
+    precipitation_probability_max: Optional[int] = Field(None, description="Max precipitation probability %", example=40)
+    wind_speed_max: Optional[float] = Field(None, description="Maximum wind speed", example=15.0)
+    weather_code: Optional[int] = Field(None, description="WMO weather code", example=3)
+    sunrise: Optional[str] = Field(None, description="Sunrise time", example="06:45")
+    sunset: Optional[str] = Field(None, description="Sunset time", example="18:30")
+    uv_index_max: Optional[float] = Field(None, description="Maximum UV index", example=6.0)
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "date": "2024-01-15",
+                "temperature_max": 25.0,
+                "temperature_min": 15.0,
+                "temperature_mean": 20.0,
+                "precipitation_sum": 2.5,
+                "precipitation_probability_max": 40,
+                "wind_speed_max": 15.0,
+                "weather_code": 3,
+                "sunrise": "06:45",
+                "sunset": "18:30",
+                "uv_index_max": 6.0
+            }
+        }
+
+
+class HourlyWeatherRequest(BaseModel):
+    """Request model for hourly weather endpoint."""
+    lat: float = Field(..., ge=-90, le=90, description="Latitude", example=40.7128)
+    lon: float = Field(..., ge=-180, le=180, description="Longitude", example=-74.006)
+    hours: Literal[24, 48, 72] = Field(24, description="Number of hours to forecast")
+    units: WeatherUnits = Field(WeatherUnits.METRIC, description="Unit system")
+    format: ResponseFormat = Field(ResponseFormat.JSON, description="Response format")
+
+
+class HourlyWeatherResponse(BaseModel):
+    """Response model for hourly weather endpoint."""
+    latitude: float = Field(..., description="Latitude of the location")
+    longitude: float = Field(..., description="Longitude of the location")
+    timezone: str = Field(..., description="Timezone of the location", example="America/New_York")
+    units: WeatherUnits = Field(..., description="Units used in response")
+    generated_at: str = Field(..., description="When this response was generated")
+    source: str = Field(..., description="Data source (cache/live)", example="cache")
+    hourly: List[HourlyDataPoint] = Field(..., description="Hourly forecast data")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "latitude": 40.71,
+                "longitude": -74.01,
+                "timezone": "America/New_York",
+                "units": "metric",
+                "generated_at": "2024-01-15T12:00:00Z",
+                "source": "live",
+                "hourly": [
+                    {
+                        "time": "2024-01-15T14:00",
+                        "temperature": 22.5,
+                        "humidity": 65,
+                        "precipitation_probability": 10
+                    }
+                ]
+            }
+        }
+
+
+class DailyWeatherRequest(BaseModel):
+    """Request model for daily weather endpoint."""
+    lat: float = Field(..., ge=-90, le=90, description="Latitude", example=40.7128)
+    lon: float = Field(..., ge=-180, le=180, description="Longitude", example=-74.006)
+    days: Literal[7, 14] = Field(7, description="Number of days to forecast")
+    units: WeatherUnits = Field(WeatherUnits.METRIC, description="Unit system")
+    format: ResponseFormat = Field(ResponseFormat.JSON, description="Response format")
+
+
+class DailyWeatherResponse(BaseModel):
+    """Response model for daily weather endpoint."""
+    latitude: float = Field(..., description="Latitude of the location")
+    longitude: float = Field(..., description="Longitude of the location")
+    timezone: str = Field(..., description="Timezone of the location")
+    units: WeatherUnits = Field(..., description="Units used in response")
+    generated_at: str = Field(..., description="When this response was generated")
+    source: str = Field(..., description="Data source (cache/live)")
+    daily: List[DailyDataPoint] = Field(..., description="Daily forecast data")
+
+
+class HistoricalWeatherRequest(BaseModel):
+    """Request model for historical weather endpoint."""
+    lat: float = Field(..., ge=-90, le=90, description="Latitude", example=40.7128)
+    lon: float = Field(..., ge=-180, le=180, description="Longitude", example=-74.006)
+    start: date = Field(..., description="Start date (YYYY-MM-DD)", example="2024-01-01")
+    end: date = Field(..., description="End date (YYYY-MM-DD)", example="2024-01-31")
+    units: WeatherUnits = Field(WeatherUnits.METRIC, description="Unit system")
+    format: ResponseFormat = Field(ResponseFormat.JSON, description="Response format")
+
+    @field_validator('end')
+    @classmethod
+    def validate_date_range(cls, v: date, info) -> date:
+        """Validate that date range is not more than 1 year."""
+        start = info.data.get('start')
+        if start and v:
+            diff = (v - start).days
+            if diff > 365:
+                raise ValueError("Date range cannot exceed 1 year (365 days)")
+            if diff < 0:
+                raise ValueError("End date must be after start date")
+        return v
+
+
+class HistoricalWeatherResponse(BaseModel):
+    """Response model for historical weather endpoint."""
+    latitude: float = Field(..., description="Latitude of the location")
+    longitude: float = Field(..., description="Longitude of the location")
+    timezone: str = Field(..., description="Timezone of the location")
+    units: WeatherUnits = Field(..., description="Units used in response")
+    start_date: str = Field(..., description="Start date of data")
+    end_date: str = Field(..., description="End date of data")
+    generated_at: str = Field(..., description="When this response was generated")
+    source: str = Field(..., description="Data source (cache/live)")
+    daily: List[DailyDataPoint] = Field(..., description="Historical daily data")
diff --git a/session_middleware.py b/session_middleware.py
new file mode 100644
index 0000000..44f2173
--- /dev/null
+++ b/session_middleware.py
@@ -0,0 +1,250 @@
+"""
+Secure Session Middleware
+
+This module provides server-side session management with:
+- UUID session IDs
+- CSV-based session storage
+- Session timeout management
+- Secure cookie handling
+- Request-attached session objects
+"""
+
+from datetime import datetime, timezone
+from typing import Optional, Callable
+from fastapi import Request, Response, HTTPException, status
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+from storage import get_storage, Session
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class SessionData:
+    """
+    Session data container attached to requests.
+    """
+    
+    def __init__(
+        self,
+        session: Optional[Session] = None,
+        user_id: Optional[str] = None,
+        is_authenticated: bool = False
+    ):
+        self.session = session
+        self.user_id = user_id
+        self.is_authenticated = is_authenticated
+        self._modified = False
+    
+    def mark_modified(self) -> None:
+        """Mark session as modified (needs to be saved)."""
+        self._modified = True
+    
+    @property
+    def is_modified(self) -> bool:
+        """Check if session has been modified."""
+        return self._modified
+
+
+class SessionMiddleware(BaseHTTPMiddleware):
+    """
+    FastAPI middleware for session management.
+    
+    Handles:
+    - Session ID extraction from cookies
+    - Session validation
+    - Session data attachment to requests
+    - Cookie management
+    """
+    
+    def __init__(
+        self,
+        app,
+        cookie_name: str = None,
+        cookie_secure: bool = None,
+        cookie_httponly: bool = None,
+        cookie_samesite: str = None,
+        session_timeout: int = None
+    ):
+        super().__init__(app)
+        self.cookie_name = cookie_name or settings.SESSION_COOKIE_NAME
+        self.cookie_secure = cookie_secure if cookie_secure is not None else settings.SESSION_COOKIE_SECURE
+        self.cookie_httponly = cookie_httponly if cookie_httponly is not None else settings.SESSION_COOKIE_HTTPONLY
+        self.cookie_samesite = cookie_samesite or settings.SESSION_COOKIE_SAMESITE
+        self.session_timeout = session_timeout or settings.SESSION_TIMEOUT_SECONDS
+        
+        logger.info(
+            f"Session middleware initialized (cookie={self.cookie_name}, "
+            f"secure={self.cookie_secure}, timeout={self.session_timeout}s)"
+        )
+    
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Process request with session handling."""
+        storage = get_storage()
+        session_data = SessionData()
+        
+        # Extract session ID from cookie
+        session_id = request.cookies.get(self.cookie_name)
+        
+        if session_id:
+            # Load existing session
+            session = storage.get_session(session_id)
+            
+            if session and session.is_valid and not session.is_expired():
+                # Valid session found
+                session_data.session = session
+                session_data.user_id = session.user_id
+                session_data.is_authenticated = True
+                
+                # Update last_active_at
+                session.last_active_at = datetime.now(timezone.utc).isoformat()
+                storage.update_session(session)
+                
+                logger.debug(f"Session loaded for user: {session.user_id}")
+        
+        # Attach session data to request state
+        request.state.session = session_data
+        
+        # Process the request
+        response = await call_next(request)
+        
+        return response
+    
+    def create_session(self, user_id: str, response: Response) -> Session:
+        """
+        Create a new session for a user and set the cookie.
+        
+        Args:
+            user_id: The user ID to create session for
+            response: The response object to set cookie on
+            
+        Returns:
+            The created Session object
+        """
+        storage = get_storage()
+        
+        # Create new session
+        session = Session.create(user_id, self.session_timeout)
+        storage.create_session(session)
+        
+        # Set cookie
+        response.set_cookie(
+            key=self.cookie_name,
+            value=session.session_id,
+            httponly=self.cookie_httponly,
+            secure=self.cookie_secure,
+            samesite=self.cookie_samesite,
+            max_age=self.session_timeout
+        )
+        
+        logger.info(f"Session created for user: {user_id}")
+        return session
+    
+    def destroy_session(self, session_id: str, response: Response) -> bool:
+        """
+        Destroy a session and clear the cookie.
+        
+        Args:
+            session_id: The session ID to destroy
+            response: The response object to clear cookie on
+            
+        Returns:
+            True if session was destroyed, False otherwise
+        """
+        storage = get_storage()
+        
+        # Invalidate session in storage
+        result = storage.invalidate_session(session_id)
+        
+        # Clear cookie
+        response.delete_cookie(
+            key=self.cookie_name,
+            httponly=self.cookie_httponly,
+            secure=self.cookie_secure,
+            samesite=self.cookie_samesite
+        )
+        
+        if result:
+            logger.info(f"Session destroyed: {session_id}")
+        
+        return result
+
+
+def get_session(request: Request) -> SessionData:
+    """
+    Get the session data from a request.
+    
+    Args:
+        request: The FastAPI request object
+        
+    Returns:
+        SessionData object
+        
+    Raises:
+        HTTPException: If session middleware is not configured
+    """
+    if not hasattr(request.state, "session"):
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Session middleware not configured"
+        )
+    
+    return request.state.session
+
+
+def require_auth(request: Request) -> SessionData:
+    """
+    Require authentication for an endpoint.
+    
+    Use as a FastAPI dependency to protect endpoints.
+    
+    Args:
+        request: The FastAPI request object
+        
+    Returns:
+        SessionData object if authenticated
+        
+    Raises:
+        HTTPException: If not authenticated
+    """
+    session = get_session(request)
+    
+    if not session.is_authenticated:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required",
+            headers={"WWW-Authenticate": "Bearer"}
+        )
+    
+    return session
+
+
+def optional_auth(request: Request) -> SessionData:
+    """
+    Optional authentication for an endpoint.
+    
+    Returns session data regardless of authentication status.
+    
+    Args:
+        request: The FastAPI request object
+        
+    Returns:
+        SessionData object
+    """
+    return get_session(request)
+
+
+# Global session middleware instance
+_session_middleware: Optional[SessionMiddleware] = None
+
+
+def get_session_middleware() -> Optional[SessionMiddleware]:
+    """Get the global session middleware instance."""
+    return _session_middleware
+
+
+def set_session_middleware(middleware: SessionMiddleware) -> None:
+    """Set the global session middleware instance."""
+    global _session_middleware
+    _session_middleware = middleware
diff --git a/static/css/animations.css b/static/css/animations.css
new file mode 100644
index 0000000..6594bbb
--- /dev/null
+++ b/static/css/animations.css
@@ -0,0 +1,568 @@
+/**
+ * IntelliWeather - Advanced Animation System
+ * 
+ * Hardware-accelerated animations using CSS transforms and opacity
+ * Supports reduced motion preferences
+ * 
+ * Animation Tokens:
+ * - Duration: fast (150ms), normal (300ms), slow (500ms), slower (800ms)
+ * - Easing: ease-out-expo, ease-in-out-expo, bounce
+ */
+
+/* ==================== DESIGN TOKENS ==================== */
+:root {
+    /* Animation Durations */
+    --duration-instant: 100ms;
+    --duration-fast: 150ms;
+    --duration-normal: 300ms;
+    --duration-slow: 500ms;
+    --duration-slower: 800ms;
+    --duration-slowest: 1200ms;
+    
+    /* Easing Functions */
+    --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+    --ease-in-out-expo: cubic-bezier(0.87, 0, 0.13, 1);
+    --ease-out-back: cubic-bezier(0.34, 1.56, 0.64, 1);
+    --ease-bounce: cubic-bezier(0.68, -0.6, 0.32, 1.6);
+    --ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
+    
+    /* Stagger Delays */
+    --stagger-xs: 30ms;
+    --stagger-sm: 50ms;
+    --stagger-md: 80ms;
+    --stagger-lg: 120ms;
+    
+    /* Transform Origins */
+    --transform-gpu: translateZ(0);
+}
+
+/* ==================== REDUCED MOTION ==================== */
+@media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+    }
+}
+
+/* ==================== BASE ANIMATION UTILITIES ==================== */
+
+/* GPU Acceleration Hint */
+.gpu-accelerated {
+    transform: var(--transform-gpu);
+    will-change: transform, opacity;
+    backface-visibility: hidden;
+}
+
+/* Animation States */
+.animate-ready {
+    opacity: 0;
+    transform: translateY(20px);
+}
+
+.animate-in {
+    animation: fadeInUp var(--duration-slow) var(--ease-out-expo) forwards;
+}
+
+.animate-out {
+    animation: fadeOutDown var(--duration-normal) var(--ease-in-out-expo) forwards;
+}
+
+/* ==================== PAGE TRANSITIONS ==================== */
+
+.page-enter {
+    animation: pageEnter var(--duration-slow) var(--ease-out-expo) forwards;
+}
+
+.page-exit {
+    animation: pageExit var(--duration-normal) var(--ease-in-out-expo) forwards;
+}
+
+@keyframes pageEnter {
+    0% {
+        opacity: 0;
+        transform: translateY(30px) scale(0.98);
+    }
+    100% {
+        opacity: 1;
+        transform: translateY(0) scale(1);
+    }
+}
+
+@keyframes pageExit {
+    0% {
+        opacity: 1;
+        transform: translateY(0) scale(1);
+    }
+    100% {
+        opacity: 0;
+        transform: translateY(-20px) scale(0.98);
+    }
+}
+
+/* ==================== CARD ANIMATIONS ==================== */
+
+/* Fade In Up */
+@keyframes fadeInUp {
+    0% {
+        opacity: 0;
+        transform: translateY(30px) var(--transform-gpu);
+    }
+    100% {
+        opacity: 1;
+        transform: translateY(0) var(--transform-gpu);
+    }
+}
+
+@keyframes fadeOutDown {
+    0% {
+        opacity: 1;
+        transform: translateY(0) var(--transform-gpu);
+    }
+    100% {
+        opacity: 0;
+        transform: translateY(20px) var(--transform-gpu);
+    }
+}
+
+/* Slide In */
+@keyframes slideInLeft {
+    0% {
+        opacity: 0;
+        transform: translateX(-40px) var(--transform-gpu);
+    }
+    100% {
+        opacity: 1;
+        transform: translateX(0) var(--transform-gpu);
+    }
+}
+
+@keyframes slideInRight {
+    0% {
+        opacity: 0;
+        transform: translateX(40px) var(--transform-gpu);
+    }
+    100% {
+        opacity: 1;
+        transform: translateX(0) var(--transform-gpu);
+    }
+}
+
+/* Scale In */
+@keyframes scaleIn {
+    0% {
+        opacity: 0;
+        transform: scale(0.9) var(--transform-gpu);
+    }
+    100% {
+        opacity: 1;
+        transform: scale(1) var(--transform-gpu);
+    }
+}
+
+@keyframes scaleInBounce {
+    0% {
+        opacity: 0;
+        transform: scale(0.8) var(--transform-gpu);
+    }
+    70% {
+        transform: scale(1.05) var(--transform-gpu);
+    }
+    100% {
+        opacity: 1;
+        transform: scale(1) var(--transform-gpu);
+    }
+}
+
+/* Card Flip */
+@keyframes cardFlip {
+    0% {
+        transform: perspective(1000px) rotateY(0deg);
+    }
+    50% {
+        transform: perspective(1000px) rotateY(90deg);
+    }
+    100% {
+        transform: perspective(1000px) rotateY(0deg);
+    }
+}
+
+.card-flip {
+    animation: cardFlip var(--duration-slower) var(--ease-in-out-expo);
+}
+
+/* ==================== WEATHER ICON ANIMATIONS ==================== */
+
+@keyframes weatherBounce {
+    0%, 100% {
+        transform: translateY(0) scale(1) var(--transform-gpu);
+    }
+    50% {
+        transform: translateY(-15px) scale(1.05) var(--transform-gpu);
+    }
+}
+
+@keyframes weatherPulse {
+    0%, 100% {
+        transform: scale(1) var(--transform-gpu);
+        filter: drop-shadow(0 5px 15px rgba(0, 0, 0, 0.1));
+    }
+    50% {
+        transform: scale(1.08) var(--transform-gpu);
+        filter: drop-shadow(0 10px 25px rgba(0, 0, 0, 0.15));
+    }
+}
+
+@keyframes weatherSpin {
+    0% {
+        transform: rotate(0deg) var(--transform-gpu);
+    }
+    100% {
+        transform: rotate(360deg) var(--transform-gpu);
+    }
+}
+
+@keyframes weatherShake {
+    0%, 100% {
+        transform: translateX(0) rotate(0deg) var(--transform-gpu);
+    }
+    25% {
+        transform: translateX(-3px) rotate(-3deg) var(--transform-gpu);
+    }
+    75% {
+        transform: translateX(3px) rotate(3deg) var(--transform-gpu);
+    }
+}
+
+.weather-icon-bounce {
+    animation: weatherBounce 3s var(--ease-out-expo) infinite;
+}
+
+.weather-icon-pulse {
+    animation: weatherPulse 2s var(--ease-smooth) infinite;
+}
+
+.weather-icon-spin {
+    animation: weatherSpin 10s linear infinite;
+}
+
+.weather-icon-shake {
+    animation: weatherShake 0.5s var(--ease-smooth) infinite;
+}
+
+/* ==================== SKELETON LOADERS ==================== */
+
+@keyframes skeletonShimmer {
+    0% {
+        background-position: -200% 0;
+    }
+    100% {
+        background-position: 200% 0;
+    }
+}
+
+.skeleton {
+    background: linear-gradient(
+        90deg,
+        rgba(255, 255, 255, 0.1) 25%,
+        rgba(255, 255, 255, 0.2) 50%,
+        rgba(255, 255, 255, 0.1) 75%
+    );
+    background-size: 200% 100%;
+    animation: skeletonShimmer 1.5s var(--ease-smooth) infinite;
+    border-radius: 8px;
+}
+
+.skeleton-text {
+    height: 1em;
+    margin-bottom: 0.5em;
+}
+
+.skeleton-title {
+    height: 2em;
+    width: 60%;
+    margin-bottom: 1em;
+}
+
+.skeleton-card {
+    height: 150px;
+    border-radius: 16px;
+}
+
+.skeleton-circle {
+    width: 80px;
+    height: 80px;
+    border-radius: 50%;
+}
+
+/* ==================== SHIMMER EFFECTS ==================== */
+
+@keyframes shimmer {
+    0% {
+        transform: translateX(-100%) rotate(45deg);
+    }
+    100% {
+        transform: translateX(200%) rotate(45deg);
+    }
+}
+
+.shimmer-effect {
+    position: relative;
+    overflow: hidden;
+}
+
+.shimmer-effect::after {
+    content: '';
+    position: absolute;
+    top: -50%;
+    left: -50%;
+    width: 200%;
+    height: 200%;
+    background: linear-gradient(
+        45deg,
+        transparent 40%,
+        rgba(255, 255, 255, 0.15) 50%,
+        transparent 60%
+    );
+    animation: shimmer 3s var(--ease-out-expo) infinite;
+    pointer-events: none;
+}
+
+/* ==================== HOVER EFFECTS ==================== */
+
+.hover-lift {
+    transition: transform var(--duration-normal) var(--ease-out-expo),
+                box-shadow var(--duration-normal) var(--ease-out-expo);
+}
+
+.hover-lift:hover {
+    transform: translateY(-8px) var(--transform-gpu);
+    box-shadow: 0 20px 40px rgba(0, 0, 0, 0.15);
+}
+
+.hover-glow {
+    transition: box-shadow var(--duration-normal) var(--ease-out-expo);
+}
+
+.hover-glow:hover {
+    box-shadow: 0 0 30px rgba(212, 175, 55, 0.4);
+}
+
+.hover-scale {
+    transition: transform var(--duration-fast) var(--ease-out-expo);
+}
+
+.hover-scale:hover {
+    transform: scale(1.05) var(--transform-gpu);
+}
+
+/* ==================== STAGGERED ANIMATIONS ==================== */
+
+.stagger-children > * {
+    opacity: 0;
+    animation: fadeInUp var(--duration-slow) var(--ease-out-expo) forwards;
+}
+
+.stagger-children > *:nth-child(1) { animation-delay: calc(var(--stagger-sm) * 1); }
+.stagger-children > *:nth-child(2) { animation-delay: calc(var(--stagger-sm) * 2); }
+.stagger-children > *:nth-child(3) { animation-delay: calc(var(--stagger-sm) * 3); }
+.stagger-children > *:nth-child(4) { animation-delay: calc(var(--stagger-sm) * 4); }
+.stagger-children > *:nth-child(5) { animation-delay: calc(var(--stagger-sm) * 5); }
+.stagger-children > *:nth-child(6) { animation-delay: calc(var(--stagger-sm) * 6); }
+.stagger-children > *:nth-child(7) { animation-delay: calc(var(--stagger-sm) * 7); }
+.stagger-children > *:nth-child(8) { animation-delay: calc(var(--stagger-sm) * 8); }
+.stagger-children > *:nth-child(9) { animation-delay: calc(var(--stagger-sm) * 9); }
+.stagger-children > *:nth-child(10) { animation-delay: calc(var(--stagger-sm) * 10); }
+
+/* ==================== CHART ANIMATIONS ==================== */
+
+@keyframes chartLineReveal {
+    0% {
+        stroke-dashoffset: 1000;
+    }
+    100% {
+        stroke-dashoffset: 0;
+    }
+}
+
+@keyframes chartBarGrow {
+    0% {
+        transform: scaleY(0);
+        transform-origin: bottom;
+    }
+    100% {
+        transform: scaleY(1);
+        transform-origin: bottom;
+    }
+}
+
+@keyframes chartAreaFill {
+    0% {
+        opacity: 0;
+        transform: scaleY(0.8);
+        transform-origin: bottom;
+    }
+    100% {
+        opacity: 1;
+        transform: scaleY(1);
+        transform-origin: bottom;
+    }
+}
+
+.chart-line {
+    stroke-dasharray: 1000;
+    stroke-dashoffset: 1000;
+    animation: chartLineReveal 1.5s var(--ease-out-expo) forwards;
+}
+
+.chart-bar {
+    animation: chartBarGrow 0.8s var(--ease-out-expo) forwards;
+}
+
+.chart-area {
+    animation: chartAreaFill 1s var(--ease-out-expo) forwards;
+}
+
+/* ==================== LOADING STATES ==================== */
+
+@keyframes loadingDots {
+    0%, 80%, 100% {
+        opacity: 0;
+        transform: scale(0.8);
+    }
+    40% {
+        opacity: 1;
+        transform: scale(1);
+    }
+}
+
+.loading-dots span {
+    display: inline-block;
+    width: 8px;
+    height: 8px;
+    margin: 0 2px;
+    background: currentColor;
+    border-radius: 50%;
+    animation: loadingDots 1.4s ease-in-out infinite both;
+}
+
+.loading-dots span:nth-child(1) { animation-delay: 0s; }
+.loading-dots span:nth-child(2) { animation-delay: 0.16s; }
+.loading-dots span:nth-child(3) { animation-delay: 0.32s; }
+
+/* ==================== NOTIFICATION ANIMATIONS ==================== */
+
+@keyframes notificationSlideIn {
+    0% {
+        opacity: 0;
+        transform: translateX(100%) var(--transform-gpu);
+    }
+    100% {
+        opacity: 1;
+        transform: translateX(0) var(--transform-gpu);
+    }
+}
+
+@keyframes notificationSlideOut {
+    0% {
+        opacity: 1;
+        transform: translateX(0) var(--transform-gpu);
+    }
+    100% {
+        opacity: 0;
+        transform: translateX(100%) var(--transform-gpu);
+    }
+}
+
+.notification-enter {
+    animation: notificationSlideIn var(--duration-normal) var(--ease-out-expo) forwards;
+}
+
+.notification-exit {
+    animation: notificationSlideOut var(--duration-fast) var(--ease-in-out-expo) forwards;
+}
+
+/* ==================== PULSE & GLOW ==================== */
+
+@keyframes pulse {
+    0%, 100% {
+        transform: scale(1);
+        opacity: 1;
+    }
+    50% {
+        transform: scale(1.1);
+        opacity: 0.8;
+    }
+}
+
+@keyframes glow {
+    0%, 100% {
+        box-shadow: 0 0 5px rgba(212, 175, 55, 0.5);
+    }
+    50% {
+        box-shadow: 0 0 20px rgba(212, 175, 55, 0.8), 0 0 40px rgba(212, 175, 55, 0.4);
+    }
+}
+
+.pulse {
+    animation: pulse 2s var(--ease-smooth) infinite;
+}
+
+.glow {
+    animation: glow 2s var(--ease-smooth) infinite;
+}
+
+/* ==================== BACKGROUND EFFECTS ==================== */
+
+@keyframes gradientShift {
+    0%, 100% {
+        background-position: 0% 50%;
+    }
+    50% {
+        background-position: 100% 50%;
+    }
+}
+
+.animated-gradient {
+    background-size: 200% 200%;
+    animation: gradientShift 15s ease infinite;
+}
+
+/* Floating Animation */
+@keyframes float {
+    0%, 100% {
+        transform: translateY(0) rotate(0deg);
+    }
+    25% {
+        transform: translateY(-20px) rotate(5deg);
+    }
+    50% {
+        transform: translateY(-40px) rotate(0deg);
+    }
+    75% {
+        transform: translateY(-20px) rotate(-5deg);
+    }
+}
+
+.float {
+    animation: float 6s ease-in-out infinite;
+}
+
+/* Particle Effect */
+@keyframes particle {
+    0% {
+        opacity: 0;
+        transform: translateY(0) scale(0);
+    }
+    50% {
+        opacity: 1;
+    }
+    100% {
+        opacity: 0;
+        transform: translateY(-100px) scale(1);
+    }
+}
+
+.particle {
+    animation: particle 3s ease-out infinite;
+}
diff --git a/static/css/theme.css b/static/css/theme.css
new file mode 100644
index 0000000..6845772
--- /dev/null
+++ b/static/css/theme.css
@@ -0,0 +1,555 @@
+/**
+ * IntelliWeather - Theme System
+ * 
+ * Supports light and dark modes with smooth transitions
+ * Royal color scheme with gold accents
+ */
+
+/* ==================== CSS VARIABLES ==================== */
+:root {
+    /* Royal Colors */
+    --royal-gold: #d4af37;
+    --royal-gold-light: #f4e4bc;
+    --royal-gold-dark: #b8960c;
+    --royal-purple: #4a1c6e;
+    --royal-purple-light: #7b4397;
+    --royal-purple-dark: #2d0f45;
+    
+    /* Accent Colors */
+    --accent-blue: #3b82f6;
+    --accent-green: #10b981;
+    --accent-red: #ef4444;
+    --accent-orange: #f59e0b;
+    --accent-cyan: #06b6d4;
+    
+    /* Spacing */
+    --space-xs: 0.25rem;
+    --space-sm: 0.5rem;
+    --space-md: 1rem;
+    --space-lg: 1.5rem;
+    --space-xl: 2rem;
+    --space-2xl: 3rem;
+    --space-3xl: 4rem;
+    
+    /* Border Radius */
+    --radius-sm: 8px;
+    --radius-md: 12px;
+    --radius-lg: 16px;
+    --radius-xl: 24px;
+    --radius-2xl: 32px;
+    --radius-full: 9999px;
+    
+    /* Shadows */
+    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+    --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+    --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
+    --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
+    --shadow-2xl: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+    
+    /* Typography */
+    --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
+    --font-serif: 'Playfair Display', Georgia, serif;
+    --font-mono: 'Fira Code', monospace;
+    
+    /* Font Sizes */
+    --text-xs: 0.75rem;
+    --text-sm: 0.875rem;
+    --text-base: 1rem;
+    --text-lg: 1.125rem;
+    --text-xl: 1.25rem;
+    --text-2xl: 1.5rem;
+    --text-3xl: 1.875rem;
+    --text-4xl: 2.25rem;
+    --text-5xl: 3rem;
+    
+    /* Z-Index Scale */
+    --z-dropdown: 100;
+    --z-sticky: 200;
+    --z-fixed: 300;
+    --z-modal-backdrop: 400;
+    --z-modal: 500;
+    --z-popover: 600;
+    --z-tooltip: 700;
+    --z-toast: 800;
+}
+
+/* ==================== LIGHT THEME (Default) ==================== */
+:root,
+[data-theme="light"] {
+    /* Background Colors */
+    --bg-primary: #ffffff;
+    --bg-secondary: #f8fafc;
+    --bg-tertiary: #f1f5f9;
+    --bg-inverse: #1e293b;
+    
+    /* Surface Colors (Cards, Modals) */
+    --surface-primary: #ffffff;
+    --surface-secondary: rgba(248, 250, 252, 0.95);
+    --surface-elevated: #ffffff;
+    --surface-glass: rgba(255, 255, 255, 0.85);
+    
+    /* Text Colors */
+    --text-primary: #1e293b;
+    --text-secondary: #475569;
+    --text-muted: #94a3b8;
+    --text-inverse: #ffffff;
+    --text-link: var(--royal-purple);
+    --text-link-hover: var(--royal-gold);
+    
+    /* Border Colors */
+    --border-primary: #e2e8f0;
+    --border-secondary: #cbd5e1;
+    --border-accent: rgba(212, 175, 55, 0.3);
+    
+    /* Glass Effect */
+    --glass-bg: rgba(255, 255, 255, 0.75);
+    --glass-border: rgba(255, 255, 255, 0.3);
+    --glass-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
+    
+    /* Input Colors */
+    --input-bg: #ffffff;
+    --input-border: #e2e8f0;
+    --input-border-focus: var(--royal-gold);
+    --input-placeholder: #94a3b8;
+    
+    /* Status Colors */
+    --status-success: #10b981;
+    --status-warning: #f59e0b;
+    --status-error: #ef4444;
+    --status-info: #3b82f6;
+    
+    /* Header/Footer */
+    --header-bg: rgba(255, 255, 255, 0.95);
+    --footer-bg: #1e293b;
+    --footer-text: #94a3b8;
+    
+    /* Gradients */
+    --gradient-primary: linear-gradient(135deg, var(--royal-purple), var(--royal-purple-light));
+    --gradient-gold: linear-gradient(135deg, var(--royal-gold), var(--royal-gold-light));
+    --gradient-sunset: linear-gradient(135deg, #ff9a56, #ff6b6b, #feca57);
+    --gradient-ocean: linear-gradient(135deg, #1e3c72, #2a5298);
+    
+    /* Background Gradient */
+    --page-gradient: linear-gradient(135deg, #e0e7ff 0%, #f8fafc 50%, #fef3c7 100%);
+}
+
+/* ==================== DARK THEME ==================== */
+[data-theme="dark"] {
+    /* Background Colors */
+    --bg-primary: #0f172a;
+    --bg-secondary: #1e293b;
+    --bg-tertiary: #334155;
+    --bg-inverse: #f8fafc;
+    
+    /* Surface Colors */
+    --surface-primary: #1e293b;
+    --surface-secondary: rgba(30, 41, 59, 0.95);
+    --surface-elevated: #334155;
+    --surface-glass: rgba(30, 41, 59, 0.85);
+    
+    /* Text Colors */
+    --text-primary: #f1f5f9;
+    --text-secondary: #94a3b8;
+    --text-muted: #64748b;
+    --text-inverse: #1e293b;
+    --text-link: var(--royal-gold);
+    --text-link-hover: var(--royal-gold-light);
+    
+    /* Border Colors */
+    --border-primary: #334155;
+    --border-secondary: #475569;
+    --border-accent: rgba(212, 175, 55, 0.4);
+    
+    /* Glass Effect */
+    --glass-bg: rgba(30, 41, 59, 0.75);
+    --glass-border: rgba(255, 255, 255, 0.1);
+    --glass-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+    
+    /* Input Colors */
+    --input-bg: #1e293b;
+    --input-border: #334155;
+    --input-border-focus: var(--royal-gold);
+    --input-placeholder: #64748b;
+    
+    /* Header/Footer */
+    --header-bg: rgba(15, 23, 42, 0.95);
+    --footer-bg: #0f172a;
+    --footer-text: #64748b;
+    
+    /* Background Gradient */
+    --page-gradient: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+}
+
+/* ==================== THEME TRANSITIONS ==================== */
+* {
+    transition: background-color 0.3s ease,
+                border-color 0.3s ease,
+                color 0.15s ease;
+}
+
+/* Prevent transition on initial load */
+.no-transitions * {
+    transition: none !important;
+}
+
+/* ==================== BASE STYLES ==================== */
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+}
+
+html {
+    font-size: 16px;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    scroll-behavior: smooth;
+}
+
+body {
+    font-family: var(--font-sans);
+    background: var(--page-gradient);
+    color: var(--text-primary);
+    line-height: 1.6;
+    min-height: 100vh;
+}
+
+/* ==================== TYPOGRAPHY ==================== */
+h1, h2, h3, h4, h5, h6 {
+    font-family: var(--font-serif);
+    font-weight: 600;
+    line-height: 1.2;
+    color: var(--text-primary);
+}
+
+h1 { font-size: var(--text-4xl); }
+h2 { font-size: var(--text-3xl); }
+h3 { font-size: var(--text-2xl); }
+h4 { font-size: var(--text-xl); }
+h5 { font-size: var(--text-lg); }
+h6 { font-size: var(--text-base); }
+
+p {
+    margin-bottom: var(--space-md);
+    color: var(--text-secondary);
+}
+
+a {
+    color: var(--text-link);
+    text-decoration: none;
+    transition: color 0.2s ease;
+}
+
+a:hover {
+    color: var(--text-link-hover);
+}
+
+/* ==================== UTILITY CLASSES ==================== */
+
+/* Flex */
+.flex { display: flex; }
+.flex-col { flex-direction: column; }
+.flex-wrap { flex-wrap: wrap; }
+.items-center { align-items: center; }
+.items-start { align-items: flex-start; }
+.items-end { align-items: flex-end; }
+.justify-center { justify-content: center; }
+.justify-between { justify-content: space-between; }
+.justify-end { justify-content: flex-end; }
+.gap-sm { gap: var(--space-sm); }
+.gap-md { gap: var(--space-md); }
+.gap-lg { gap: var(--space-lg); }
+.gap-xl { gap: var(--space-xl); }
+
+/* Grid */
+.grid { display: grid; }
+.grid-cols-2 { grid-template-columns: repeat(2, 1fr); }
+.grid-cols-3 { grid-template-columns: repeat(3, 1fr); }
+.grid-cols-4 { grid-template-columns: repeat(4, 1fr); }
+
+/* Spacing */
+.p-sm { padding: var(--space-sm); }
+.p-md { padding: var(--space-md); }
+.p-lg { padding: var(--space-lg); }
+.p-xl { padding: var(--space-xl); }
+.m-auto { margin: auto; }
+.mt-sm { margin-top: var(--space-sm); }
+.mt-md { margin-top: var(--space-md); }
+.mt-lg { margin-top: var(--space-lg); }
+.mb-sm { margin-bottom: var(--space-sm); }
+.mb-md { margin-bottom: var(--space-md); }
+.mb-lg { margin-bottom: var(--space-lg); }
+
+/* Text */
+.text-center { text-align: center; }
+.text-left { text-align: left; }
+.text-right { text-align: right; }
+.text-sm { font-size: var(--text-sm); }
+.text-lg { font-size: var(--text-lg); }
+.text-xl { font-size: var(--text-xl); }
+.text-muted { color: var(--text-muted); }
+.text-primary { color: var(--text-primary); }
+.text-gold { color: var(--royal-gold); }
+.font-bold { font-weight: 700; }
+.font-medium { font-weight: 500; }
+.uppercase { text-transform: uppercase; }
+.tracking-wide { letter-spacing: 0.05em; }
+
+/* Borders */
+.rounded-sm { border-radius: var(--radius-sm); }
+.rounded-md { border-radius: var(--radius-md); }
+.rounded-lg { border-radius: var(--radius-lg); }
+.rounded-xl { border-radius: var(--radius-xl); }
+.rounded-full { border-radius: var(--radius-full); }
+.border { border: 1px solid var(--border-primary); }
+.border-accent { border: 2px solid var(--border-accent); }
+
+/* Shadows */
+.shadow-sm { box-shadow: var(--shadow-sm); }
+.shadow-md { box-shadow: var(--shadow-md); }
+.shadow-lg { box-shadow: var(--shadow-lg); }
+.shadow-xl { box-shadow: var(--shadow-xl); }
+.shadow-2xl { box-shadow: var(--shadow-2xl); }
+
+/* Width */
+.w-full { width: 100%; }
+.max-w-sm { max-width: 24rem; }
+.max-w-md { max-width: 28rem; }
+.max-w-lg { max-width: 32rem; }
+.max-w-xl { max-width: 36rem; }
+.max-w-2xl { max-width: 42rem; }
+.max-w-4xl { max-width: 56rem; }
+.max-w-6xl { max-width: 72rem; }
+
+/* Display */
+.hidden { display: none; }
+.block { display: block; }
+.inline-block { display: inline-block; }
+.relative { position: relative; }
+.absolute { position: absolute; }
+.fixed { position: fixed; }
+.sticky { position: sticky; }
+.top-0 { top: 0; }
+.left-0 { left: 0; }
+.right-0 { right: 0; }
+.bottom-0 { bottom: 0; }
+.z-10 { z-index: 10; }
+.z-50 { z-index: 50; }
+.z-100 { z-index: 100; }
+
+/* Overflow */
+.overflow-hidden { overflow: hidden; }
+.overflow-auto { overflow: auto; }
+.overflow-x-auto { overflow-x: auto; }
+
+/* Backgrounds */
+.bg-primary { background: var(--bg-primary); }
+.bg-secondary { background: var(--bg-secondary); }
+.bg-surface { background: var(--surface-primary); }
+.bg-glass { 
+    background: var(--glass-bg);
+    backdrop-filter: blur(20px);
+    -webkit-backdrop-filter: blur(20px);
+}
+.bg-gradient-primary { background: var(--gradient-primary); }
+.bg-gradient-gold { background: var(--gradient-gold); }
+
+/* ==================== BUTTONS ==================== */
+.btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-sm);
+    padding: var(--space-sm) var(--space-lg);
+    font-family: var(--font-sans);
+    font-size: var(--text-sm);
+    font-weight: 600;
+    border-radius: var(--radius-md);
+    border: none;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    text-decoration: none;
+}
+
+.btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+.btn-primary {
+    background: var(--gradient-primary);
+    color: white;
+    box-shadow: 0 4px 15px rgba(74, 28, 110, 0.3);
+}
+
+.btn-primary:hover:not(:disabled) {
+    transform: translateY(-2px);
+    box-shadow: 0 8px 25px rgba(74, 28, 110, 0.4);
+}
+
+.btn-gold {
+    background: var(--gradient-gold);
+    color: var(--royal-purple-dark);
+    box-shadow: 0 4px 15px rgba(212, 175, 55, 0.3);
+}
+
+.btn-gold:hover:not(:disabled) {
+    transform: translateY(-2px);
+    box-shadow: 0 8px 25px rgba(212, 175, 55, 0.4);
+}
+
+.btn-outline {
+    background: transparent;
+    border: 2px solid var(--border-accent);
+    color: var(--text-primary);
+}
+
+.btn-outline:hover:not(:disabled) {
+    background: var(--royal-gold);
+    border-color: var(--royal-gold);
+    color: var(--royal-purple-dark);
+}
+
+.btn-ghost {
+    background: transparent;
+    color: var(--text-secondary);
+}
+
+.btn-ghost:hover:not(:disabled) {
+    background: var(--bg-tertiary);
+    color: var(--text-primary);
+}
+
+.btn-icon {
+    width: 40px;
+    height: 40px;
+    padding: 0;
+    border-radius: var(--radius-full);
+}
+
+.btn-lg {
+    padding: var(--space-md) var(--space-xl);
+    font-size: var(--text-base);
+}
+
+.btn-sm {
+    padding: var(--space-xs) var(--space-md);
+    font-size: var(--text-xs);
+}
+
+/* ==================== CARDS ==================== */
+.card {
+    background: var(--surface-primary);
+    border-radius: var(--radius-xl);
+    border: 1px solid var(--border-primary);
+    overflow: hidden;
+}
+
+.card-glass {
+    background: var(--glass-bg);
+    backdrop-filter: blur(20px);
+    -webkit-backdrop-filter: blur(20px);
+    border: 1px solid var(--glass-border);
+    box-shadow: var(--glass-shadow);
+}
+
+.card-header {
+    padding: var(--space-lg);
+    border-bottom: 1px solid var(--border-primary);
+}
+
+.card-body {
+    padding: var(--space-lg);
+}
+
+.card-footer {
+    padding: var(--space-lg);
+    border-top: 1px solid var(--border-primary);
+    background: var(--bg-secondary);
+}
+
+/* ==================== INPUTS ==================== */
+.input {
+    width: 100%;
+    padding: var(--space-sm) var(--space-md);
+    font-family: var(--font-sans);
+    font-size: var(--text-base);
+    background: var(--input-bg);
+    border: 2px solid var(--input-border);
+    border-radius: var(--radius-md);
+    color: var(--text-primary);
+    transition: border-color 0.2s ease, box-shadow 0.2s ease;
+}
+
+.input::placeholder {
+    color: var(--input-placeholder);
+}
+
+.input:focus {
+    outline: none;
+    border-color: var(--input-border-focus);
+    box-shadow: 0 0 0 4px rgba(212, 175, 55, 0.15);
+}
+
+.input-lg {
+    padding: var(--space-md) var(--space-lg);
+    font-size: var(--text-lg);
+}
+
+/* ==================== BADGES ==================== */
+.badge {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-xs);
+    padding: var(--space-xs) var(--space-sm);
+    font-size: var(--text-xs);
+    font-weight: 600;
+    border-radius: var(--radius-full);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+}
+
+.badge-success {
+    background: rgba(16, 185, 129, 0.1);
+    color: var(--status-success);
+}
+
+.badge-warning {
+    background: rgba(245, 158, 11, 0.1);
+    color: var(--status-warning);
+}
+
+.badge-error {
+    background: rgba(239, 68, 68, 0.1);
+    color: var(--status-error);
+}
+
+.badge-info {
+    background: rgba(59, 130, 246, 0.1);
+    color: var(--status-info);
+}
+
+.badge-gold {
+    background: rgba(212, 175, 55, 0.1);
+    color: var(--royal-gold);
+}
+
+/* ==================== RESPONSIVE ==================== */
+@media (max-width: 768px) {
+    :root {
+        --text-4xl: 1.875rem;
+        --text-3xl: 1.5rem;
+        --text-2xl: 1.25rem;
+    }
+    
+    .hide-mobile { display: none !important; }
+    .grid-cols-2 { grid-template-columns: 1fr; }
+    .grid-cols-3 { grid-template-columns: 1fr; }
+    .grid-cols-4 { grid-template-columns: repeat(2, 1fr); }
+}
+
+@media (min-width: 769px) {
+    .hide-desktop { display: none !important; }
+}
diff --git a/static/google-callback.html b/static/google-callback.html
index 987b231..3a65e46 100644
--- a/static/google-callback.html
+++ b/static/google-callback.html
@@ -2,24 +2,133 @@
 <html lang="en">
 <head>
     <meta charset="UTF-8">
-    <title>Authenticating with Google...</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Authenticating - IntelliWeather</title>
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🌦️</text></svg>">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
     <style>
-        body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background-color: #eef5ff; }
-        p { font-size: 1.2rem; color: #555; }
+        :root {
+            --primary-color: #6366f1;
+            --text-dark: #1e293b;
+            --text-light: #64748b;
+            --error-color: #ef4444;
+            --success-color: #10b981;
+        }
+        * { box-sizing: border-box; }
+        body { 
+            font-family: 'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; 
+            display: flex; 
+            justify-content: center; 
+            align-items: center; 
+            min-height: 100vh; 
+            margin: 0; 
+            padding: 1rem;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        }
+        .auth-card {
+            background: rgba(255, 255, 255, 0.95);
+            backdrop-filter: blur(20px);
+            padding: 3rem;
+            border-radius: 24px;
+            box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+            text-align: center;
+            width: 100%;
+            max-width: 400px;
+            border: 1px solid rgba(255, 255, 255, 0.3);
+        }
+        .logo { font-size: 4rem; margin-bottom: 1rem; }
+        .spinner {
+            width: 50px;
+            height: 50px;
+            border: 4px solid #f1f5f9;
+            border-top-color: var(--primary-color);
+            border-radius: 50%;
+            animation: spin 1s linear infinite;
+            margin: 0 auto 1.5rem;
+        }
+        @keyframes spin {
+            to { transform: rotate(360deg); }
+        }
+        #message {
+            font-size: 1.1rem;
+            color: var(--text-dark);
+            font-weight: 500;
+            margin-bottom: 0.5rem;
+        }
+        .sub-message {
+            color: var(--text-light);
+            font-size: 0.9rem;
+        }
+        .error-icon {
+            font-size: 4rem;
+            margin-bottom: 1rem;
+        }
+        .error-text {
+            color: var(--error-color);
+        }
+        .back-link {
+            display: inline-block;
+            margin-top: 1.5rem;
+            padding: 0.75rem 1.5rem;
+            background: var(--primary-color);
+            color: white;
+            text-decoration: none;
+            border-radius: 10px;
+            font-weight: 600;
+            transition: all 0.3s ease;
+        }
+        .back-link:hover {
+            background: #4f46e5;
+            transform: translateY(-2px);
+        }
+        .hidden { display: none; }
     </style>
 </head>
 <body>
-    <p id="message">Processing your login, please wait...</p>
+    <div class="auth-card">
+        <div id="loading-state">
+            <div class="logo">🌦️</div>
+            <div class="spinner"></div>
+            <p id="message">Completing authentication...</p>
+            <p class="sub-message">Please wait while we verify your credentials</p>
+        </div>
+        
+        <div id="error-state" class="hidden">
+            <div class="error-icon">⚠️</div>
+            <p id="error-message" class="error-text">Authentication failed</p>
+            <p class="sub-message">Please try signing in again</p>
+            <a href="./login.html" class="back-link">Back to Login</a>
+        </div>
+    </div>
+    
     <script>
+        // Get API base URL dynamically
+        const API_BASE_URL = window.location.hostname === '127.0.0.1' || window.location.hostname === 'localhost' 
+            ? `http://${window.location.hostname}:8000`
+            : window.location.origin;
+
         window.onload = async function() {
-            const messageDiv = document.getElementById('message');
+            const messageEl = document.getElementById('message');
+            const loadingState = document.getElementById('loading-state');
+            const errorState = document.getElementById('error-state');
+            const errorMessage = document.getElementById('error-message');
+            
             const params = new URLSearchParams(window.location.search);
-            const code = params.get('code'); // Get the authorization code from Google
+            const code = params.get('code');
+
+            function showError(text) {
+                loadingState.classList.add('hidden');
+                errorState.classList.remove('hidden');
+                errorMessage.textContent = text;
+            }
 
             if (code) {
                 try {
-                    // Send the code to our backend to be exchanged for a token
-                    const response = await fetch('http://127.0.0.1:8000/auth/google/exchange', {
+                    messageEl.textContent = 'Exchanging authorization code...';
+                    
+                    const response = await fetch(`${API_BASE_URL}/auth/google/exchange`, {
                         method: 'POST',
                         headers: { 'Content-Type': 'application/json' },
                         body: JSON.stringify({ code: code })
@@ -28,17 +137,19 @@
                     const data = await response.json();
 
                     if (response.ok) {
-                        // Success! Save our app's token and go to the main dashboard
+                        messageEl.textContent = 'Success! Redirecting to dashboard...';
                         localStorage.setItem('weatherAppToken', data.access_token);
-                        window.location.href = './index.html';
+                        setTimeout(() => {
+                            window.location.href = './index.html';
+                        }, 1000);
                     } else {
-                        messageDiv.textContent = 'Error: ' + (data.detail || 'Could not log in.');
+                        showError(data.detail || 'Could not complete authentication');
                     }
                 } catch (error) {
-                    messageDiv.textContent = 'Error: Could not connect to the server.';
+                    showError('Could not connect to the server');
                 }
             } else {
-                messageDiv.textContent = 'Error: No authorization code provided by Google.';
+                showError('No authorization code provided by Google');
             }
         };
     </script>
diff --git a/static/index.html b/static/index.html
index b0c0172..570cb9b 100644
--- a/static/index.html
+++ b/static/index.html
@@ -1,287 +1,1431 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>IntelliWeather Dashboard</title>
-    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🌦️</text></svg>">
-    <style>
-        :root { --primary-color: #007bff; --text-dark: #212529; --text-light: #6c757d; --bg-card: rgba(255, 255, 255, 0.9); --bg-item: rgba(240, 244, 248, 0.85); --border-color: rgba(0, 0, 0, 0.1); }
-        *, *::before, *::after { box-sizing: border-box; }
-        body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; display: flex; justify-content: center; align-items: flex-start; min-height: 100vh; margin: 0; padding: 2rem 1rem; background-color: #eef5ff; background-image: linear-gradient(to top, #70c1ff 0%, #b3e5fc 100%); transition: background-image 1s ease-in-out; }
-        @keyframes slow-pan { 0% { background-position: 0% 50%; } 50% { background-position: 100% 50%; } 100% { background-position: 0% 50%; } }
-        .bg-sunny { background-image: linear-gradient(to top, #ffcc33 0%, #ffb347 100%); background-size: 200% 200%; animation: slow-pan 20s ease infinite; }
-        .bg-cloudy { background-image: linear-gradient(to top, #bdc3c7 0%, #a7b5c1 100%); background-size: 200% 200%; animation: slow-pan 30s ease infinite; }
-        .bg-snowy { background-image: linear-gradient(to top, #e6e9f0 0%, #eef1f5 100%); background-size: 200% 200%; animation: slow-pan 35s ease infinite; }
-        .bg-rainy { background: linear-gradient(to bottom, #738290, #485461); color: white; }
-        .rain { position: fixed; top: 0; left: 0; width: 100%; height: 100%; overflow: hidden; z-index: -1; }
-        .rain .drop { position: absolute; bottom: 100%; width: 2px; height: 80px; background: linear-gradient(to bottom, rgba(255,255,255,0), rgba(255,255,255,0.4)); animation: drop 0.5s linear infinite; }
-        @keyframes drop { 0% {transform: translateY(0vh);} 100% {transform: translateY(110vh);} }
-        .dashboard { background: var(--bg-card); backdrop-filter: blur(12px); padding: 2rem; border-radius: 20px; box-shadow: 0 8px 30px rgba(0, 0, 0, 0.12); width: 100%; max-width: 900px; border: 1px solid rgba(255, 255, 255, 0.2); }
-        .header { display: flex; flex-wrap: wrap; justify-content: space-between; align-items: center; gap: 1rem; margin-bottom: 1rem; }
-        .header-text h1 { margin: 0; color: var(--text-dark); font-size: 1.5rem; }
-        .header-text p { margin: 0; color: var(--text-light); }
-        .search-container { position: relative; }
-        #city-search { font-size: 1rem; padding: 0.5rem; border-radius: 8px; border: 1px solid #ccc; width: 220px; }
-        #search-results { position: absolute; background: white; width: 220px; border-radius: 8px; box-shadow: 0 4px 15px rgba(0,0,0,0.1); max-height: 200px; overflow-y: auto; z-index: 10; border: 1px solid #eee; }
-        .search-item { padding: 0.75rem; cursor: pointer; }
-        .search-item:hover { background-color: #f0f4f8; }
-        #alert-banner { background: #ffc107; color: #333; font-weight: bold; padding: 1rem; text-align: center; border-radius: 10px; margin-bottom: 1rem; display: none; }
-        nav { display: flex; justify-content: center; border-bottom: 1px solid var(--border-color); margin-bottom: 2rem; }
-        nav button { background: none; border: none; padding: 1rem; font-size: 1rem; cursor: pointer; color: var(--text-light); border-bottom: 3px solid transparent; }
-        nav button.active { color: var(--primary-color); border-bottom-color: var(--primary-color); font-weight: bold; }
-        .tab-content { display: none; }
-        .tab-content.active { display: block; animation: fadeIn 0.5s; }
-        @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
-        .now-layout { display: flex; flex-wrap: wrap; gap: 2rem; align-items: center;}
-        .main-display { flex: 1; min-width: 250px; text-align: center; }
-        .main-display .icon { font-size: 6rem; margin: 0; }
-        .main-display .temp { font-size: 5rem; font-weight: bold; margin: 0; color: var(--text-dark); line-height: 1; }
-        .main-display .description { font-size: 1.5rem; color: var(--text-light); margin: 0 0 0.5rem 0; }
-        .details-grid { flex: 1.5; min-width: 300px; display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
-        .detail-item { background: var(--bg-item); padding: 1rem; border-radius: 10px; }
-        .detail-item h3 { margin: 0 0 0.5rem 0; font-size: 0.9rem; color: var(--text-light); font-weight: normal; text-align: left; }
-        .detail-item p { margin: 0; font-size: 1.5rem; font-weight: bold; color: var(--text-dark); text-align: left; }
-        .hourly-forecast-container { display: flex; overflow-x: auto; gap: 1rem; padding-bottom: 1rem; scrollbar-width: thin; }
-        .hourly-item { text-align: center; min-width: 65px; background: var(--bg-item); padding: 1rem 0.5rem; border-radius: 10px; }
-        .hourly-item .time { font-size: 0.9rem; font-weight: bold; }
-        .hourly-item .icon { font-size: 1.8rem; margin: 0.5rem 0; }
-        .hourly-item .temp { font-weight: 500; font-size: 1.1rem; }
-        .daily-forecast-list { display: flex; flex-direction: column; gap: 0.5rem; }
-        .forecast-item { display: grid; grid-template-columns: 1fr 1fr 2fr 1.5fr; align-items: center; padding: 0.75rem; border-radius: 10px; transition: background-color 0.2s; }
-        .forecast-item:hover { background-color: var(--bg-item); }
-        .forecast-item > div { text-align: left; }
-        .forecast-item .day { font-weight: bold; }
-        .forecast-item .icon { font-size: 1.5rem; text-align: center; }
-        .forecast-item .precip { color: #36a2eb; font-size: 0.9rem; }
-        .forecast-item .temps { font-weight: 500; text-align: right; }
-    </style>
-</head>
-<body>
-    <div class="dashboard">
-        <div id="alert-banner"></div>
-        <div class="header">
-            <div class="header-text">
-                <h1 id="location-name">IntelliWeather</h1>
-                <p id="current-date"></p>
-            </div>
-            <div class="search-container">
-                <input type="text" id="city-search" placeholder="Search for a city...">
-                <div id="search-results"></div>
-            </div>
-        </div>
-        
-        <nav>
-            <button class="tab-button active" data-tab="now">Now</button>
-            <button class="tab-button" data-tab="hourly">Hourly</button>
-            <button class="tab-button" data-tab="daily">Daily</button>
-        </nav>
-        
-        <div id="now" class="tab-content active">
-            <div class="now-layout">
-                <div class="main-display">
-                    <p class="icon" id="main-icon">--</p>
-                    <p class="temp" id="main-temp">--°</p>
-                    <p class="description" id="weather-description">--</p>
-                </div>
-                <div class="details-grid">
-                    <div class="detail-item"><h3>Feels Like</h3><p id="feels-like">--°</p></div>
-                    <div class="detail-item"><h3>Humidity</h3><p id="humidity">--%</p></div>
-                    <div class="detail-item"><h3>Wind</h3><p id="wind">-- m/s</p></div>
-                    <div class="detail-item"><h3>UV Index</h3><p id="uv-index">--</p></div>
-                    <div class="detail-item"><h3>Air Quality (AQI)</h3><p id="aqi">--</p></div>
-                    <div class="detail-item"><h3>Precipitation</h3><p id="precip-sum">-- mm</p></div>
-                </div>
-            </div>
-        </div>
-        
-        <div id="hourly" class="tab-content"><div class="hourly-forecast-container" id="hourly-forecast-container"></div></div>
-        
-        <div id="daily" class="tab-content"><div class="daily-forecast-list" id="daily-forecast-container"></div></div>
-    </div>
-
-    <script>
-        document.addEventListener('DOMContentLoaded', () => {
-            const API_BASE_URL = "http://127.0.0.1:8000";
-            let lastCoords = { lat: null, lon: null, name: "Your Location" };
-
-            // --- ALL DOM SELECTORS ---
-            const locationNameEl = document.getElementById('location-name');
-            const searchInput = document.getElementById('city-search');
-            const searchResults = document.getElementById('search-results');
-            const tabs = document.querySelectorAll('.tab-button');
-            const tabContents = document.querySelectorAll('.tab-content');
-
-            // --- EVENT LISTENERS ---
-            tabs.forEach(tab => {
-                tab.addEventListener('click', () => {
-                    tabs.forEach(item => item.classList.remove('active'));
-                    tab.classList.add('active');
-                    tabContents.forEach(content => content.classList.remove('active'));
-                    document.getElementById(tab.dataset.tab).classList.add('active');
-                });
-            });
-
-            let searchTimeout;
-            searchInput.addEventListener('keyup', () => {
-                clearTimeout(searchTimeout);
-                const query = searchInput.value;
-                if (query.length < 3) { searchResults.innerHTML = ''; return; }
-                searchTimeout = setTimeout(async () => {
-                    try {
-                        const response = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${query}&count=5`);
-                        const data = await response.json();
-                        searchResults.innerHTML = '';
-                        if (data.results) {
-                            data.results.forEach(city => {
-                                const item = document.createElement('div');
-                                item.className = 'search-item';
-                                item.textContent = `${city.name}, ${city.admin1 || ''} ${city.country_code}`;
-                                item.onclick = () => {
-                                    fetchAllWeatherData(city.latitude, city.longitude, city.name);
-                                    searchResults.innerHTML = '';
-                                    searchInput.value = '';
-                                };
-                                searchResults.appendChild(item);
-                            });
-                        }
-                    } catch (e) { console.error("Geocoding failed:", e); }
-                }, 500);
-            });
-
-            // --- DATA FETCHING & UI ORCHESTRATION ---
-            async function fetchAllWeatherData(lat, lon, name) {
-                lastCoords = { lat, lon, name };
-                locationNameEl.textContent = `Loading for ${name}...`;
-                try {
-                    const [weatherRes, hourlyRes, dailyRes, aqiAlertsRes] = await Promise.all([
-                        fetch(`${API_BASE_URL}/weather?lat=${lat}&lon=${lon}`),
-                        fetch(`${API_BASE_URL}/hourly?lat=${lat}&lon=${lon}`),
-                        fetch(`${API_BASE_URL}/forecast?lat=${lat}&lon=${lon}`),
-                        fetch(`${API_BASE_URL}/aqi-alerts?lat=${lat}&lon=${lon}`)
-                    ]);
-                    if (!weatherRes.ok || !hourlyRes.ok || !dailyRes.ok || !aqiAlertsRes.ok) throw new Error(`API request failed: ${weatherRes.status}`);
-                    
-                    const weatherData = await weatherRes.json();
-                    const hourlyData = await hourlyRes.json();
-                    const dailyData = await dailyRes.json();
-                    const aqiAlertsData = await aqiAlertsRes.json();
-
-                    updateUI(name, weatherData, hourlyData, dailyData, aqiAlertsData);
-                } catch (error) {
-                    console.error("Failed to fetch weather data:", error);
-                    locationNameEl.textContent = "Failed to load data";
-                }
-            }
-
-            function updateUI(name, current, hourly, daily, aqiAlerts) {
-                locationNameEl.textContent = name;
-                updateBackground(current.weather_code);
-                updateAlertsUI(aqiAlerts.alerts);
-                updateCurrentWeatherUI(current, daily[0]);
-                renderHourlyForecast(hourly);
-                updateDailyForecastUI(daily);
-                updateAqiUI(aqiAlerts.aqi);
-            }
-
-            // --- UI UPDATE FUNCTIONS ---
-            function updateCurrentWeatherUI(current, today) {
-                document.getElementById('main-icon').textContent = getWeatherIcon(current.weather_code);
-                document.getElementById('main-temp').textContent = `${Math.round(current.temperature_c)}°`;
-                document.getElementById('weather-description').textContent = getWeatherDescription(current.weather_code);
-                document.getElementById('feels-like').textContent = `${Math.round(current.apparent_temperature)}°`;
-                document.getElementById('humidity').textContent = `${current.humidity_pct}%`;
-                document.getElementById('wind').textContent = `${current.wind_speed_mps} m/s`;
-                document.getElementById('uv-index').textContent = current.uv_index;
-                document.getElementById('precip-sum').textContent = `${today.precipitation_sum} mm`;
-            }
-
-            function renderHourlyForecast(data) {
-                const container = document.getElementById('hourly-forecast-container');
-                container.innerHTML = '';
-                data.slice(0, 24).forEach(hour => {
-                    const item = document.createElement('div');
-                    item.className = 'hourly-item';
-                    item.innerHTML = `
-                        <div class="time">${new Date(hour.time).getHours()}:00</div>
-                        <div class="icon">${getWeatherIcon(hour.weather_code)}</div>
-                        <div class="temp">${Math.round(hour.temp)}°</div>
-                    `;
-                    container.appendChild(item);
-                });
-            }
-
-            function updateDailyForecastUI(data) {
-                const container = document.getElementById('daily-forecast-container');
-                container.innerHTML = '';
-                data.forEach(day => {
-                    const itemEl = document.createElement('div');
-                    itemEl.className = 'forecast-item';
-                    const date = new Date(day.date);
-                    itemEl.innerHTML = ` <div class="day">${date.toLocaleDateString('en-US', { weekday: 'short' })}</div> <div class="icon">${getWeatherIcon(day.weather_code)}</div> <div class="precip">💧 ${day.precipitation_probability_max}%</div> <div class="temps">${Math.round(day.min_temp)}° / <strong>${Math.round(day.max_temp)}°</strong></div> `;
-                    container.appendChild(itemEl);
-                });
-            }
-
-            function updateAlertsUI(alerts) {
-                const banner = document.getElementById('alert-banner');
-                if (alerts && alerts.length > 0) {
-                    banner.textContent = `⚠️ Alert: ${alerts[0]}`;
-                    banner.style.display = 'block';
-                } else {
-                    banner.style.display = 'none';
-                }
-            }
-
-            function updateAqiUI(data) {
-                const aqiEl = document.getElementById('aqi');
-                if(!data || !data.hourly || !data.hourly.us_aqi || data.hourly.us_aqi.length === 0) {
-                    aqiEl.textContent = 'N/A';
-                    return;
-                };
-                aqiEl.textContent = data.hourly.us_aqi[0];
-            }
-
-            // --- HELPER FUNCTIONS ---
-            function updateBackground(code) {
-                const condition = getWeatherCondition(code);
-                document.body.className = '';
-                document.body.classList.add(condition);
-                let existingRain = document.querySelector('.rain');
-                if (existingRain) existingRain.remove();
-                if (condition === 'bg-rainy') {
-                    const rain = document.createElement('div');
-                    rain.className = 'rain';
-                    for (let i = 0; i < 70; i++) {
-                        const drop = document.createElement('div');
-                        drop.className = 'drop';
-                        drop.style.left = `${Math.random() * 100}%`;
-                        drop.style.animationDelay = `${Math.random() * 2}s`;
-                        drop.style.animationDuration = `${0.2 + Math.random() * 0.3}s`;
-                        rain.appendChild(drop);
-                    }
-                    document.body.prepend(rain);
-                }
-            }
-
-            function getWeatherDescription(code) { const d = { 0: 'Clear', 1: 'Mainly Clear', 2: 'Partly Cloudy', 3: 'Overcast', 45: 'Fog', 48: 'Rime Fog', 61: 'Slight Rain', 63: 'Rain', 65: 'Heavy Rain', 80: 'Rain Showers', 95: 'Thunderstorm' }; return d[code] || 'Cloudy'; }
-            function getWeatherIcon(code) { const c = getWeatherCondition(code); if (c === 'bg-sunny') return '☀️'; if (c === 'bg-cloudy') return '☁️'; if (c === 'bg-rainy') return '🌧️'; if (c === 'bg-snowy') return '❄️'; return '🌍'; }
-            function getWeatherCondition(code) { if (code <= 1) return 'bg-sunny'; if (code <= 3) return 'bg-cloudy'; if (code > 40) return 'bg-rainy'; return 'bg-cloudy'; }
-
-            // --- AUTO-REFRESH ---
-            setInterval(() => { if (lastCoords.lat) { fetchAllWeatherData(lastCoords.lat, lastCoords.lon, lastCoords.name); } }, 15 * 60 * 1000);
-
-            // --- INITIAL LOAD ---
-            document.getElementById('current-date').textContent = new Date().toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' });
-            if (navigator.geolocation) {
-                navigator.geolocation.getCurrentPosition(
-                    position => fetchAllWeatherData(position.coords.latitude, position.coords.longitude, "Your Current Location"),
-                    () => { alert('Could not get your location. Please use the search bar.'); }
-                );
-            } else {
-                alert('Geolocation is not supported. Please use the search bar.');
-            }
-        });
-    </script>
-</body>
-</html>
+<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="theme-color" content="#ffffff">
+    <meta name="description" content="IntelliWeather - Professional weather forecasting with real-time data, hourly and daily forecasts, air quality monitoring, and severe weather alerts.">
+    <meta name="keywords" content="weather, forecast, temperature, humidity, wind, air quality, weather alerts">
+    
+    <!-- Open Graph / Social Preview -->
+    <meta property="og:type" content="website">
+    <meta property="og:title" content="IntelliWeather - Professional Weather Forecasting">
+    <meta property="og:description" content="Get accurate weather forecasts, hourly predictions, and severe weather alerts for any location worldwide.">
+    <meta property="og:image" content="/static/images/og-preview.png">
+    <meta property="twitter:card" content="summary_large_image">
+    
+    <title>IntelliWeather - Professional Weather Forecasting</title>
+    
+    <!-- Favicon -->
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🌤️</text></svg>">
+    
+    <!-- Fonts -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;500;600;700&family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    
+    <!-- Stylesheets -->
+    <link rel="stylesheet" href="/static/css/theme.css">
+    <link rel="stylesheet" href="/static/css/animations.css">
+    
+    <style>
+        /* ==================== LAYOUT ==================== */
+        body {
+            display: flex;
+            flex-direction: column;
+            min-height: 100vh;
+            overflow-x: hidden;
+        }
+        
+        .main-content {
+            flex: 1;
+            padding: 2rem 1rem;
+            padding-top: calc(80px + 2rem); /* Account for fixed header */
+        }
+        
+        .container {
+            max-width: 1200px;
+            margin: 0 auto;
+            width: 100%;
+        }
+        
+        /* ==================== HEADER ==================== */
+        .site-header {
+            position: fixed;
+            top: 0;
+            left: 0;
+            right: 0;
+            height: 80px;
+            background: var(--header-bg);
+            backdrop-filter: blur(20px);
+            -webkit-backdrop-filter: blur(20px);
+            border-bottom: 1px solid var(--border-primary);
+            z-index: var(--z-fixed);
+            transition: transform 0.3s ease, box-shadow 0.3s ease;
+        }
+        
+        .site-header.scrolled {
+            box-shadow: var(--shadow-lg);
+        }
+        
+        .header-container {
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            height: 100%;
+            padding: 0 2rem;
+            max-width: 1400px;
+            margin: 0 auto;
+        }
+        
+        .logo {
+            display: flex;
+            align-items: center;
+            gap: 0.75rem;
+            text-decoration: none;
+        }
+        
+        .logo-icon {
+            font-size: 2rem;
+            filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1));
+        }
+        
+        .logo-text {
+            font-family: var(--font-serif);
+            font-size: 1.5rem;
+            font-weight: 700;
+            color: var(--text-primary);
+        }
+        
+        .logo-text span {
+            color: var(--royal-gold);
+        }
+        
+        .nav-main {
+            display: flex;
+            align-items: center;
+            gap: 2rem;
+        }
+        
+        .nav-links {
+            display: flex;
+            align-items: center;
+            gap: 1.5rem;
+            list-style: none;
+        }
+        
+        .nav-link {
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            padding: 0.5rem 1rem;
+            color: var(--text-secondary);
+            font-weight: 500;
+            font-size: 0.95rem;
+            border-radius: var(--radius-md);
+            transition: all 0.2s ease;
+        }
+        
+        .nav-link:hover {
+            color: var(--text-primary);
+            background: var(--bg-tertiary);
+        }
+        
+        .nav-link.active {
+            color: var(--royal-gold);
+            background: rgba(212, 175, 55, 0.1);
+        }
+        
+        .nav-link-icon {
+            font-size: 1.1rem;
+        }
+        
+        .header-actions {
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+        }
+        
+        .theme-toggle {
+            width: 44px;
+            height: 44px;
+            border-radius: var(--radius-full);
+            border: 2px solid var(--border-primary);
+            background: var(--bg-secondary);
+            cursor: pointer;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-size: 1.25rem;
+            transition: all 0.2s ease;
+        }
+        
+        .theme-toggle:hover {
+            border-color: var(--royal-gold);
+            background: rgba(212, 175, 55, 0.1);
+        }
+        
+        .mobile-menu-toggle {
+            display: none;
+            width: 44px;
+            height: 44px;
+            border: none;
+            background: transparent;
+            cursor: pointer;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            gap: 5px;
+        }
+        
+        .mobile-menu-toggle span {
+            display: block;
+            width: 24px;
+            height: 2px;
+            background: var(--text-primary);
+            border-radius: 2px;
+            transition: all 0.3s ease;
+        }
+        
+        /* ==================== CONNECTION STATUS ==================== */
+        .connection-status {
+            position: fixed;
+            top: 100px;
+            right: 1.5rem;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            padding: 0.5rem 1rem;
+            background: var(--glass-bg);
+            backdrop-filter: blur(20px);
+            border: 1px solid var(--glass-border);
+            border-radius: var(--radius-full);
+            font-size: 0.85rem;
+            font-weight: 500;
+            color: var(--text-secondary);
+            z-index: var(--z-sticky);
+            box-shadow: var(--shadow-md);
+            transition: all 0.3s ease;
+        }
+        
+        .connection-dot {
+            width: 8px;
+            height: 8px;
+            border-radius: 50%;
+            background: var(--status-success);
+            box-shadow: 0 0 8px var(--status-success);
+            animation: pulse 2s ease infinite;
+        }
+        
+        .connection-status.connecting .connection-dot {
+            background: var(--status-warning);
+            box-shadow: 0 0 8px var(--status-warning);
+            animation: blink 0.5s ease infinite;
+        }
+        
+        .connection-status.disconnected .connection-dot {
+            background: var(--status-error);
+            box-shadow: 0 0 8px var(--status-error);
+            animation: none;
+        }
+        
+        @keyframes blink {
+            0%, 100% { opacity: 1; }
+            50% { opacity: 0.3; }
+        }
+        
+        /* ==================== DASHBOARD ==================== */
+        .dashboard {
+            background: var(--surface-primary);
+            border-radius: var(--radius-2xl);
+            box-shadow: var(--shadow-2xl);
+            overflow: hidden;
+            animation: fadeInUp 0.6s var(--ease-out-expo);
+        }
+        
+        .dashboard-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            flex-wrap: wrap;
+            gap: 1.5rem;
+            padding: 2rem;
+            border-bottom: 1px solid var(--border-primary);
+        }
+        
+        .location-info h1 {
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            font-size: var(--text-3xl);
+            margin-bottom: 0.25rem;
+        }
+        
+        .location-info h1::before {
+            content: '📍';
+            font-size: 1.5rem;
+        }
+        
+        .location-info p {
+            color: var(--text-muted);
+            margin: 0;
+        }
+        
+        /* Search Box */
+        .search-container {
+            position: relative;
+            width: 320px;
+        }
+        
+        .search-input {
+            width: 100%;
+            padding: 0.9rem 1rem 0.9rem 3rem;
+            font-size: 0.95rem;
+            background: var(--input-bg);
+            border: 2px solid var(--input-border);
+            border-radius: var(--radius-lg);
+            color: var(--text-primary);
+            transition: all 0.2s ease;
+        }
+        
+        .search-input:focus {
+            outline: none;
+            border-color: var(--input-border-focus);
+            box-shadow: 0 0 0 4px rgba(212, 175, 55, 0.15);
+        }
+        
+        .search-icon {
+            position: absolute;
+            left: 1rem;
+            top: 50%;
+            transform: translateY(-50%);
+            font-size: 1.1rem;
+            pointer-events: none;
+        }
+        
+        #search-results {
+            position: absolute;
+            top: 100%;
+            left: 0;
+            right: 0;
+            margin-top: 0.5rem;
+            background: var(--surface-primary);
+            border: 1px solid var(--border-primary);
+            border-radius: var(--radius-lg);
+            box-shadow: var(--shadow-xl);
+            max-height: 320px;
+            overflow-y: auto;
+            z-index: var(--z-dropdown);
+            display: none;
+        }
+        
+        .search-item {
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+            padding: 1rem 1.25rem;
+            cursor: pointer;
+            border-bottom: 1px solid var(--border-primary);
+            transition: all 0.2s ease;
+        }
+        
+        .search-item:last-child {
+            border-bottom: none;
+        }
+        
+        .search-item:hover,
+        .search-item.selected {
+            background: rgba(212, 175, 55, 0.1);
+        }
+        
+        .search-item-icon {
+            font-size: 1.25rem;
+        }
+        
+        .search-item-content {
+            flex: 1;
+        }
+        
+        .search-item-name {
+            font-weight: 600;
+            color: var(--text-primary);
+        }
+        
+        .search-item-detail {
+            font-size: 0.85rem;
+            color: var(--text-muted);
+        }
+        
+        .search-item-arrow {
+            color: var(--royal-gold);
+            opacity: 0;
+            transform: translateX(-10px);
+            transition: all 0.2s ease;
+        }
+        
+        .search-item:hover .search-item-arrow,
+        .search-item.selected .search-item-arrow {
+            opacity: 1;
+            transform: translateX(0);
+        }
+        
+        .search-loading {
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            gap: 0.75rem;
+            padding: 1.5rem;
+            color: var(--text-muted);
+        }
+        
+        .search-loading-spinner {
+            width: 20px;
+            height: 20px;
+            border: 2px solid var(--border-primary);
+            border-top-color: var(--royal-gold);
+            border-radius: 50%;
+            animation: spin 0.8s linear infinite;
+        }
+        
+        @keyframes spin {
+            to { transform: rotate(360deg); }
+        }
+        
+        /* ==================== TABS ==================== */
+        .tab-nav {
+            display: flex;
+            justify-content: center;
+            gap: 0.5rem;
+            padding: 1rem 2rem;
+            background: var(--bg-secondary);
+        }
+        
+        .tab-btn {
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            padding: 0.9rem 2rem;
+            background: transparent;
+            border: none;
+            font-family: inherit;
+            font-size: 0.95rem;
+            font-weight: 500;
+            color: var(--text-secondary);
+            cursor: pointer;
+            border-radius: var(--radius-lg);
+            transition: all 0.3s ease;
+        }
+        
+        .tab-btn:hover:not(.active) {
+            color: var(--text-primary);
+            background: var(--surface-primary);
+        }
+        
+        .tab-btn.active {
+            color: white;
+            background: var(--gradient-primary);
+            box-shadow: 0 4px 15px rgba(74, 28, 110, 0.3);
+        }
+        
+        .tab-content {
+            display: none;
+            padding: 2rem;
+            animation: fadeInUp 0.4s ease;
+        }
+        
+        .tab-content.active {
+            display: block;
+        }
+        
+        /* ==================== CURRENT WEATHER ==================== */
+        .now-layout {
+            display: grid;
+            grid-template-columns: 1fr 1.5fr;
+            gap: 2rem;
+            align-items: center;
+        }
+        
+        .main-weather {
+            text-align: center;
+            padding: 2.5rem 2rem;
+            background: linear-gradient(145deg, rgba(212, 175, 55, 0.08), rgba(123, 67, 151, 0.08));
+            border-radius: var(--radius-xl);
+            border: 1px solid var(--border-accent);
+            position: relative;
+            overflow: hidden;
+        }
+        
+        .main-weather::before {
+            content: '';
+            position: absolute;
+            top: -50%;
+            left: -50%;
+            width: 200%;
+            height: 200%;
+            background: linear-gradient(45deg, transparent 40%, rgba(255, 255, 255, 0.1) 50%, transparent 60%);
+            animation: shimmer 3s ease-in-out infinite;
+        }
+        
+        .weather-icon {
+            font-size: 8rem;
+            filter: drop-shadow(0 10px 20px rgba(0, 0, 0, 0.1));
+            animation: weatherBounce 3s ease-in-out infinite;
+            position: relative;
+            z-index: 1;
+        }
+        
+        .temperature {
+            font-family: var(--font-serif);
+            font-size: 5rem;
+            font-weight: 700;
+            background: linear-gradient(135deg, var(--text-primary), var(--royal-purple));
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            background-clip: text;
+            margin: 0.5rem 0;
+            position: relative;
+            z-index: 1;
+        }
+        
+        .weather-description {
+            font-size: 1.25rem;
+            color: var(--text-secondary);
+            font-weight: 500;
+            text-transform: capitalize;
+            position: relative;
+            z-index: 1;
+        }
+        
+        /* Weather Details Grid */
+        .details-grid {
+            display: grid;
+            grid-template-columns: repeat(2, 1fr);
+            gap: 1rem;
+        }
+        
+        .detail-card {
+            background: var(--bg-secondary);
+            padding: 1.25rem;
+            border-radius: var(--radius-lg);
+            border: 1px solid transparent;
+            transition: all 0.3s ease;
+        }
+        
+        .detail-card:hover {
+            background: var(--surface-primary);
+            border-color: var(--border-accent);
+            transform: translateY(-4px);
+            box-shadow: var(--shadow-lg);
+        }
+        
+        .detail-card h3 {
+            font-size: 0.8rem;
+            font-weight: 600;
+            color: var(--text-muted);
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+            margin-bottom: 0.5rem;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+        }
+        
+        .detail-card .value {
+            font-family: var(--font-serif);
+            font-size: 1.75rem;
+            font-weight: 600;
+            color: var(--text-primary);
+        }
+        
+        .detail-card .unit {
+            font-family: var(--font-sans);
+            font-size: 0.9rem;
+            font-weight: 500;
+            color: var(--text-muted);
+        }
+        
+        /* ==================== HOURLY FORECAST ==================== */
+        .hourly-container {
+            display: flex;
+            gap: 1rem;
+            overflow-x: auto;
+            padding: 1rem 0.5rem;
+            scrollbar-width: thin;
+            scrollbar-color: var(--royal-gold) var(--bg-secondary);
+        }
+        
+        .hourly-container::-webkit-scrollbar {
+            height: 8px;
+        }
+        
+        .hourly-container::-webkit-scrollbar-track {
+            background: var(--bg-secondary);
+            border-radius: 10px;
+        }
+        
+        .hourly-container::-webkit-scrollbar-thumb {
+            background: var(--gradient-gold);
+            border-radius: 10px;
+        }
+        
+        .hourly-item {
+            text-align: center;
+            min-width: 90px;
+            padding: 1.25rem 1rem;
+            background: var(--bg-secondary);
+            border-radius: var(--radius-lg);
+            border: 2px solid transparent;
+            transition: all 0.3s ease;
+        }
+        
+        .hourly-item:hover {
+            background: var(--surface-primary);
+            border-color: var(--royal-gold);
+            transform: translateY(-6px);
+            box-shadow: 0 15px 35px rgba(212, 175, 55, 0.2);
+        }
+        
+        .hourly-item .time {
+            font-size: 0.85rem;
+            font-weight: 600;
+            color: var(--text-secondary);
+        }
+        
+        .hourly-item .icon {
+            font-size: 2.2rem;
+            margin: 0.75rem 0;
+        }
+        
+        .hourly-item .temp {
+            font-family: var(--font-serif);
+            font-weight: 700;
+            font-size: 1.2rem;
+            color: var(--text-primary);
+        }
+        
+        /* ==================== DAILY FORECAST ==================== */
+        .daily-list {
+            display: flex;
+            flex-direction: column;
+            gap: 0.75rem;
+        }
+        
+        .daily-item {
+            display: grid;
+            grid-template-columns: 1.2fr 0.8fr 1.5fr 1.2fr;
+            align-items: center;
+            padding: 1.1rem 1.5rem;
+            background: var(--bg-secondary);
+            border-radius: var(--radius-lg);
+            border: 2px solid transparent;
+            transition: all 0.3s ease;
+        }
+        
+        .daily-item:hover {
+            background: var(--surface-primary);
+            border-color: var(--royal-gold);
+            transform: translateX(10px);
+            box-shadow: var(--shadow-lg);
+        }
+        
+        .daily-item .day {
+            font-family: var(--font-serif);
+            font-weight: 600;
+            color: var(--text-primary);
+        }
+        
+        .daily-item .icon {
+            font-size: 1.8rem;
+            text-align: center;
+        }
+        
+        .daily-item .precip {
+            color: var(--accent-blue);
+            font-size: 0.9rem;
+            font-weight: 500;
+            display: flex;
+            align-items: center;
+            gap: 0.3rem;
+        }
+        
+        .daily-item .temps {
+            text-align: right;
+            font-weight: 600;
+        }
+        
+        .daily-item .temps .high {
+            color: var(--text-primary);
+            font-family: var(--font-serif);
+        }
+        
+        .daily-item .temps .low {
+            color: var(--text-muted);
+        }
+        
+        /* ==================== LOADING & ERROR STATES ==================== */
+        .loading-overlay {
+            position: absolute;
+            inset: 0;
+            background: var(--surface-glass);
+            backdrop-filter: blur(8px);
+            display: flex;
+            flex-direction: column;
+            justify-content: center;
+            align-items: center;
+            border-radius: var(--radius-2xl);
+            z-index: 100;
+            opacity: 0;
+            visibility: hidden;
+            transition: all 0.3s ease;
+        }
+        
+        .loading-overlay.active {
+            opacity: 1;
+            visibility: visible;
+        }
+        
+        .loading-spinner {
+            width: 60px;
+            height: 60px;
+            border: 4px solid var(--bg-secondary);
+            border-top-color: var(--royal-gold);
+            border-radius: 50%;
+            animation: spin 1s linear infinite;
+        }
+        
+        .loading-text {
+            margin-top: 1.5rem;
+            color: var(--text-secondary);
+            font-weight: 500;
+        }
+        
+        .error-state {
+            text-align: center;
+            padding: 3rem;
+        }
+        
+        .error-state .error-icon {
+            font-size: 5rem;
+            margin-bottom: 1rem;
+        }
+        
+        .error-state h3 {
+            font-size: 1.5rem;
+            margin-bottom: 0.5rem;
+        }
+        
+        .error-state p {
+            margin-bottom: 1.5rem;
+        }
+        
+        /* ==================== SKELETON LOADERS ==================== */
+        .skeleton {
+            background: linear-gradient(90deg, var(--bg-secondary) 25%, var(--bg-tertiary) 50%, var(--bg-secondary) 75%);
+            background-size: 200% 100%;
+            animation: skeletonShimmer 1.5s ease infinite;
+            border-radius: var(--radius-md);
+        }
+        
+        .skeleton-text {
+            height: 1em;
+            margin-bottom: 0.5em;
+        }
+        
+        .skeleton-title {
+            height: 2em;
+            width: 60%;
+            margin-bottom: 1em;
+        }
+        
+        .skeleton-card {
+            height: 150px;
+        }
+        
+        /* ==================== FOOTER ==================== */
+        .site-footer {
+            background: var(--footer-bg);
+            color: var(--footer-text);
+            padding: 4rem 2rem 2rem;
+            margin-top: auto;
+        }
+        
+        .footer-container {
+            max-width: 1200px;
+            margin: 0 auto;
+        }
+        
+        .footer-grid {
+            display: grid;
+            grid-template-columns: 2fr 1fr 1fr 1fr;
+            gap: 3rem;
+            margin-bottom: 3rem;
+        }
+        
+        .footer-brand .logo {
+            margin-bottom: 1rem;
+        }
+        
+        .footer-brand .logo-text {
+            color: white;
+        }
+        
+        .footer-brand p {
+            color: var(--footer-text);
+            font-size: 0.95rem;
+            line-height: 1.6;
+            margin-bottom: 1.5rem;
+        }
+        
+        .social-links {
+            display: flex;
+            gap: 1rem;
+        }
+        
+        .social-link {
+            width: 40px;
+            height: 40px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            background: rgba(255, 255, 255, 0.1);
+            border-radius: var(--radius-md);
+            font-size: 1.25rem;
+            transition: all 0.2s ease;
+        }
+        
+        .social-link:hover {
+            background: var(--royal-gold);
+            transform: translateY(-3px);
+        }
+        
+        .footer-column h4 {
+            color: white;
+            font-size: 1rem;
+            font-weight: 600;
+            margin-bottom: 1.5rem;
+            font-family: var(--font-sans);
+        }
+        
+        .footer-links {
+            list-style: none;
+        }
+        
+        .footer-links li {
+            margin-bottom: 0.75rem;
+        }
+        
+        .footer-links a {
+            color: var(--footer-text);
+            font-size: 0.9rem;
+            transition: color 0.2s ease;
+        }
+        
+        .footer-links a:hover {
+            color: var(--royal-gold);
+        }
+        
+        .footer-bottom {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            padding-top: 2rem;
+            border-top: 1px solid rgba(255, 255, 255, 0.1);
+        }
+        
+        .footer-bottom p {
+            font-size: 0.85rem;
+            margin: 0;
+        }
+        
+        .footer-bottom a {
+            color: var(--royal-gold);
+        }
+        
+        .language-select {
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            padding: 0.5rem 1rem;
+            background: rgba(255, 255, 255, 0.1);
+            border: 1px solid rgba(255, 255, 255, 0.2);
+            border-radius: var(--radius-md);
+            color: white;
+            font-size: 0.9rem;
+            cursor: pointer;
+        }
+        
+        .language-select:hover {
+            background: rgba(255, 255, 255, 0.15);
+        }
+        
+        /* ==================== BACKGROUND EFFECTS ==================== */
+        .bg-effects {
+            position: fixed;
+            inset: 0;
+            pointer-events: none;
+            z-index: -1;
+            overflow: hidden;
+        }
+        
+        .bg-orb {
+            position: absolute;
+            border-radius: 50%;
+            filter: blur(80px);
+            opacity: 0.3;
+            animation: float 20s ease-in-out infinite;
+        }
+        
+        .bg-orb-1 {
+            width: 500px;
+            height: 500px;
+            background: linear-gradient(135deg, var(--royal-purple), var(--royal-gold));
+            top: -150px;
+            left: -150px;
+        }
+        
+        .bg-orb-2 {
+            width: 400px;
+            height: 400px;
+            background: linear-gradient(135deg, var(--accent-cyan), var(--royal-purple-light));
+            bottom: -100px;
+            right: -100px;
+            animation-delay: -7s;
+        }
+        
+        .bg-orb-3 {
+            width: 300px;
+            height: 300px;
+            background: linear-gradient(135deg, var(--royal-gold), var(--accent-orange));
+            top: 40%;
+            left: 60%;
+            animation-delay: -14s;
+        }
+        
+        /* ==================== RESPONSIVE ==================== */
+        @media (max-width: 1024px) {
+            .footer-grid {
+                grid-template-columns: repeat(2, 1fr);
+            }
+        }
+        
+        @media (max-width: 768px) {
+            .site-header {
+                height: 70px;
+            }
+            
+            .header-container {
+                padding: 0 1rem;
+            }
+            
+            .nav-main {
+                display: none;
+            }
+            
+            .mobile-menu-toggle {
+                display: flex;
+            }
+            
+            .main-content {
+                padding: 1rem;
+                padding-top: calc(70px + 1rem);
+            }
+            
+            .dashboard-header {
+                flex-direction: column;
+                align-items: flex-start;
+            }
+            
+            .search-container {
+                width: 100%;
+            }
+            
+            .tab-nav {
+                flex-wrap: wrap;
+                padding: 1rem;
+            }
+            
+            .tab-btn {
+                padding: 0.75rem 1.25rem;
+                font-size: 0.9rem;
+            }
+            
+            .now-layout {
+                grid-template-columns: 1fr;
+            }
+            
+            .details-grid {
+                grid-template-columns: 1fr;
+            }
+            
+            .daily-item {
+                grid-template-columns: 1fr 0.6fr 1fr 1fr;
+                padding: 0.9rem 1rem;
+            }
+            
+            .footer-grid {
+                grid-template-columns: 1fr;
+                gap: 2rem;
+            }
+            
+            .footer-bottom {
+                flex-direction: column;
+                gap: 1rem;
+                text-align: center;
+            }
+            
+            .connection-status {
+                top: 80px;
+                right: 1rem;
+                font-size: 0.8rem;
+                padding: 0.4rem 0.8rem;
+            }
+            
+            .temperature {
+                font-size: 4rem;
+            }
+            
+            .weather-icon {
+                font-size: 6rem;
+            }
+        }
+    </style>
+</head>
+<body>
+    <!-- Background Effects -->
+    <div class="bg-effects">
+        <div class="bg-orb bg-orb-1"></div>
+        <div class="bg-orb bg-orb-2"></div>
+        <div class="bg-orb bg-orb-3"></div>
+    </div>
+    
+    <!-- Header -->
+    <header class="site-header" id="site-header">
+        <div class="header-container">
+            <a href="/" class="logo">
+                <span class="logo-icon">🌤️</span>
+                <span class="logo-text">Intelli<span>Weather</span></span>
+            </a>
+            
+            <nav class="nav-main">
+                <ul class="nav-links">
+                    <li><a href="/" class="nav-link active"><span class="nav-link-icon">🏠</span> Dashboard</a></li>
+                    <li><a href="/maps" class="nav-link"><span class="nav-link-icon">🗺️</span> Maps</a></li>
+                    <li><a href="/alerts" class="nav-link"><span class="nav-link-icon">⚠️</span> Alerts</a></li>
+                    <li><a href="/historical" class="nav-link"><span class="nav-link-icon">📊</span> Historical</a></li>
+                    <li><a href="/docs" class="nav-link"><span class="nav-link-icon">📚</span> API Docs</a></li>
+                </ul>
+            </nav>
+            
+            <div class="header-actions">
+                <button class="theme-toggle" id="theme-toggle" aria-label="Toggle theme">
+                    <span class="theme-icon">🌙</span>
+                </button>
+                <a href="/login.html" class="btn btn-outline hide-mobile">Sign In</a>
+                <a href="/signup.html" class="btn btn-primary hide-mobile">Get Started</a>
+                <button class="mobile-menu-toggle" id="mobile-menu-toggle" aria-label="Menu">
+                    <span></span>
+                    <span></span>
+                    <span></span>
+                </button>
+            </div>
+        </div>
+    </header>
+    
+    <!-- Connection Status -->
+    <div class="connection-status connecting" id="connection-status">
+        <span class="connection-dot"></span>
+        <span class="connection-text">Connecting...</span>
+    </div>
+    
+    <!-- Main Content -->
+    <main class="main-content">
+        <div class="container">
+            <div class="dashboard" id="dashboard">
+                <!-- Loading Overlay -->
+                <div class="loading-overlay" id="loading-overlay">
+                    <div class="loading-spinner"></div>
+                    <p class="loading-text" id="loading-text">Getting your location...</p>
+                </div>
+                
+                <!-- Dashboard Header -->
+                <header class="dashboard-header">
+                    <div class="location-info">
+                        <h1 id="location-name">Loading...</h1>
+                        <p id="current-date"></p>
+                    </div>
+                    <div class="search-container">
+                        <span class="search-icon">🔍</span>
+                        <input type="text" id="city-search" class="search-input" placeholder="Search for a city..." autocomplete="off">
+                        <div id="search-results"></div>
+                    </div>
+                </header>
+                
+                <!-- Navigation Tabs -->
+                <nav class="tab-nav">
+                    <button class="tab-btn active" data-tab="now">☀️ Now</button>
+                    <button class="tab-btn" data-tab="hourly">⏱️ Hourly</button>
+                    <button class="tab-btn" data-tab="daily">📅 7-Day</button>
+                </nav>
+                
+                <!-- Tab Content: Current Weather -->
+                <div id="now" class="tab-content active">
+                    <div class="now-layout">
+                        <div class="main-weather shimmer-effect">
+                            <div class="weather-icon" id="main-icon">🌍</div>
+                            <div class="temperature" id="main-temp">--°</div>
+                            <div class="weather-description" id="main-description">Loading weather...</div>
+                        </div>
+                        <div class="details-grid stagger-children">
+                            <div class="detail-card">
+                                <h3>🌡️ Feels Like</h3>
+                                <p><span class="value" id="feels-like">--</span><span class="unit">°C</span></p>
+                            </div>
+                            <div class="detail-card">
+                                <h3>💧 Humidity</h3>
+                                <p><span class="value" id="humidity">--</span><span class="unit">%</span></p>
+                            </div>
+                            <div class="detail-card">
+                                <h3>🌬️ Wind</h3>
+                                <p><span class="value" id="wind">--</span><span class="unit"> m/s</span></p>
+                            </div>
+                            <div class="detail-card">
+                                <h3>☀️ UV Index</h3>
+                                <p><span class="value" id="uv-index">--</span></p>
+                            </div>
+                            <div class="detail-card">
+                                <h3>🫁 Air Quality</h3>
+                                <p><span class="value" id="aqi">--</span><span class="unit"> AQI</span></p>
+                            </div>
+                            <div class="detail-card">
+                                <h3>🌧️ Precipitation</h3>
+                                <p><span class="value" id="precip">--</span><span class="unit"> mm</span></p>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+                
+                <!-- Tab Content: Hourly Forecast -->
+                <div id="hourly" class="tab-content">
+                    <div class="hourly-container" id="hourly-container"></div>
+                </div>
+                
+                <!-- Tab Content: Daily Forecast -->
+                <div id="daily" class="tab-content">
+                    <div class="daily-list" id="daily-container"></div>
+                </div>
+                
+                <!-- Error State -->
+                <div id="error-state" class="error-state" style="display: none;">
+                    <div class="error-icon">⚠️</div>
+                    <h3>Unable to load weather data</h3>
+                    <p>Please check your connection and try again.</p>
+                    <button class="btn btn-primary btn-lg" onclick="retryFetch()">Try Again</button>
+                </div>
+            </div>
+        </div>
+    </main>
+    
+    <!-- Footer -->
+    <footer class="site-footer">
+        <div class="footer-container">
+            <div class="footer-grid">
+                <div class="footer-brand">
+                    <a href="/" class="logo">
+                        <span class="logo-icon">🌤️</span>
+                        <span class="logo-text">Intelli<span>Weather</span></span>
+                    </a>
+                    <p>Professional weather forecasting powered by advanced meteorological data. Get accurate forecasts, severe weather alerts, and historical weather data for any location worldwide.</p>
+                    <div class="social-links">
+                        <a href="#" class="social-link" aria-label="Twitter">🐦</a>
+                        <a href="#" class="social-link" aria-label="Facebook">📘</a>
+                        <a href="#" class="social-link" aria-label="Instagram">📷</a>
+                        <a href="https://github.com/CodersAcademy006/Weather-API" class="social-link" aria-label="GitHub">💻</a>
+                    </div>
+                </div>
+                
+                <div class="footer-column">
+                    <h4>Products</h4>
+                    <ul class="footer-links">
+                        <li><a href="/docs">Weather API</a></li>
+                        <li><a href="/maps">Weather Maps</a></li>
+                        <li><a href="/alerts">Severe Alerts</a></li>
+                        <li><a href="/historical">Historical Data</a></li>
+                        <li><a href="/widgets">Weather Widgets</a></li>
+                    </ul>
+                </div>
+                
+                <div class="footer-column">
+                    <h4>Resources</h4>
+                    <ul class="footer-links">
+                        <li><a href="/docs">Documentation</a></li>
+                        <li><a href="/docs#api-reference">API Reference</a></li>
+                        <li><a href="/pricing">Pricing</a></li>
+                        <li><a href="/status">System Status</a></li>
+                        <li><a href="/changelog">Changelog</a></li>
+                    </ul>
+                </div>
+                
+                <div class="footer-column">
+                    <h4>Company</h4>
+                    <ul class="footer-links">
+                        <li><a href="/about">About Us</a></li>
+                        <li><a href="/blog">Blog</a></li>
+                        <li><a href="/careers">Careers</a></li>
+                        <li><a href="/contact">Contact</a></li>
+                        <li><a href="/privacy">Privacy Policy</a></li>
+                    </ul>
+                </div>
+            </div>
+            
+            <div class="footer-bottom">
+                <p>© 2024 IntelliWeather. All rights reserved. Powered by <a href="https://open-meteo.com" target="_blank">Open-Meteo</a></p>
+                <div class="language-select" id="language-select">
+                    <span>🌐</span>
+                    <span>English</span>
+                    <span>▼</span>
+                </div>
+            </div>
+        </div>
+    </footer>
+    
+    <!-- Scripts -->
+    <script src="/static/js/theme.js"></script>
+    <script src="/static/js/motion.js"></script>
+    <script src="/static/js/search.js"></script>
+    
+    <script>
+        // ==================== CONFIGURATION ====================
+        const API_BASE_URL = window.location.hostname === '127.0.0.1' || window.location.hostname === 'localhost' 
+            ? `http://${window.location.hostname}:8000`
+            : window.location.origin;
+        
+        // ==================== STATE ====================
+        let currentLat = null, currentLon = null, currentLocationName = "Your Location";
+        
+        // ==================== DOM ELEMENTS ====================
+        const $ = id => document.getElementById(id);
+        const loadingOverlay = $('loading-overlay');
+        const loadingText = $('loading-text');
+        const connectionStatus = $('connection-status');
+        const errorState = $('error-state');
+        const themeToggle = $('theme-toggle');
+        const siteHeader = $('site-header');
+        
+        // ==================== WEATHER DATA ====================
+        const weatherIcons = {
+            0: '☀️', 1: '🌤️', 2: '⛅', 3: '☁️',
+            45: '🌫️', 48: '🌫️',
+            51: '🌦️', 53: '🌧️', 55: '🌧️',
+            61: '🌧️', 63: '🌧️', 65: '⛈️',
+            71: '🌨️', 73: '🌨️', 75: '❄️',
+            80: '🌦️', 81: '🌧️', 82: '⛈️',
+            95: '⛈️', 96: '⛈️', 99: '🌩️'
+        };
+        
+        const weatherDescriptions = {
+            0: 'Clear sky', 1: 'Mainly clear', 2: 'Partly cloudy', 3: 'Overcast',
+            45: 'Foggy', 48: 'Rime fog',
+            51: 'Light drizzle', 53: 'Moderate drizzle', 55: 'Dense drizzle',
+            61: 'Slight rain', 63: 'Moderate rain', 65: 'Heavy rain',
+            71: 'Slight snow', 73: 'Moderate snow', 75: 'Heavy snow',
+            80: 'Rain showers', 81: 'Moderate showers', 82: 'Violent showers',
+            95: 'Thunderstorm', 96: 'Thunderstorm with hail', 99: 'Severe thunderstorm'
+        };
+        
+        // ==================== HELPERS ====================
+        function setLoading(show, text = 'Loading...') {
+            loadingOverlay.classList.toggle('active', show);
+            loadingText.textContent = text;
+        }
+        
+        function setConnectionStatus(status) {
+            connectionStatus.className = `connection-status ${status}`;
+            const texts = { connected: 'Connected', connecting: 'Connecting...', disconnected: 'Disconnected' };
+            connectionStatus.querySelector('.connection-text').textContent = texts[status] || 'Unknown';
+        }
+        
+        function formatDate(date = new Date()) {
+            return date.toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' });
+        }
+        
+        function formatHour(isoString) {
+            return new Date(isoString).toLocaleTimeString('en-US', { hour: 'numeric', hour12: true });
+        }
+        
+        function formatDay(dateString) {
+            const date = new Date(dateString);
+            const today = new Date();
+            if (date.toDateString() === today.toDateString()) return 'Today';
+            const tomorrow = new Date(today);
+            tomorrow.setDate(today.getDate() + 1);
+            if (date.toDateString() === tomorrow.toDateString()) return 'Tomorrow';
+            return date.toLocaleDateString('en-US', { weekday: 'short', month: 'short', day: 'numeric' });
+        }
+        
+        async function fetchWithRetry(url, options = {}, retries = 3) {
+            for (let i = 0; i < retries; i++) {
+                try {
+                    setConnectionStatus('connecting');
+                    const response = await fetch(url, { ...options, signal: AbortSignal.timeout(10000) });
+                    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+                    setConnectionStatus('connected');
+                    return response;
+                } catch (error) {
+                    console.warn(`Attempt ${i + 1} failed:`, error.message);
+                    if (i === retries - 1) {
+                        setConnectionStatus('disconnected');
+                        throw error;
+                    }
+                    await new Promise(r => setTimeout(r, 2000 * (i + 1)));
+                }
+            }
+        }
+        
+        // ==================== DATA FETCHING ====================
+        async function fetchAllWeatherData(lat, lon, locationName) {
+            try {
+                setLoading(true, 'Fetching weather data...');
+                errorState.style.display = 'none';
+                
+                const [weatherRes, hourlyRes, forecastRes, aqiRes] = await Promise.all([
+                    fetchWithRetry(`${API_BASE_URL}/weather?lat=${lat}&lon=${lon}`),
+                    fetchWithRetry(`${API_BASE_URL}/hourly?lat=${lat}&lon=${lon}`),
+                    fetchWithRetry(`${API_BASE_URL}/forecast?lat=${lat}&lon=${lon}`),
+                    fetchWithRetry(`${API_BASE_URL}/aqi-alerts?lat=${lat}&lon=${lon}`)
+                ]);
+                
+                const [weather, hourly, forecast, aqi] = await Promise.all([
+                    weatherRes.json(), hourlyRes.json(), forecastRes.json(), aqiRes.json()
+                ]);
+                
+                currentLat = lat;
+                currentLon = lon;
+                currentLocationName = locationName;
+                
+                updateCurrentWeather(weather);
+                updateHourlyForecast(hourly);
+                updateDailyForecast(forecast);
+                updateAQI(aqi);
+                
+                setLoading(false);
+            } catch (error) {
+                console.error('Failed to fetch weather data:', error);
+                setLoading(false);
+                errorState.style.display = 'block';
+            }
+        }
+        
+        function updateCurrentWeather(data) {
+            $('location-name').textContent = currentLocationName;
+            $('current-date').textContent = formatDate();
+            $('main-temp').textContent = `${Math.round(data.temperature_c)}°`;
+            $('main-icon').textContent = weatherIcons[data.weather_code] || '🌡️';
+            $('main-description').textContent = weatherDescriptions[data.weather_code] || 'Unknown';
+            $('feels-like').textContent = Math.round(data.apparent_temperature);
+            $('humidity').textContent = data.humidity_pct;
+            $('wind').textContent = data.wind_speed_mps?.toFixed(1);
+            $('uv-index').textContent = data.uv_index?.toFixed(1);
+            $('precip').textContent = data.precip_mm?.toFixed(1);
+        }
+        
+        function updateHourlyForecast(data) {
+            const container = $('hourly-container');
+            container.innerHTML = data.slice(0, 24).map((hour, i) => `
+                <div class="hourly-item" style="animation-delay: ${i * 0.05}s">
+                    <div class="time">${formatHour(hour.time)}</div>
+                    <div class="icon">${weatherIcons[hour.weather_code] || '🌡️'}</div>
+                    <div class="temp">${Math.round(hour.temp)}°</div>
+                </div>
+            `).join('');
+        }
+        
+        function updateDailyForecast(data) {
+            const container = $('daily-container');
+            container.innerHTML = data.map((day, i) => `
+                <div class="daily-item" style="animation-delay: ${i * 0.1}s">
+                    <span class="day">${formatDay(day.date)}</span>
+                    <span class="icon">${weatherIcons[day.weather_code] || '🌡️'}</span>
+                    <span class="precip">💧 ${day.precipitation_probability_max || 0}%</span>
+                    <span class="temps">
+                        <span class="high">${Math.round(day.max_temp)}°</span> / 
+                        <span class="low">${Math.round(day.min_temp)}°</span>
+                    </span>
+                </div>
+            `).join('');
+        }
+        
+        function updateAQI(data) {
+            if (data?.aqi?.hourly?.us_aqi?.[0]) {
+                $('aqi').textContent = data.aqi.hourly.us_aqi[0];
+            }
+        }
+        
+        function retryFetch() {
+            if (currentLat && currentLon) {
+                fetchAllWeatherData(currentLat, currentLon, currentLocationName);
+            } else {
+                initLocation();
+            }
+        }
+        
+        // ==================== TAB NAVIGATION ====================
+        document.querySelectorAll('.tab-btn').forEach(btn => {
+            btn.addEventListener('click', () => {
+                document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
+                document.querySelectorAll('.tab-content').forEach(t => t.classList.remove('active'));
+                btn.classList.add('active');
+                $(btn.dataset.tab).classList.add('active');
+            });
+        });
+        
+        // ==================== THEME TOGGLE ====================
+        themeToggle.addEventListener('click', () => {
+            if (window.themeManager) {
+                const newTheme = window.themeManager.toggle();
+                themeToggle.querySelector('.theme-icon').textContent = newTheme === 'dark' ? '☀️' : '🌙';
+            }
+        });
+        
+        // Update theme icon on load
+        if (window.themeManager && window.themeManager.isDark()) {
+            themeToggle.querySelector('.theme-icon').textContent = '☀️';
+        }
+        
+        // ==================== HEADER SCROLL EFFECT ====================
+        let lastScroll = 0;
+        window.addEventListener('scroll', () => {
+            const currentScroll = window.pageYOffset;
+            siteHeader.classList.toggle('scrolled', currentScroll > 50);
+            lastScroll = currentScroll;
+        });
+        
+        // ==================== INITIALIZATION ====================
+        function initLocation() {
+            setLoading(true, 'Getting your location...');
+            if (navigator.geolocation) {
+                navigator.geolocation.getCurrentPosition(
+                    pos => fetchAllWeatherData(pos.coords.latitude.toFixed(2), pos.coords.longitude.toFixed(2), "Your Current Location"),
+                    () => fetchAllWeatherData(40.71, -74.01, "New York"),
+                    { timeout: 10000, maximumAge: 300000 }
+                );
+            } else {
+                fetchAllWeatherData(40.71, -74.01, "New York");
+            }
+        }
+        
+        // Initialize
+        $('current-date').textContent = formatDate();
+        initLocation();
+        
+        // Connection check
+        setInterval(async () => {
+            try {
+                await fetch(`${API_BASE_URL}/healthz`, { signal: AbortSignal.timeout(5000) });
+                setConnectionStatus('connected');
+            } catch {
+                setConnectionStatus('disconnected');
+            }
+        }, 30000);
+    </script>
+</body>
+</html>
diff --git a/static/js/motion.js b/static/js/motion.js
new file mode 100644
index 0000000..fcc13b2
--- /dev/null
+++ b/static/js/motion.js
@@ -0,0 +1,306 @@
+/**
+ * IntelliWeather - Motion Controller
+ * 
+ * Advanced animation sequencing and coordination system
+ * Supports cancellation, interruption, and reduced motion preferences
+ */
+
+class MotionController {
+    constructor() {
+        this.activeAnimations = new Map();
+        this.prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        
+        // Listen for motion preference changes
+        window.matchMedia('(prefers-reduced-motion: reduce)').addEventListener('change', (e) => {
+            this.prefersReducedMotion = e.matches;
+        });
+    }
+    
+    /**
+     * Animation tokens - consistent timing across the app
+     */
+    static TOKENS = {
+        duration: {
+            instant: 100,
+            fast: 150,
+            normal: 300,
+            slow: 500,
+            slower: 800,
+            slowest: 1200
+        },
+        easing: {
+            linear: 'linear',
+            easeOut: 'cubic-bezier(0.16, 1, 0.3, 1)',
+            easeInOut: 'cubic-bezier(0.87, 0, 0.13, 1)',
+            easeOutBack: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+            bounce: 'cubic-bezier(0.68, -0.6, 0.32, 1.6)',
+            smooth: 'cubic-bezier(0.4, 0, 0.2, 1)'
+        },
+        stagger: {
+            xs: 30,
+            sm: 50,
+            md: 80,
+            lg: 120
+        }
+    };
+    
+    /**
+     * Create a cancellable animation promise
+     */
+    animate(element, keyframes, options = {}) {
+        if (this.prefersReducedMotion) {
+            // Apply final state immediately
+            if (keyframes.length > 0) {
+                const finalFrame = keyframes[keyframes.length - 1];
+                Object.assign(element.style, finalFrame);
+            }
+            return Promise.resolve();
+        }
+        
+        const animation = element.animate(keyframes, {
+            duration: options.duration || MotionController.TOKENS.duration.normal,
+            easing: options.easing || MotionController.TOKENS.easing.easeOut,
+            fill: 'forwards',
+            ...options
+        });
+        
+        const id = Symbol('animation');
+        this.activeAnimations.set(id, animation);
+        
+        return new Promise((resolve, reject) => {
+            animation.onfinish = () => {
+                this.activeAnimations.delete(id);
+                resolve();
+            };
+            animation.oncancel = () => {
+                this.activeAnimations.delete(id);
+                reject(new Error('Animation cancelled'));
+            };
+        });
+    }
+    
+    /**
+     * Cancel all active animations
+     */
+    cancelAll() {
+        this.activeAnimations.forEach(animation => animation.cancel());
+        this.activeAnimations.clear();
+    }
+    
+    /**
+     * Fade in animation
+     */
+    fadeIn(element, options = {}) {
+        element.style.opacity = '0';
+        return this.animate(element, [
+            { opacity: 0 },
+            { opacity: 1 }
+        ], { duration: MotionController.TOKENS.duration.normal, ...options });
+    }
+    
+    /**
+     * Fade out animation
+     */
+    fadeOut(element, options = {}) {
+        return this.animate(element, [
+            { opacity: 1 },
+            { opacity: 0 }
+        ], { duration: MotionController.TOKENS.duration.fast, ...options });
+    }
+    
+    /**
+     * Slide in from direction
+     */
+    slideIn(element, direction = 'up', options = {}) {
+        const transforms = {
+            up: 'translateY(30px)',
+            down: 'translateY(-30px)',
+            left: 'translateX(30px)',
+            right: 'translateX(-30px)'
+        };
+        
+        element.style.opacity = '0';
+        element.style.transform = transforms[direction];
+        
+        return this.animate(element, [
+            { opacity: 0, transform: transforms[direction] },
+            { opacity: 1, transform: 'translate(0)' }
+        ], { duration: MotionController.TOKENS.duration.slow, ...options });
+    }
+    
+    /**
+     * Scale in with optional bounce
+     */
+    scaleIn(element, bounce = false, options = {}) {
+        element.style.opacity = '0';
+        element.style.transform = 'scale(0.9)';
+        
+        const keyframes = bounce ? [
+            { opacity: 0, transform: 'scale(0.8)' },
+            { opacity: 1, transform: 'scale(1.05)' },
+            { opacity: 1, transform: 'scale(1)' }
+        ] : [
+            { opacity: 0, transform: 'scale(0.9)' },
+            { opacity: 1, transform: 'scale(1)' }
+        ];
+        
+        return this.animate(element, keyframes, { 
+            duration: bounce ? MotionController.TOKENS.duration.slower : MotionController.TOKENS.duration.normal,
+            easing: bounce ? MotionController.TOKENS.easing.bounce : MotionController.TOKENS.easing.easeOut,
+            ...options 
+        });
+    }
+    
+    /**
+     * Stagger animation for multiple elements
+     */
+    async staggerIn(elements, animation = 'fadeIn', staggerDelay = MotionController.TOKENS.stagger.sm) {
+        if (this.prefersReducedMotion) {
+            elements.forEach(el => el.style.opacity = '1');
+            return;
+        }
+        
+        const promises = Array.from(elements).map((element, index) => {
+            return new Promise(resolve => {
+                setTimeout(() => {
+                    this[animation](element).then(resolve).catch(resolve);
+                }, index * staggerDelay);
+            });
+        });
+        
+        return Promise.all(promises);
+    }
+    
+    /**
+     * Page transition - exit current, enter new
+     */
+    async pageTransition(exitElement, enterElement) {
+        if (this.prefersReducedMotion) {
+            if (exitElement) exitElement.style.display = 'none';
+            if (enterElement) enterElement.style.display = 'block';
+            return;
+        }
+        
+        // Exit animation
+        if (exitElement) {
+            await this.animate(exitElement, [
+                { opacity: 1, transform: 'translateY(0)' },
+                { opacity: 0, transform: 'translateY(-20px)' }
+            ], { duration: MotionController.TOKENS.duration.normal });
+            exitElement.style.display = 'none';
+        }
+        
+        // Enter animation
+        if (enterElement) {
+            enterElement.style.display = 'block';
+            await this.animate(enterElement, [
+                { opacity: 0, transform: 'translateY(30px)' },
+                { opacity: 1, transform: 'translateY(0)' }
+            ], { duration: MotionController.TOKENS.duration.slow });
+        }
+    }
+    
+    /**
+     * Coordinated sequence for loading states
+     * search -> loading skeleton -> results reveal
+     */
+    async loadingSequence(searchInput, skeletonContainer, resultsContainer, loadData) {
+        // 1. Show skeleton
+        if (skeletonContainer) {
+            skeletonContainer.style.display = 'block';
+            this.fadeIn(skeletonContainer);
+        }
+        
+        // 2. Load data
+        let data;
+        try {
+            data = await loadData();
+        } catch (error) {
+            if (skeletonContainer) {
+                await this.fadeOut(skeletonContainer);
+                skeletonContainer.style.display = 'none';
+            }
+            throw error;
+        }
+        
+        // 3. Hide skeleton
+        if (skeletonContainer) {
+            await this.fadeOut(skeletonContainer);
+            skeletonContainer.style.display = 'none';
+        }
+        
+        // 4. Show results with stagger
+        if (resultsContainer) {
+            resultsContainer.style.display = 'block';
+            const items = resultsContainer.children;
+            await this.staggerIn(items, 'slideIn');
+        }
+        
+        return data;
+    }
+    
+    /**
+     * Weather card flip transition
+     */
+    async cardFlip(card, updateContent) {
+        if (this.prefersReducedMotion) {
+            updateContent();
+            return;
+        }
+        
+        // Flip out
+        await this.animate(card, [
+            { transform: 'perspective(1000px) rotateY(0deg)' },
+            { transform: 'perspective(1000px) rotateY(90deg)' }
+        ], { duration: MotionController.TOKENS.duration.normal });
+        
+        // Update content at midpoint
+        updateContent();
+        
+        // Flip in
+        await this.animate(card, [
+            { transform: 'perspective(1000px) rotateY(90deg)' },
+            { transform: 'perspective(1000px) rotateY(0deg)' }
+        ], { duration: MotionController.TOKENS.duration.normal });
+    }
+    
+    /**
+     * Shake animation for errors
+     */
+    shake(element) {
+        return this.animate(element, [
+            { transform: 'translateX(0)' },
+            { transform: 'translateX(-10px)' },
+            { transform: 'translateX(10px)' },
+            { transform: 'translateX(-10px)' },
+            { transform: 'translateX(10px)' },
+            { transform: 'translateX(0)' }
+        ], { duration: MotionController.TOKENS.duration.slow });
+    }
+    
+    /**
+     * Pulse animation for attention
+     */
+    pulse(element, count = 2) {
+        const keyframes = [];
+        for (let i = 0; i < count; i++) {
+            keyframes.push(
+                { transform: 'scale(1)', offset: i / count },
+                { transform: 'scale(1.1)', offset: (i + 0.5) / count }
+            );
+        }
+        keyframes.push({ transform: 'scale(1)' });
+        
+        return this.animate(element, keyframes, { 
+            duration: MotionController.TOKENS.duration.slower * count 
+        });
+    }
+}
+
+// Create global instance
+window.motionController = new MotionController();
+
+// Export for modules
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = MotionController;
+}
diff --git a/static/js/search.js b/static/js/search.js
new file mode 100644
index 0000000..f43d5b1
--- /dev/null
+++ b/static/js/search.js
@@ -0,0 +1,301 @@
+/**
+ * IntelliWeather - Search Component
+ * 
+ * Enhanced search with autosuggest, keyboard navigation, and animations
+ */
+
+class SearchController {
+    constructor(options = {}) {
+        this.input = document.querySelector(options.inputSelector || '#city-search');
+        this.resultsContainer = document.querySelector(options.resultsSelector || '#search-results');
+        this.apiBaseUrl = options.apiBaseUrl || window.location.origin;
+        
+        this.debounceTimeout = null;
+        this.debounceDelay = options.debounceDelay || 300;
+        this.minQueryLength = options.minQueryLength || 2;
+        this.maxResults = options.maxResults || 5;
+        
+        this.selectedIndex = -1;
+        this.results = [];
+        this.isLoading = false;
+        
+        this.onSelect = options.onSelect || (() => {});
+        
+        this.init();
+    }
+    
+    init() {
+        if (!this.input || !this.resultsContainer) {
+            console.warn('Search: Missing required elements');
+            return;
+        }
+        
+        // Input events
+        this.input.addEventListener('input', (e) => this.handleInput(e));
+        this.input.addEventListener('keydown', (e) => this.handleKeydown(e));
+        this.input.addEventListener('focus', () => this.handleFocus());
+        this.input.addEventListener('blur', () => this.handleBlur());
+        
+        // Click outside to close
+        document.addEventListener('click', (e) => {
+            if (!e.target.closest('.search-container')) {
+                this.close();
+            }
+        });
+        
+        // Results container events
+        this.resultsContainer.addEventListener('click', (e) => this.handleResultClick(e));
+        this.resultsContainer.addEventListener('mouseenter', (e) => this.handleResultHover(e), true);
+    }
+    
+    handleInput(e) {
+        const query = e.target.value.trim();
+        
+        // Clear previous timeout
+        clearTimeout(this.debounceTimeout);
+        
+        if (query.length < this.minQueryLength) {
+            this.close();
+            return;
+        }
+        
+        // Show loading state
+        this.showLoading();
+        
+        // Debounce the search
+        this.debounceTimeout = setTimeout(() => {
+            this.search(query);
+        }, this.debounceDelay);
+    }
+    
+    handleKeydown(e) {
+        if (!this.results.length) return;
+        
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                this.selectNext();
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                this.selectPrevious();
+                break;
+            case 'Enter':
+                e.preventDefault();
+                if (this.selectedIndex >= 0) {
+                    this.selectResult(this.results[this.selectedIndex]);
+                }
+                break;
+            case 'Escape':
+                this.close();
+                this.input.blur();
+                break;
+        }
+    }
+    
+    handleFocus() {
+        if (this.results.length) {
+            this.renderResults();
+        }
+    }
+    
+    handleBlur() {
+        // Delay to allow click events on results
+        setTimeout(() => {
+            if (!this.resultsContainer.matches(':hover')) {
+                this.close();
+            }
+        }, 150);
+    }
+    
+    handleResultClick(e) {
+        const item = e.target.closest('.search-item');
+        if (item && item.dataset.index !== undefined) {
+            const index = parseInt(item.dataset.index);
+            this.selectResult(this.results[index]);
+        }
+    }
+    
+    handleResultHover(e) {
+        const item = e.target.closest('.search-item');
+        if (item && item.dataset.index !== undefined) {
+            this.selectedIndex = parseInt(item.dataset.index);
+            this.highlightSelected();
+        }
+    }
+    
+    async search(query) {
+        this.isLoading = true;
+        
+        try {
+            // Use our geocoding endpoint if available, fallback to Open-Meteo
+            const response = await fetch(
+                `${this.apiBaseUrl}/geocode/search?q=${encodeURIComponent(query)}&limit=${this.maxResults}`,
+                { signal: AbortSignal.timeout(5000) }
+            ).catch(() => 
+                fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(query)}&count=${this.maxResults}`,
+                    { signal: AbortSignal.timeout(5000) }
+                )
+            );
+            
+            const data = await response.json();
+            
+            // Normalize response format
+            if (data.results) {
+                this.results = data.results.map(r => ({
+                    name: r.name,
+                    admin: r.admin1 || r.admin || '',
+                    country: r.country || '',
+                    lat: r.latitude || r.lat,
+                    lon: r.longitude || r.lon,
+                    timezone: r.timezone || ''
+                }));
+            } else if (Array.isArray(data)) {
+                this.results = data;
+            } else {
+                this.results = [];
+            }
+            
+            this.selectedIndex = -1;
+            this.renderResults();
+        } catch (error) {
+            console.error('Search error:', error);
+            this.showError();
+        } finally {
+            this.isLoading = false;
+        }
+    }
+    
+    showLoading() {
+        this.resultsContainer.innerHTML = `
+            <div class="search-loading">
+                <div class="search-loading-spinner"></div>
+                <span>Searching...</span>
+            </div>
+        `;
+        this.resultsContainer.style.display = 'block';
+        
+        // Animate in
+        if (window.motionController) {
+            window.motionController.fadeIn(this.resultsContainer);
+        }
+    }
+    
+    showError() {
+        this.resultsContainer.innerHTML = `
+            <div class="search-item search-error">
+                <span class="search-error-icon">⚠️</span>
+                <span>Unable to search. Please try again.</span>
+            </div>
+        `;
+    }
+    
+    renderResults() {
+        if (!this.results.length) {
+            this.resultsContainer.innerHTML = `
+                <div class="search-item search-no-results">
+                    <span class="search-icon">🔍</span>
+                    <span>No locations found</span>
+                </div>
+            `;
+            this.resultsContainer.style.display = 'block';
+            return;
+        }
+        
+        this.resultsContainer.innerHTML = this.results.map((result, index) => `
+            <div class="search-item ${index === this.selectedIndex ? 'selected' : ''}" 
+                 data-index="${index}"
+                 role="option"
+                 aria-selected="${index === this.selectedIndex}">
+                <div class="search-item-icon">📍</div>
+                <div class="search-item-content">
+                    <div class="search-item-name">${this.escapeHtml(result.name)}</div>
+                    <div class="search-item-detail">
+                        ${result.admin ? this.escapeHtml(result.admin) + ', ' : ''}${this.escapeHtml(result.country)}
+                    </div>
+                </div>
+                <div class="search-item-arrow">→</div>
+            </div>
+        `).join('');
+        
+        this.resultsContainer.style.display = 'block';
+        
+        // Animate items
+        if (window.motionController) {
+            const items = this.resultsContainer.querySelectorAll('.search-item');
+            window.motionController.staggerIn(items, 'slideIn');
+        }
+    }
+    
+    selectNext() {
+        if (this.selectedIndex < this.results.length - 1) {
+            this.selectedIndex++;
+            this.highlightSelected();
+        }
+    }
+    
+    selectPrevious() {
+        if (this.selectedIndex > 0) {
+            this.selectedIndex--;
+            this.highlightSelected();
+        }
+    }
+    
+    highlightSelected() {
+        const items = this.resultsContainer.querySelectorAll('.search-item');
+        items.forEach((item, index) => {
+            item.classList.toggle('selected', index === this.selectedIndex);
+            item.setAttribute('aria-selected', index === this.selectedIndex);
+        });
+        
+        // Scroll into view if needed
+        if (this.selectedIndex >= 0 && items[this.selectedIndex]) {
+            items[this.selectedIndex].scrollIntoView({ block: 'nearest' });
+        }
+    }
+    
+    selectResult(result) {
+        if (!result) return;
+        
+        // Update input
+        this.input.value = `${result.name}, ${result.country}`;
+        
+        // Close dropdown
+        this.close();
+        
+        // Callback
+        this.onSelect(result);
+    }
+    
+    close() {
+        this.resultsContainer.style.display = 'none';
+        this.resultsContainer.innerHTML = '';
+        this.selectedIndex = -1;
+    }
+    
+    escapeHtml(text) {
+        const div = document.createElement('div');
+        div.textContent = text;
+        return div.innerHTML;
+    }
+}
+
+// Auto-initialize if elements exist
+document.addEventListener('DOMContentLoaded', () => {
+    const searchInput = document.querySelector('#city-search');
+    if (searchInput) {
+        window.searchController = new SearchController({
+            onSelect: (result) => {
+                // Trigger weather fetch
+                if (typeof fetchAllWeatherData === 'function') {
+                    fetchAllWeatherData(result.lat, result.lon, `${result.name}, ${result.country}`);
+                }
+            }
+        });
+    }
+});
+
+// Export for modules
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = SearchController;
+}
diff --git a/static/js/theme.js b/static/js/theme.js
new file mode 100644
index 0000000..4fd0b47
--- /dev/null
+++ b/static/js/theme.js
@@ -0,0 +1,96 @@
+/**
+ * IntelliWeather - Theme Manager
+ * 
+ * Handles dark/light mode toggle with persistence
+ */
+
+class ThemeManager {
+    constructor() {
+        this.STORAGE_KEY = 'intelliweather-theme';
+        this.THEMES = ['light', 'dark'];
+        this.currentTheme = this.loadTheme();
+        this.init();
+    }
+    
+    init() {
+        // Apply theme immediately to prevent flash
+        this.applyTheme(this.currentTheme);
+        
+        // Listen for system preference changes
+        window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+            if (!localStorage.getItem(this.STORAGE_KEY)) {
+                this.applyTheme(e.matches ? 'dark' : 'light');
+            }
+        });
+    }
+    
+    loadTheme() {
+        // Check localStorage first
+        const stored = localStorage.getItem(this.STORAGE_KEY);
+        if (stored && this.THEMES.includes(stored)) {
+            return stored;
+        }
+        
+        // Check system preference
+        if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+            return 'dark';
+        }
+        
+        return 'light';
+    }
+    
+    applyTheme(theme) {
+        // Prevent transition flash on initial load
+        document.documentElement.classList.add('no-transitions');
+        document.documentElement.setAttribute('data-theme', theme);
+        this.currentTheme = theme;
+        
+        // Update meta theme-color for mobile browsers
+        const metaThemeColor = document.querySelector('meta[name="theme-color"]');
+        if (metaThemeColor) {
+            metaThemeColor.content = theme === 'dark' ? '#0f172a' : '#ffffff';
+        }
+        
+        // Re-enable transitions after a frame
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+                document.documentElement.classList.remove('no-transitions');
+            });
+        });
+        
+        // Dispatch custom event
+        window.dispatchEvent(new CustomEvent('themechange', { detail: { theme } }));
+    }
+    
+    toggle() {
+        const newTheme = this.currentTheme === 'dark' ? 'light' : 'dark';
+        this.setTheme(newTheme);
+        return newTheme;
+    }
+    
+    setTheme(theme) {
+        if (!this.THEMES.includes(theme)) {
+            console.warn(`Invalid theme: ${theme}`);
+            return;
+        }
+        
+        localStorage.setItem(this.STORAGE_KEY, theme);
+        this.applyTheme(theme);
+    }
+    
+    getTheme() {
+        return this.currentTheme;
+    }
+    
+    isDark() {
+        return this.currentTheme === 'dark';
+    }
+}
+
+// Create global instance
+window.themeManager = new ThemeManager();
+
+// Export for modules
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = ThemeManager;
+}
diff --git a/static/login.html b/static/login.html
index 2ce8eb7..e803c4d 100644
--- a/static/login.html
+++ b/static/login.html
@@ -1,75 +1,290 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Log In - Weather App</title>
-    <style>
-        body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background-color: #eef5ff; }
-        .auth-card { background: white; padding: 2rem 3rem; border-radius: 15px; box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1); text-align: center; width: 90%; max-width: 400px; }
-        h1 { margin-top: 0; }
-        .form-group { margin-bottom: 1.5rem; text-align: left; }
-        label { display: block; margin-bottom: 0.5rem; font-weight: bold; color: #555; }
-        input { width: 100%; padding: 10px; border-radius: 5px; border: 1px solid #ccc; box-sizing: border-box; }
-        button { background-color: #007bff; color: white; border: none; padding: 12px; border-radius: 5px; cursor: pointer; font-size: 16px; width: 100%; }
-        .google-btn { cursor: pointer; width: 100%; display: block; background-color: #4285F4; color: white; padding: 12px; border-radius: 5px; text-decoration: none; font-weight: bold; border: none; font-size: 16px; margin-top: 1rem; }
-        .link { margin-top: 1rem; }
-        .message { margin-top: 1rem; font-weight: bold; color: red; }
-    </style>
-</head>
-<body>
-    <div class="auth-card">
-        <h1>Log In</h1>
-        <form id="loginForm">
-            <div class="form-group">
-                <label for="email">Email</label>
-                <input type="email" id="email" name="username" required>
-            </div>
-            <div class="form-group">
-                <label for="password">Password</label>
-                <input type="password" id="password" name="password" required>
-            </div>
-            <button type="submit">Log In</button>
-        </form>
-        <p style="text-align: center; margin: 1rem 0;">OR</p>
-        <button id="googleSignInBtn" class="google-btn">Sign in with Google</button>
-        <div id="message" class="message"></div>
-        <div class="link">
-            <p>Don't have an account? <a href="/signup.html">Sign Up</a></p>
-        </div>
-    </div>
-
-    <script>
-        const loginForm = document.getElementById('loginForm');
-        const googleSignInBtn = document.getElementById('googleSignInBtn');
-        const messageDiv = document.getElementById('message');
-
-        // Handler for standard email/password login
-        loginForm.addEventListener('submit', async (event) => {
-            event.preventDefault();
-            const formData = new FormData(loginForm);
-            try {
-                const response = await fetch('/token', {
-                    method: 'POST',
-                    body: formData
-                });
-                const data = await response.json();
-                if (response.ok) {
-                    localStorage.setItem('weatherAppToken', data.access_token);
-                    window.location.href = '/index.html'; 
-                } else {
-                    messageDiv.textContent = data.detail || 'An error occurred.';
-                }
-            } catch (error) {
-                messageDiv.textContent = 'Could not connect to the server.';
-            }
-        });
-
-        // Handler for Google Sign-In button
-        googleSignInBtn.addEventListener('click', () => {
-            // This now simply navigates to our backend endpoint that handles the redirect
-            window.location.href = '/login/google';
-        });
-    </script>
-</body>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Welcome Back - IntelliWeather</title>
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>👑</text></svg>">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;500;600;700&family=Inter:wght@300;400;500;600&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --royal-gold: #d4af37;
+            --royal-purple: #4a1c6e;
+            --royal-purple-light: #7b4397;
+            --text-primary: #1e293b;
+            --text-secondary: #475569;
+            --text-muted: #94a3b8;
+            --success: #10b981;
+            --error: #ef4444;
+        }
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+        body { 
+            font-family: 'Inter', system-ui, sans-serif;
+            min-height: 100vh;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            padding: 1rem;
+            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+            position: relative;
+            overflow: hidden;
+        }
+
+        /* Background Elements */
+        .orb {
+            position: fixed;
+            border-radius: 50%;
+            filter: blur(80px);
+            opacity: 0.5;
+            animation: float 20s ease-in-out infinite;
+            pointer-events: none;
+        }
+        .orb-1 { width: 500px; height: 500px; background: linear-gradient(135deg, var(--royal-purple), var(--royal-gold)); top: -150px; left: -150px; }
+        .orb-2 { width: 400px; height: 400px; background: linear-gradient(135deg, #e94560, var(--royal-purple-light)); bottom: -100px; right: -100px; animation-delay: -10s; }
+        @keyframes float {
+            0%, 100% { transform: translate(0, 0); }
+            50% { transform: translate(30px, -30px); }
+        }
+
+        /* Auth Card */
+        .auth-card {
+            background: rgba(255, 255, 255, 0.95);
+            backdrop-filter: blur(20px);
+            padding: 3rem;
+            border-radius: 32px;
+            box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+            width: 100%;
+            max-width: 420px;
+            position: relative;
+            z-index: 1;
+            animation: cardEntrance 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+        }
+        @keyframes cardEntrance {
+            from { opacity: 0; transform: translateY(30px) scale(0.95); }
+            to { opacity: 1; transform: translateY(0) scale(1); }
+        }
+        .auth-card::before {
+            content: '👑';
+            position: absolute;
+            top: -25px;
+            left: 50%;
+            transform: translateX(-50%);
+            font-size: 3rem;
+            filter: drop-shadow(0 4px 8px rgba(212, 175, 55, 0.4));
+            animation: crownFloat 3s ease-in-out infinite;
+        }
+        @keyframes crownFloat {
+            0%, 100% { transform: translateX(-50%) translateY(0); }
+            50% { transform: translateX(-50%) translateY(-8px); }
+        }
+
+        .header { text-align: center; margin-bottom: 2rem; }
+        .header h1 {
+            font-family: 'Playfair Display', serif;
+            font-size: 2rem;
+            color: var(--text-primary);
+            margin-bottom: 0.5rem;
+        }
+        .header p { color: var(--text-muted); font-size: 0.95rem; }
+
+        /* Form */
+        .form-group { margin-bottom: 1.5rem; text-align: left; }
+        .form-group label {
+            display: block;
+            font-weight: 600;
+            color: var(--text-primary);
+            margin-bottom: 0.5rem;
+            font-size: 0.9rem;
+        }
+        .form-group input {
+            width: 100%;
+            padding: 1rem 1.25rem;
+            font-size: 1rem;
+            font-family: inherit;
+            border: 2px solid rgba(212, 175, 55, 0.3);
+            border-radius: 16px;
+            background: rgba(248, 250, 252, 0.9);
+            color: var(--text-primary);
+            transition: all 0.3s ease;
+        }
+        .form-group input:focus {
+            outline: none;
+            border-color: var(--royal-gold);
+            background: white;
+            box-shadow: 0 0 0 4px rgba(212, 175, 55, 0.15);
+        }
+        .form-group input::placeholder { color: var(--text-muted); }
+
+        /* Submit Button */
+        .submit-btn {
+            width: 100%;
+            padding: 1rem;
+            font-size: 1rem;
+            font-weight: 600;
+            font-family: inherit;
+            color: white;
+            background: linear-gradient(135deg, var(--royal-purple), var(--royal-purple-light));
+            border: none;
+            border-radius: 16px;
+            cursor: pointer;
+            transition: all 0.3s ease;
+            box-shadow: 0 4px 15px rgba(74, 28, 110, 0.4);
+            margin-bottom: 1.5rem;
+        }
+        .submit-btn:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 8px 25px rgba(74, 28, 110, 0.5);
+        }
+        .submit-btn:active { transform: translateY(0); }
+
+        /* Divider */
+        .divider {
+            display: flex;
+            align-items: center;
+            margin: 1.5rem 0;
+            color: var(--text-muted);
+            font-size: 0.85rem;
+        }
+        .divider::before, .divider::after {
+            content: '';
+            flex: 1;
+            height: 1px;
+            background: rgba(212, 175, 55, 0.3);
+        }
+        .divider span { padding: 0 1rem; }
+
+        /* Google Button */
+        .google-btn {
+            width: 100%;
+            padding: 1rem;
+            font-size: 1rem;
+            font-weight: 500;
+            font-family: inherit;
+            color: var(--text-primary);
+            background: white;
+            border: 2px solid rgba(212, 175, 55, 0.3);
+            border-radius: 16px;
+            cursor: pointer;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            gap: 0.75rem;
+            transition: all 0.3s ease;
+        }
+        .google-btn:hover {
+            border-color: var(--royal-gold);
+            background: rgba(212, 175, 55, 0.05);
+        }
+        .google-btn svg { width: 20px; height: 20px; }
+
+        /* Links */
+        .auth-link {
+            text-align: center;
+            margin-top: 1.5rem;
+            font-size: 0.9rem;
+            color: var(--text-muted);
+        }
+        .auth-link a {
+            color: var(--royal-gold);
+            text-decoration: none;
+            font-weight: 600;
+            transition: color 0.3s ease;
+        }
+        .auth-link a:hover { color: var(--royal-purple); }
+
+        /* Message */
+        .message {
+            padding: 1rem;
+            border-radius: 12px;
+            margin-bottom: 1.5rem;
+            font-size: 0.9rem;
+            display: none;
+            animation: slideIn 0.3s ease;
+        }
+        @keyframes slideIn { from { opacity: 0; transform: translateY(-10px); } to { opacity: 1; transform: translateY(0); } }
+        .message.success { background: rgba(16, 185, 129, 0.1); color: #047857; border: 1px solid rgba(16, 185, 129, 0.3); }
+        .message.error { background: rgba(239, 68, 68, 0.1); color: #dc2626; border: 1px solid rgba(239, 68, 68, 0.3); }
+
+        @media (max-width: 480px) {
+            .auth-card { padding: 2rem 1.5rem; border-radius: 24px; }
+            .header h1 { font-size: 1.75rem; }
+        }
+    </style>
+</head>
+<body>
+    <div class="orb orb-1"></div>
+    <div class="orb orb-2"></div>
+
+    <div class="auth-card">
+        <div class="header">
+            <h1>Welcome Back</h1>
+            <p>Sign in to your royal weather experience</p>
+        </div>
+
+        <div class="message" id="message"></div>
+
+        <form id="login-form">
+            <div class="form-group">
+                <label for="email">Email Address</label>
+                <input type="email" id="email" placeholder="you@example.com" required>
+            </div>
+            <div class="form-group">
+                <label for="password">Password</label>
+                <input type="password" id="password" placeholder="Enter your password" required>
+            </div>
+            <button type="submit" class="submit-btn">Sign In</button>
+        </form>
+
+        <div class="divider"><span>or continue with</span></div>
+
+        <button class="google-btn" id="google-btn">
+            <svg viewBox="0 0 24 24"><path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/><path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/><path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/><path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/></svg>
+            Sign in with Google
+        </button>
+
+        <p class="auth-link">Don't have an account? <a href="/signup.html">Create one</a></p>
+    </div>
+
+    <script>
+        const API_BASE_URL = window.location.hostname === '127.0.0.1' || window.location.hostname === 'localhost' 
+            ? `http://${window.location.hostname}:8000` : window.location.origin;
+
+        function showMessage(text, type) {
+            const msg = document.getElementById('message');
+            msg.textContent = text;
+            msg.className = `message ${type}`;
+            msg.style.display = 'block';
+        }
+
+        document.getElementById('login-form').addEventListener('submit', async (e) => {
+            e.preventDefault();
+            const formData = new FormData();
+            formData.append('username', document.getElementById('email').value);
+            formData.append('password', document.getElementById('password').value);
+
+            try {
+                const response = await fetch(`${API_BASE_URL}/token`, {
+                    method: 'POST',
+                    body: formData
+                });
+                const data = await response.json();
+                if (response.ok) {
+                    localStorage.setItem('weatherAppToken', data.access_token);
+                    showMessage('Welcome back! Redirecting...', 'success');
+                    setTimeout(() => window.location.href = '/index.html', 700);
+                } else {
+                    showMessage(data.detail || 'Invalid credentials', 'error');
+                }
+            } catch (error) {
+                showMessage('Connection error. Please try again.', 'error');
+            }
+        });
+
+        document.getElementById('google-btn').addEventListener('click', () => {
+            window.location.href = '/login/google';
+        });
+    </script>
+</body>
 </html>
\ No newline at end of file
diff --git a/static/signup.html b/static/signup.html
index a29645b..c7a9dfb 100644
--- a/static/signup.html
+++ b/static/signup.html
@@ -1,92 +1,325 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Sign Up - Weather App</title>
-    <style>
-        body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background-color: #eef5ff; }
-        .auth-card { background: white; padding: 2rem 3rem; border-radius: 15px; box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1); text-align: center; width: 90%; max-width: 400px; }
-        h1 { margin-top: 0; }
-        .form-group { margin-bottom: 1.5rem; text-align: left; }
-        label { display: block; margin-bottom: 0.5rem; font-weight: bold; color: #555; }
-        input { width: 100%; padding: 10px; border-radius: 5px; border: 1px solid #ccc; box-sizing: border-box; }
-        button { background-color: #28a745; color: white; border: none; padding: 12px; border-radius: 5px; cursor: pointer; font-size: 16px; width: 100%; }
-        .google-btn { cursor: pointer; width: 100%; display: block; background-color: #4285F4; color: white; padding: 12px; border-radius: 5px; text-decoration: none; font-weight: bold; border: none; font-size: 16px; margin-top: 1rem; }
-        .link { margin-top: 1rem; }
-        .message { margin-top: 1rem; font-weight: bold; }
-        .success { color: green; }
-        .error { color: red; }
-    </style>
-</head>
-<body>
-    <div class="auth-card">
-        <h1>Create Account</h1>
-        <form id="signupForm">
-            <div class="form-group">
-                <label for="email">Email</label>
-                <input type="email" id="email" required>
-            </div>
-            <div class="form-group">
-                <label for="password">Password</label>
-                <input type="password" id="password" required>
-            </div>
-            <button type="submit">Sign Up</button>
-        </form>
-        <p style="text-align: center; margin: 1rem 0;">OR</p>
-        <button id="googleSignInBtn" class="google-btn">Sign up with Google</button>
-
-        <div id="message" class="message"></div>
-        <div class="link">
-            <p>Already have an account? <a href="./login.html">Log In</a></p>
-        </div>
-    </div>
-
-    <script>
-        const signupForm = document.getElementById('signupForm');
-        const googleSignInBtn = document.getElementById('googleSignInBtn');
-        const messageDiv = document.getElementById('message');
-
-        // Handler for standard email/password signup
-        signupForm.addEventListener('submit', async (event) => {
-            event.preventDefault();
-            const email = document.getElementById('email').value;
-            const password = document.getElementById('password').value;
-            
-            try {
-                const response = await fetch('http://127.0.0.1:8000/signup', {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({ email, password })
-                });
-                const data = await response.json();
-                if (response.ok) {
-                    messageDiv.textContent = 'Account created successfully! Redirecting to login...';
-                    messageDiv.className = 'message success';
-                    setTimeout(() => { window.location.href = './login.html'; }, 2000);
-                } else {
-                    messageDiv.textContent = data.detail || 'An error occurred.';
-                    messageDiv.className = 'message error';     
-                }
-            } catch (error) {
-                messageDiv.textContent = 'Could not connect to the server.';
-                messageDiv.className = 'message error';
-            }
-        });
-
-        // Handler for Google Sign-In button
-        googleSignInBtn.addEventListener('click', () => {
-            const GOOGLE_CLIENT_ID = "907619015371-uok8j31a979f7ii4t1094csjf7ij9qqk.apps.googleusercontent.com";
-            const REDIRECT_URI = "http://127.0.0.1:3000/weather-api/google-callback.html";
-            
-            const authUrl = `https://accounts.google.com/o/oauth2/v2/auth?` +
-                          `client_id=${GOOGLE_CLIENT_ID}` +
-                          `&redirect_uri=${REDIRECT_URI}` +
-                          `&response_type=code` +
-                          `&scope=openid%20email%20profile`;
-            
-            window.location.href = authUrl;
-        });
-    </script>
-</body>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Create Account - IntelliWeather</title>
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>👑</text></svg>">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;500;600;700&family=Inter:wght@300;400;500;600&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --royal-gold: #d4af37;
+            --royal-purple: #4a1c6e;
+            --royal-purple-light: #7b4397;
+            --text-primary: #1e293b;
+            --text-secondary: #475569;
+            --text-muted: #94a3b8;
+            --success: #10b981;
+            --error: #ef4444;
+        }
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+        body { 
+            font-family: 'Inter', system-ui, sans-serif;
+            min-height: 100vh;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            padding: 1rem;
+            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+            position: relative;
+            overflow: hidden;
+        }
+
+        /* Background Elements */
+        .orb {
+            position: fixed;
+            border-radius: 50%;
+            filter: blur(80px);
+            opacity: 0.5;
+            animation: float 20s ease-in-out infinite;
+            pointer-events: none;
+        }
+        .orb-1 { width: 500px; height: 500px; background: linear-gradient(135deg, var(--royal-gold), var(--royal-purple)); top: -150px; right: -150px; }
+        .orb-2 { width: 400px; height: 400px; background: linear-gradient(135deg, var(--royal-purple-light), #e94560); bottom: -100px; left: -100px; animation-delay: -10s; }
+        @keyframes float {
+            0%, 100% { transform: translate(0, 0); }
+            50% { transform: translate(-30px, 30px); }
+        }
+
+        /* Auth Card */
+        .auth-card {
+            background: rgba(255, 255, 255, 0.95);
+            backdrop-filter: blur(20px);
+            padding: 3rem;
+            border-radius: 32px;
+            box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+            width: 100%;
+            max-width: 420px;
+            position: relative;
+            z-index: 1;
+            animation: cardEntrance 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+        }
+        @keyframes cardEntrance {
+            from { opacity: 0; transform: translateY(30px) scale(0.95); }
+            to { opacity: 1; transform: translateY(0) scale(1); }
+        }
+        .auth-card::before {
+            content: '✨';
+            position: absolute;
+            top: -25px;
+            left: 50%;
+            transform: translateX(-50%);
+            font-size: 3rem;
+            filter: drop-shadow(0 4px 8px rgba(212, 175, 55, 0.4));
+            animation: sparkle 2s ease-in-out infinite;
+        }
+        @keyframes sparkle {
+            0%, 100% { transform: translateX(-50%) scale(1); opacity: 1; }
+            50% { transform: translateX(-50%) scale(1.2); opacity: 0.8; }
+        }
+
+        .header { text-align: center; margin-bottom: 2rem; }
+        .header h1 {
+            font-family: 'Playfair Display', serif;
+            font-size: 2rem;
+            color: var(--text-primary);
+            margin-bottom: 0.5rem;
+        }
+        .header p { color: var(--text-muted); font-size: 0.95rem; }
+
+        /* Features */
+        .features {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 0.5rem;
+            justify-content: center;
+            margin: 1rem 0 1.5rem;
+        }
+        .feature-tag {
+            background: linear-gradient(135deg, rgba(212, 175, 55, 0.15), rgba(123, 67, 151, 0.15));
+            padding: 0.5rem 1rem;
+            border-radius: 50px;
+            font-size: 0.8rem;
+            font-weight: 500;
+            color: var(--royal-purple);
+            border: 1px solid rgba(212, 175, 55, 0.3);
+        }
+
+        /* Form */
+        .form-group { margin-bottom: 1.25rem; text-align: left; }
+        .form-group label {
+            display: block;
+            font-weight: 600;
+            color: var(--text-primary);
+            margin-bottom: 0.5rem;
+            font-size: 0.9rem;
+        }
+        .form-group input {
+            width: 100%;
+            padding: 1rem 1.25rem;
+            font-size: 1rem;
+            font-family: inherit;
+            border: 2px solid rgba(212, 175, 55, 0.3);
+            border-radius: 16px;
+            background: rgba(248, 250, 252, 0.9);
+            color: var(--text-primary);
+            transition: all 0.3s ease;
+        }
+        .form-group input:focus {
+            outline: none;
+            border-color: var(--royal-gold);
+            background: white;
+            box-shadow: 0 0 0 4px rgba(212, 175, 55, 0.15);
+        }
+        .form-group input::placeholder { color: var(--text-muted); }
+        .form-group small { color: var(--text-muted); font-size: 0.8rem; display: block; margin-top: 0.4rem; }
+
+        /* Submit Button */
+        .submit-btn {
+            width: 100%;
+            padding: 1rem;
+            font-size: 1rem;
+            font-weight: 600;
+            font-family: inherit;
+            color: white;
+            background: linear-gradient(135deg, var(--success), #059669);
+            border: none;
+            border-radius: 16px;
+            cursor: pointer;
+            transition: all 0.3s ease;
+            box-shadow: 0 4px 15px rgba(16, 185, 129, 0.4);
+            margin-bottom: 1.5rem;
+        }
+        .submit-btn:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 8px 25px rgba(16, 185, 129, 0.5);
+        }
+        .submit-btn:active { transform: translateY(0); }
+
+        /* Divider */
+        .divider {
+            display: flex;
+            align-items: center;
+            margin: 1.5rem 0;
+            color: var(--text-muted);
+            font-size: 0.85rem;
+        }
+        .divider::before, .divider::after {
+            content: '';
+            flex: 1;
+            height: 1px;
+            background: rgba(212, 175, 55, 0.3);
+        }
+        .divider span { padding: 0 1rem; }
+
+        /* Google Button */
+        .google-btn {
+            width: 100%;
+            padding: 1rem;
+            font-size: 1rem;
+            font-weight: 500;
+            font-family: inherit;
+            color: var(--text-primary);
+            background: white;
+            border: 2px solid rgba(212, 175, 55, 0.3);
+            border-radius: 16px;
+            cursor: pointer;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            gap: 0.75rem;
+            transition: all 0.3s ease;
+        }
+        .google-btn:hover {
+            border-color: var(--royal-gold);
+            background: rgba(212, 175, 55, 0.05);
+        }
+        .google-btn svg { width: 20px; height: 20px; }
+
+        /* Links */
+        .auth-link {
+            text-align: center;
+            margin-top: 1.5rem;
+            font-size: 0.9rem;
+            color: var(--text-muted);
+        }
+        .auth-link a {
+            color: var(--royal-gold);
+            text-decoration: none;
+            font-weight: 600;
+            transition: color 0.3s ease;
+        }
+        .auth-link a:hover { color: var(--royal-purple); }
+
+        /* Message */
+        .message {
+            padding: 1rem;
+            border-radius: 12px;
+            margin-bottom: 1.5rem;
+            font-size: 0.9rem;
+            display: none;
+            animation: slideIn 0.3s ease;
+        }
+        @keyframes slideIn { from { opacity: 0; transform: translateY(-10px); } to { opacity: 1; transform: translateY(0); } }
+        .message.success { background: rgba(16, 185, 129, 0.1); color: #047857; border: 1px solid rgba(16, 185, 129, 0.3); }
+        .message.error { background: rgba(239, 68, 68, 0.1); color: #dc2626; border: 1px solid rgba(239, 68, 68, 0.3); }
+
+        @media (max-width: 480px) {
+            .auth-card { padding: 2rem 1.5rem; border-radius: 24px; }
+            .header h1 { font-size: 1.75rem; }
+        }
+    </style>
+</head>
+<body>
+    <div class="orb orb-1"></div>
+    <div class="orb orb-2"></div>
+
+    <div class="auth-card">
+        <div class="header">
+            <h1>Create Account</h1>
+            <p>Join the royal weather experience</p>
+        </div>
+
+        <div class="features">
+            <span class="feature-tag">🌡️ Real-time Data</span>
+            <span class="feature-tag">📍 Location-based</span>
+            <span class="feature-tag">📊 7-Day Forecast</span>
+        </div>
+
+        <div class="message" id="message"></div>
+
+        <form id="signup-form">
+            <div class="form-group">
+                <label for="username">Username</label>
+                <input type="text" id="username" placeholder="Choose a username" required minlength="3">
+            </div>
+            <div class="form-group">
+                <label for="email">Email Address</label>
+                <input type="email" id="email" placeholder="you@example.com" required>
+            </div>
+            <div class="form-group">
+                <label for="password">Password</label>
+                <input type="password" id="password" placeholder="Create a strong password" required minlength="8">
+                <small>Min 8 characters with uppercase, lowercase, and number</small>
+            </div>
+            <button type="submit" class="submit-btn">Create Account</button>
+        </form>
+
+        <div class="divider"><span>or continue with</span></div>
+
+        <button class="google-btn" id="google-btn">
+            <svg viewBox="0 0 24 24"><path fill="#4285F4" d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z"/><path fill="#34A853" d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"/><path fill="#FBBC05" d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"/><path fill="#EA4335" d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"/></svg>
+            Sign up with Google
+        </button>
+
+        <p class="auth-link">Already have an account? <a href="/login.html">Sign in</a></p>
+    </div>
+
+    <script>
+        const API_BASE_URL = window.location.hostname === '127.0.0.1' || window.location.hostname === 'localhost' 
+            ? `http://${window.location.hostname}:8000` : window.location.origin;
+
+        function showMessage(text, type) {
+            const msg = document.getElementById('message');
+            msg.textContent = text;
+            msg.className = `message ${type}`;
+            msg.style.display = 'block';
+        }
+
+        document.getElementById('signup-form').addEventListener('submit', async (e) => {
+            e.preventDefault();
+            const data = {
+                username: document.getElementById('username').value,
+                email: document.getElementById('email').value,
+                password: document.getElementById('password').value
+            };
+
+            try {
+                const response = await fetch(`${API_BASE_URL}/auth/signup`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(data)
+                });
+                const result = await response.json();
+                if (response.ok) {
+                    showMessage('Account created! Redirecting...', 'success');
+                    setTimeout(() => window.location.href = '/index.html', 700);
+                } else {
+                    showMessage(result.detail || 'Registration failed', 'error');
+                }
+            } catch (error) {
+                showMessage('Connection error. Please try again.', 'error');
+            }
+        });
+
+        document.getElementById('google-btn').addEventListener('click', () => {
+            const GOOGLE_CLIENT_ID = "907619015371-uok8j31a979f7ii4t1094csjf7ij9qqk.apps.googleusercontent.com";
+            const REDIRECT_URI = `${window.location.origin}/google-callback.html`;
+            const authUrl = `https://accounts.google.com/o/oauth2/v2/auth?client_id=${GOOGLE_CLIENT_ID}&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&response_type=code&scope=openid%20email%20profile`;
+            window.location.href = authUrl;
+        });
+    </script>
+</body>
 </html>
\ No newline at end of file
diff --git a/storage.py b/storage.py
new file mode 100644
index 0000000..a59da83
--- /dev/null
+++ b/storage.py
@@ -0,0 +1,536 @@
+"""
+CSV/Excel-backed Data Storage Layer
+
+This module provides a simple database using CSV files with:
+- User storage (user_id, username, email, hashed_password, created_at)
+- Session storage (session_id, user_id, created_at, last_active_at, expires_at)
+- User search history
+- Cached weather results for popular locations
+- Thread-safe file operations
+- Auto-creation of data directory and CSV files with headers
+"""
+
+import csv
+import os
+import threading
+import uuid
+from datetime import datetime, timezone
+from typing import Optional, List, Dict, Any
+from dataclasses import dataclass, asdict, field
+from pathlib import Path
+from config import settings
+from logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class User:
+    """User model."""
+    user_id: str
+    username: str
+    email: str
+    hashed_password: str
+    created_at: str
+    is_active: bool = True
+    
+    @classmethod
+    def create(cls, username: str, email: str, hashed_password: str) -> "User":
+        """Create a new user with auto-generated ID and timestamp."""
+        return cls(
+            user_id=str(uuid.uuid4()),
+            username=username,
+            email=email,
+            hashed_password=hashed_password,
+            created_at=datetime.now(timezone.utc).isoformat()
+        )
+
+
+@dataclass
+class Session:
+    """Session model."""
+    session_id: str
+    user_id: str
+    created_at: str
+    last_active_at: str
+    expires_at: str
+    is_valid: bool = True
+    
+    @classmethod
+    def create(cls, user_id: str, ttl_seconds: int = None) -> "Session":
+        """Create a new session with auto-generated ID and timestamps."""
+        ttl = ttl_seconds or settings.SESSION_TIMEOUT_SECONDS
+        now = datetime.now(timezone.utc)
+        expires = now.timestamp() + ttl
+        
+        return cls(
+            session_id=str(uuid.uuid4()),
+            user_id=user_id,
+            created_at=now.isoformat(),
+            last_active_at=now.isoformat(),
+            expires_at=datetime.fromtimestamp(expires, timezone.utc).isoformat()
+        )
+    
+    def is_expired(self) -> bool:
+        """Check if the session has expired."""
+        expires = datetime.fromisoformat(self.expires_at)
+        return datetime.now(timezone.utc) > expires
+
+
+@dataclass
+class SearchHistory:
+    """User search history model."""
+    id: str
+    user_id: str
+    query: str
+    lat: float
+    lon: float
+    searched_at: str
+    
+    @classmethod
+    def create(cls, user_id: str, query: str, lat: float, lon: float) -> "SearchHistory":
+        """Create a new search history entry."""
+        return cls(
+            id=str(uuid.uuid4()),
+            user_id=user_id,
+            query=query,
+            lat=lat,
+            lon=lon,
+            searched_at=datetime.now(timezone.utc).isoformat()
+        )
+
+
+@dataclass
+class CachedWeather:
+    """Cached weather data model."""
+    cache_key: str
+    lat: float
+    lon: float
+    location_name: str
+    data_type: str  # current, hourly, daily, aqi
+    data: str  # JSON string
+    created_at: str
+    expires_at: str
+    hit_count: int = 0
+    
+    @classmethod
+    def create(
+        cls,
+        lat: float,
+        lon: float,
+        location_name: str,
+        data_type: str,
+        data: str,
+        ttl_seconds: int = None
+    ) -> "CachedWeather":
+        """Create a new cached weather entry."""
+        ttl = ttl_seconds or settings.CACHE_TTL_SECONDS
+        now = datetime.now(timezone.utc)
+        expires = now.timestamp() + ttl
+        
+        return cls(
+            cache_key=f"{data_type}:{round(lat, 2)}:{round(lon, 2)}",
+            lat=lat,
+            lon=lon,
+            location_name=location_name,
+            data_type=data_type,
+            data=data,
+            created_at=now.isoformat(),
+            expires_at=datetime.fromtimestamp(expires, timezone.utc).isoformat()
+        )
+
+
+class CSVStorage:
+    """
+    Thread-safe CSV-based storage system.
+    
+    Provides CRUD operations for users, sessions, search history,
+    and cached weather data.
+    """
+    
+    # CSV file configurations
+    FILES = {
+        "users": {
+            "filename": "users.csv",
+            "headers": ["user_id", "username", "email", "hashed_password", "created_at", "is_active"]
+        },
+        "sessions": {
+            "filename": "sessions.csv",
+            "headers": ["session_id", "user_id", "created_at", "last_active_at", "expires_at", "is_valid"]
+        },
+        "search_history": {
+            "filename": "search_history.csv",
+            "headers": ["id", "user_id", "query", "lat", "lon", "searched_at"]
+        },
+        "cached_weather": {
+            "filename": "cached_weather.csv",
+            "headers": ["cache_key", "lat", "lon", "location_name", "data_type", "data", "created_at", "expires_at", "hit_count"]
+        }
+    }
+    
+    def __init__(self, data_dir: str = None):
+        """
+        Initialize the storage system.
+        
+        Args:
+            data_dir: Directory for CSV files (uses settings if not specified)
+        """
+        self._data_dir = data_dir or settings.DATA_DIR
+        self._locks: Dict[str, threading.RLock] = {
+            name: threading.RLock() for name in self.FILES
+        }
+        self._init_storage()
+        logger.info(f"CSV storage initialized at {self._data_dir}")
+    
+    def _init_storage(self) -> None:
+        """Initialize storage directory and CSV files."""
+        # Create data directory
+        Path(self._data_dir).mkdir(parents=True, exist_ok=True)
+        
+        # Initialize each CSV file with headers if it doesn't exist
+        for name, config in self.FILES.items():
+            filepath = self._get_filepath(name)
+            if not os.path.exists(filepath):
+                with open(filepath, "w", newline="", encoding="utf-8") as f:
+                    writer = csv.writer(f)
+                    writer.writerow(config["headers"])
+                logger.info(f"Created {config['filename']} with headers")
+    
+    def _get_filepath(self, file_type: str) -> str:
+        """Get the full path for a CSV file."""
+        return os.path.join(self._data_dir, self.FILES[file_type]["filename"])
+    
+    def _read_all(self, file_type: str) -> List[Dict[str, Any]]:
+        """Read all rows from a CSV file."""
+        filepath = self._get_filepath(file_type)
+        headers = self.FILES[file_type]["headers"]
+        
+        with self._locks[file_type]:
+            with open(filepath, "r", newline="", encoding="utf-8") as f:
+                reader = csv.DictReader(f)
+                return list(reader)
+    
+    def _write_all(self, file_type: str, rows: List[Dict[str, Any]]) -> None:
+        """Write all rows to a CSV file."""
+        filepath = self._get_filepath(file_type)
+        headers = self.FILES[file_type]["headers"]
+        
+        with self._locks[file_type]:
+            with open(filepath, "w", newline="", encoding="utf-8") as f:
+                writer = csv.DictWriter(f, fieldnames=headers)
+                writer.writeheader()
+                writer.writerows(rows)
+    
+    def _append_row(self, file_type: str, row: Dict[str, Any]) -> None:
+        """Append a single row to a CSV file."""
+        filepath = self._get_filepath(file_type)
+        headers = self.FILES[file_type]["headers"]
+        
+        with self._locks[file_type]:
+            with open(filepath, "a", newline="", encoding="utf-8") as f:
+                writer = csv.DictWriter(f, fieldnames=headers)
+                writer.writerow(row)
+    
+    # ==================== USER OPERATIONS ====================
+    
+    def create_user(self, user: User) -> User:
+        """Create a new user."""
+        # Check for existing user
+        existing = self.get_user_by_email(user.email)
+        if existing:
+            raise ValueError(f"User with email {user.email} already exists")
+        
+        existing = self.get_user_by_username(user.username)
+        if existing:
+            raise ValueError(f"User with username {user.username} already exists")
+        
+        self._append_row("users", asdict(user))
+        logger.info(f"Created user: {user.username}")
+        return user
+    
+    def get_user_by_id(self, user_id: str) -> Optional[User]:
+        """Get a user by ID."""
+        rows = self._read_all("users")
+        for row in rows:
+            if row["user_id"] == user_id:
+                row["is_active"] = row.get("is_active", "True") == "True"
+                return User(**row)
+        return None
+    
+    def get_user_by_email(self, email: str) -> Optional[User]:
+        """Get a user by email."""
+        rows = self._read_all("users")
+        for row in rows:
+            if row["email"].lower() == email.lower():
+                row["is_active"] = row.get("is_active", "True") == "True"
+                return User(**row)
+        return None
+    
+    def get_user_by_username(self, username: str) -> Optional[User]:
+        """Get a user by username."""
+        rows = self._read_all("users")
+        for row in rows:
+            if row["username"].lower() == username.lower():
+                row["is_active"] = row.get("is_active", "True") == "True"
+                return User(**row)
+        return None
+    
+    def update_user(self, user: User) -> User:
+        """Update an existing user."""
+        rows = self._read_all("users")
+        updated = False
+        
+        for i, row in enumerate(rows):
+            if row["user_id"] == user.user_id:
+                rows[i] = asdict(user)
+                updated = True
+                break
+        
+        if updated:
+            self._write_all("users", rows)
+            logger.info(f"Updated user: {user.username}")
+        
+        return user
+    
+    def get_all_users(self) -> List[User]:
+        """Get all users."""
+        rows = self._read_all("users")
+        return [User(**{**row, "is_active": row.get("is_active", "True") == "True"}) for row in rows]
+    
+    # ==================== SESSION OPERATIONS ====================
+    
+    def create_session(self, session: Session) -> Session:
+        """Create a new session."""
+        self._append_row("sessions", asdict(session))
+        logger.info(f"Created session for user: {session.user_id}")
+        return session
+    
+    def get_session(self, session_id: str) -> Optional[Session]:
+        """Get a session by ID."""
+        rows = self._read_all("sessions")
+        for row in rows:
+            if row["session_id"] == session_id:
+                row["is_valid"] = row.get("is_valid", "True") == "True"
+                return Session(**row)
+        return None
+    
+    def update_session(self, session: Session) -> Session:
+        """Update a session (e.g., last_active_at)."""
+        rows = self._read_all("sessions")
+        updated = False
+        
+        for i, row in enumerate(rows):
+            if row["session_id"] == session.session_id:
+                rows[i] = asdict(session)
+                updated = True
+                break
+        
+        if updated:
+            self._write_all("sessions", rows)
+        
+        return session
+    
+    def invalidate_session(self, session_id: str) -> bool:
+        """Invalidate a session."""
+        session = self.get_session(session_id)
+        if session:
+            session.is_valid = False
+            self.update_session(session)
+            logger.info(f"Invalidated session: {session_id}")
+            return True
+        return False
+    
+    def get_user_sessions(self, user_id: str, valid_only: bool = True) -> List[Session]:
+        """Get all sessions for a user."""
+        rows = self._read_all("sessions")
+        sessions = []
+        
+        for row in rows:
+            if row["user_id"] == user_id:
+                row["is_valid"] = row.get("is_valid", "True") == "True"
+                session = Session(**row)
+                if not valid_only or (session.is_valid and not session.is_expired()):
+                    sessions.append(session)
+        
+        return sessions
+    
+    def cleanup_expired_sessions(self) -> int:
+        """Remove expired sessions."""
+        rows = self._read_all("sessions")
+        valid_rows = []
+        removed = 0
+        
+        for row in rows:
+            row["is_valid"] = row.get("is_valid", "True") == "True"
+            session = Session(**row)
+            if session.is_valid and not session.is_expired():
+                valid_rows.append(row)
+            else:
+                removed += 1
+        
+        if removed > 0:
+            self._write_all("sessions", valid_rows)
+            logger.info(f"Cleaned up {removed} expired sessions")
+        
+        return removed
+    
+    def count_active_sessions(self) -> int:
+        """Count active (valid and not expired) sessions."""
+        rows = self._read_all("sessions")
+        count = 0
+        
+        for row in rows:
+            row["is_valid"] = row.get("is_valid", "True") == "True"
+            session = Session(**row)
+            if session.is_valid and not session.is_expired():
+                count += 1
+        
+        return count
+    
+    # ==================== SEARCH HISTORY OPERATIONS ====================
+    
+    def add_search_history(self, entry: SearchHistory) -> SearchHistory:
+        """Add a search history entry."""
+        self._append_row("search_history", asdict(entry))
+        return entry
+    
+    def get_user_search_history(
+        self,
+        user_id: str,
+        limit: int = 10
+    ) -> List[SearchHistory]:
+        """Get search history for a user."""
+        rows = self._read_all("search_history")
+        history = [
+            SearchHistory(**{**row, "lat": float(row["lat"]), "lon": float(row["lon"])})
+            for row in rows
+            if row["user_id"] == user_id
+        ]
+        # Sort by most recent and limit
+        history.sort(key=lambda x: x.searched_at, reverse=True)
+        return history[:limit]
+    
+    # ==================== CACHED WEATHER OPERATIONS ====================
+    
+    def save_cached_weather(self, entry: CachedWeather) -> CachedWeather:
+        """Save or update cached weather data."""
+        rows = self._read_all("cached_weather")
+        
+        # Check if entry exists
+        for i, row in enumerate(rows):
+            if row["cache_key"] == entry.cache_key:
+                rows[i] = asdict(entry)
+                self._write_all("cached_weather", rows)
+                return entry
+        
+        # New entry
+        self._append_row("cached_weather", asdict(entry))
+        return entry
+    
+    def get_cached_weather(self, cache_key: str) -> Optional[CachedWeather]:
+        """Get cached weather data."""
+        rows = self._read_all("cached_weather")
+        
+        for row in rows:
+            if row["cache_key"] == cache_key:
+                # Check expiration
+                expires = datetime.fromisoformat(row["expires_at"])
+                if datetime.now(timezone.utc) > expires:
+                    return None
+                
+                return CachedWeather(
+                    **{
+                        **row,
+                        "lat": float(row["lat"]),
+                        "lon": float(row["lon"]),
+                        "hit_count": int(row.get("hit_count", 0))
+                    }
+                )
+        
+        return None
+    
+    def increment_weather_cache_hits(self, cache_key: str) -> None:
+        """Increment hit count for cached weather."""
+        rows = self._read_all("cached_weather")
+        
+        for i, row in enumerate(rows):
+            if row["cache_key"] == cache_key:
+                rows[i]["hit_count"] = str(int(row.get("hit_count", 0)) + 1)
+                self._write_all("cached_weather", rows)
+                break
+    
+    def cleanup_expired_weather_cache(self) -> int:
+        """Remove expired weather cache entries."""
+        rows = self._read_all("cached_weather")
+        valid_rows = []
+        removed = 0
+        now = datetime.now(timezone.utc)
+        
+        for row in rows:
+            expires = datetime.fromisoformat(row["expires_at"])
+            if now <= expires:
+                valid_rows.append(row)
+            else:
+                removed += 1
+        
+        if removed > 0:
+            self._write_all("cached_weather", valid_rows)
+            logger.info(f"Cleaned up {removed} expired weather cache entries")
+        
+        return removed
+    
+    # ==================== UTILITY METHODS ====================
+    
+    def is_writable(self) -> bool:
+        """Check if storage is writable."""
+        try:
+            test_file = os.path.join(self._data_dir, ".write_test")
+            with open(test_file, "w") as f:
+                f.write("test")
+            os.remove(test_file)
+            return True
+        except Exception:
+            return False
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get storage statistics."""
+        return {
+            "users_count": len(self._read_all("users")),
+            "sessions_count": self.count_active_sessions(),
+            "search_history_count": len(self._read_all("search_history")),
+            "cached_weather_count": len(self._read_all("cached_weather")),
+            "data_directory": self._data_dir,
+            "is_writable": self.is_writable()
+        }
+
+
+# Global storage instance
+_storage: Optional[CSVStorage] = None
+
+
+def get_storage() -> CSVStorage:
+    """
+    Get the global storage instance.
+    
+    Returns:
+        The global CSVStorage instance
+    """
+    global _storage
+    if _storage is None:
+        _storage = CSVStorage()
+    return _storage
+
+
+def init_storage(data_dir: str = None) -> CSVStorage:
+    """
+    Initialize (or reinitialize) the global storage.
+    
+    Args:
+        data_dir: Optional custom data directory
+        
+    Returns:
+        The new CSVStorage instance
+    """
+    global _storage
+    _storage = CSVStorage(data_dir)
+    return _storage
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..87afbd6
--- /dev/null
+++ b/tests/__init__.py
@@ -0,0 +1,3 @@
+"""
+Tests package initialization.
+"""
diff --git a/tests/test_modules.py b/tests/test_modules.py
new file mode 100644
index 0000000..c4206c5
--- /dev/null
+++ b/tests/test_modules.py
@@ -0,0 +1,467 @@
+"""
+Unit tests for the Weather API modules.
+
+Run with: pytest tests/ -v
+"""
+
+import pytest
+import time
+import threading
+from datetime import datetime, timezone
+from unittest.mock import Mock, patch, MagicMock
+
+
+# ==================== CACHE TESTS ====================
+
+class TestCache:
+    """Tests for the cache module."""
+    
+    def test_cache_set_and_get(self):
+        """Test basic set and get operations."""
+        from cache import Cache
+        
+        cache = Cache(default_ttl=60, max_size=100, cleanup_interval=300)
+        
+        try:
+            cache.set("test_key", "test_value")
+            result = cache.get("test_key")
+            
+            assert result == "test_value"
+        finally:
+            cache.shutdown()
+    
+    def test_cache_expiration(self):
+        """Test that cached items expire after TTL."""
+        from cache import Cache
+        
+        cache = Cache(default_ttl=1, max_size=100, cleanup_interval=300)
+        
+        try:
+            cache.set("expiring_key", "value", ttl=1)
+            
+            # Should exist immediately
+            assert cache.get("expiring_key") == "value"
+            
+            # Wait for expiration
+            time.sleep(1.5)
+            
+            # Should be expired
+            assert cache.get("expiring_key") is None
+        finally:
+            cache.shutdown()
+    
+    def test_cache_delete(self):
+        """Test delete operation."""
+        from cache import Cache
+        
+        cache = Cache(default_ttl=60, max_size=100, cleanup_interval=300)
+        
+        try:
+            cache.set("delete_key", "value")
+            assert cache.get("delete_key") == "value"
+            
+            result = cache.delete("delete_key")
+            assert result is True
+            assert cache.get("delete_key") is None
+            
+            # Deleting non-existent key
+            result = cache.delete("non_existent")
+            assert result is False
+        finally:
+            cache.shutdown()
+    
+    def test_cache_keys(self):
+        """Test keys listing."""
+        from cache import Cache
+        
+        cache = Cache(default_ttl=60, max_size=100, cleanup_interval=300)
+        
+        try:
+            cache.set("prefix:key1", "value1")
+            cache.set("prefix:key2", "value2")
+            cache.set("other:key3", "value3")
+            
+            all_keys = cache.keys()
+            assert len(all_keys) == 3
+            
+            prefix_keys = cache.keys("prefix:")
+            assert len(prefix_keys) == 2
+            assert "prefix:key1" in prefix_keys
+            assert "prefix:key2" in prefix_keys
+        finally:
+            cache.shutdown()
+    
+    def test_cache_stats(self):
+        """Test statistics tracking."""
+        from cache import Cache
+        
+        cache = Cache(default_ttl=60, max_size=100, cleanup_interval=300)
+        
+        try:
+            cache.set("stats_key", "value")
+            cache.get("stats_key")  # Hit
+            cache.get("stats_key")  # Hit
+            cache.get("non_existent")  # Miss
+            
+            stats = cache.stats()
+            
+            assert stats["hits"] == 2
+            assert stats["misses"] == 1
+            assert stats["size"] == 1
+        finally:
+            cache.shutdown()
+    
+    def test_cache_thread_safety(self):
+        """Test thread safety of cache operations."""
+        from cache import Cache
+        
+        cache = Cache(default_ttl=60, max_size=1000, cleanup_interval=300)
+        errors = []
+        
+        try:
+            def writer():
+                for i in range(100):
+                    try:
+                        cache.set(f"thread_key_{i}", f"value_{i}")
+                    except Exception as e:
+                        errors.append(e)
+            
+            def reader():
+                for i in range(100):
+                    try:
+                        cache.get(f"thread_key_{i}")
+                    except Exception as e:
+                        errors.append(e)
+            
+            threads = []
+            for _ in range(5):
+                threads.append(threading.Thread(target=writer))
+                threads.append(threading.Thread(target=reader))
+            
+            for t in threads:
+                t.start()
+            
+            for t in threads:
+                t.join()
+            
+            assert len(errors) == 0
+        finally:
+            cache.shutdown()
+    
+    def test_generate_weather_cache_key(self):
+        """Test weather cache key generation."""
+        from cache import generate_weather_cache_key
+        
+        key1 = generate_weather_cache_key(40.7128, -74.0060, "current")
+        key2 = generate_weather_cache_key(40.7129, -74.0061, "current")  # Slightly different
+        
+        # Should be the same due to rounding
+        assert key1 == key2
+        assert key1 == "weather:current:40.71:-74.01"
+
+
+# ==================== STORAGE TESTS ====================
+
+class TestStorage:
+    """Tests for the storage module."""
+    
+    @pytest.fixture
+    def temp_storage(self, tmp_path):
+        """Create a temporary storage instance."""
+        from storage import CSVStorage
+        storage = CSVStorage(str(tmp_path))
+        return storage
+    
+    def test_user_creation(self, temp_storage):
+        """Test user creation."""
+        from storage import User
+        
+        user = User.create(
+            username="testuser",
+            email="test@example.com",
+            hashed_password="hashed_pwd"
+        )
+        
+        created = temp_storage.create_user(user)
+        
+        assert created.user_id is not None
+        assert created.username == "testuser"
+        assert created.email == "test@example.com"
+    
+    def test_user_duplicate_email(self, temp_storage):
+        """Test duplicate email prevention."""
+        from storage import User
+        
+        user1 = User.create("user1", "same@example.com", "pwd1")
+        temp_storage.create_user(user1)
+        
+        user2 = User.create("user2", "same@example.com", "pwd2")
+        
+        with pytest.raises(ValueError):
+            temp_storage.create_user(user2)
+    
+    def test_user_retrieval(self, temp_storage):
+        """Test user retrieval by different fields."""
+        from storage import User
+        
+        user = User.create("findme", "find@example.com", "pwd")
+        temp_storage.create_user(user)
+        
+        by_id = temp_storage.get_user_by_id(user.user_id)
+        by_email = temp_storage.get_user_by_email("find@example.com")
+        by_username = temp_storage.get_user_by_username("findme")
+        
+        assert by_id.user_id == user.user_id
+        assert by_email.email == "find@example.com"
+        assert by_username.username == "findme"
+    
+    def test_session_lifecycle(self, temp_storage):
+        """Test session creation, retrieval, and invalidation."""
+        from storage import Session
+        
+        session = Session.create("user123", ttl_seconds=3600)
+        temp_storage.create_session(session)
+        
+        retrieved = temp_storage.get_session(session.session_id)
+        assert retrieved is not None
+        assert retrieved.user_id == "user123"
+        assert retrieved.is_valid is True
+        
+        # Invalidate
+        temp_storage.invalidate_session(session.session_id)
+        
+        retrieved = temp_storage.get_session(session.session_id)
+        assert retrieved.is_valid is False
+    
+    def test_search_history(self, temp_storage):
+        """Test search history operations."""
+        from storage import SearchHistory
+        
+        entry1 = SearchHistory.create("user1", "New York", 40.71, -74.01)
+        entry2 = SearchHistory.create("user1", "London", 51.51, -0.13)
+        entry3 = SearchHistory.create("user2", "Paris", 48.86, 2.35)
+        
+        temp_storage.add_search_history(entry1)
+        temp_storage.add_search_history(entry2)
+        temp_storage.add_search_history(entry3)
+        
+        user1_history = temp_storage.get_user_search_history("user1")
+        
+        assert len(user1_history) == 2
+    
+    def test_storage_writable(self, temp_storage):
+        """Test storage writability check."""
+        assert temp_storage.is_writable() is True
+    
+    def test_storage_stats(self, temp_storage):
+        """Test storage statistics."""
+        stats = temp_storage.get_stats()
+        
+        assert "users_count" in stats
+        assert "sessions_count" in stats
+        assert "is_writable" in stats
+
+
+# ==================== RATE LIMITER TESTS ====================
+
+class TestRateLimiter:
+    """Tests for the rate limiter."""
+    
+    def test_allows_within_limit(self):
+        """Test that requests within limit are allowed."""
+        from middleware.rate_limiter import SlidingWindowRateLimiter
+        
+        limiter = SlidingWindowRateLimiter(requests_per_window=10, window_seconds=60)
+        
+        for _ in range(10):
+            is_allowed, _ = limiter.is_allowed("test_ip")
+            assert is_allowed is True
+    
+    def test_blocks_over_limit(self):
+        """Test that requests over limit are blocked."""
+        from middleware.rate_limiter import SlidingWindowRateLimiter
+        
+        limiter = SlidingWindowRateLimiter(requests_per_window=5, window_seconds=60)
+        
+        # Use up the limit
+        for _ in range(5):
+            limiter.is_allowed("test_ip")
+        
+        # This should be blocked
+        is_allowed, retry_after = limiter.is_allowed("test_ip")
+        
+        assert is_allowed is False
+        assert retry_after > 0
+    
+    def test_different_ips_independent(self):
+        """Test that different IPs have independent limits."""
+        from middleware.rate_limiter import SlidingWindowRateLimiter
+        
+        limiter = SlidingWindowRateLimiter(requests_per_window=2, window_seconds=60)
+        
+        # IP1 uses up limit
+        limiter.is_allowed("ip1")
+        limiter.is_allowed("ip1")
+        is_allowed, _ = limiter.is_allowed("ip1")
+        assert is_allowed is False
+        
+        # IP2 should still be allowed
+        is_allowed, _ = limiter.is_allowed("ip2")
+        assert is_allowed is True
+    
+    def test_window_sliding(self):
+        """Test that window slides properly."""
+        from middleware.rate_limiter import SlidingWindowRateLimiter
+        
+        limiter = SlidingWindowRateLimiter(requests_per_window=2, window_seconds=1)
+        
+        # Use up limit
+        limiter.is_allowed("test_ip")
+        limiter.is_allowed("test_ip")
+        
+        # Should be blocked
+        is_allowed, _ = limiter.is_allowed("test_ip")
+        assert is_allowed is False
+        
+        # Wait for window to slide
+        time.sleep(1.1)
+        
+        # Should be allowed again
+        is_allowed, _ = limiter.is_allowed("test_ip")
+        assert is_allowed is True
+    
+    def test_stats(self):
+        """Test rate limiter statistics."""
+        from middleware.rate_limiter import SlidingWindowRateLimiter
+        
+        limiter = SlidingWindowRateLimiter(requests_per_window=10, window_seconds=60)
+        
+        limiter.is_allowed("ip1")
+        limiter.is_allowed("ip2")
+        
+        stats = limiter.stats()
+        
+        assert stats["total_requests"] == 2
+        assert stats["unique_ips"] == 2
+
+
+# ==================== SESSION MIDDLEWARE TESTS ====================
+
+class TestSessionMiddleware:
+    """Tests for the session middleware."""
+    
+    def test_session_data_creation(self):
+        """Test SessionData creation."""
+        from session_middleware import SessionData
+        
+        session_data = SessionData()
+        
+        assert session_data.is_authenticated is False
+        assert session_data.user_id is None
+    
+    def test_session_data_authenticated(self):
+        """Test authenticated SessionData."""
+        from session_middleware import SessionData
+        from storage import Session
+        
+        session = Session.create("user123")
+        session_data = SessionData(
+            session=session,
+            user_id="user123",
+            is_authenticated=True
+        )
+        
+        assert session_data.is_authenticated is True
+        assert session_data.user_id == "user123"
+
+
+# ==================== AUTH ROUTE TESTS ====================
+
+class TestAuthRoutes:
+    """Tests for authentication routes."""
+    
+    def test_password_hashing(self):
+        """Test password hashing and verification."""
+        from routes.auth import hash_password, verify_password
+        
+        password = "TestPassword123"
+        hashed = hash_password(password)
+        
+        assert hashed != password
+        assert verify_password(password, hashed) is True
+        assert verify_password("wrong_password", hashed) is False
+
+
+# ==================== METRICS TESTS ====================
+
+class TestMetrics:
+    """Tests for the metrics module."""
+    
+    def test_increment_counter(self):
+        """Test counter increment."""
+        from metrics import Metrics
+        
+        metrics = Metrics()
+        
+        metrics.increment("total_requests")
+        metrics.increment("total_requests")
+        metrics.increment("total_requests", 3)
+        
+        assert metrics.get("total_requests") == 5
+    
+    def test_get_all_counters(self):
+        """Test getting all counters."""
+        from metrics import Metrics
+        
+        metrics = Metrics()
+        
+        metrics.increment("cache_hits", 10)
+        metrics.increment("cache_misses", 5)
+        
+        all_counters = metrics.get_all()
+        
+        assert all_counters["cache_hits"] == 10
+        assert all_counters["cache_misses"] == 5
+    
+    def test_uptime(self):
+        """Test uptime tracking."""
+        from metrics import Metrics
+        
+        metrics = Metrics()
+        
+        time.sleep(0.1)
+        uptime = metrics.uptime_seconds()
+        
+        assert uptime >= 0.1
+
+
+# ==================== CONFIG TESTS ====================
+
+class TestConfig:
+    """Tests for the configuration module."""
+    
+    def test_default_values(self):
+        """Test that default values are set."""
+        from config import Settings
+        
+        settings = Settings()
+        
+        assert settings.APP_NAME == "IntelliWeather"
+        assert settings.CACHE_TTL_SECONDS > 0
+        assert settings.RATE_LIMIT_PER_MIN > 0
+    
+    def test_parse_popular_locations(self):
+        """Test parsing of popular locations."""
+        from config import Settings
+        
+        settings = Settings()
+        locations = settings.parse_popular_locations()
+        
+        assert len(locations) > 0
+        assert "lat" in locations[0]
+        assert "lon" in locations[0]
+        assert "name" in locations[0]
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])
diff --git a/workers/__init__.py b/workers/__init__.py
new file mode 100644
index 0000000..5b40f63
--- /dev/null
+++ b/workers/__init__.py
@@ -0,0 +1,10 @@
+"""
+Background Workers Package
+
+Contains background tasks and scheduled jobs for IntelliWeather.
+"""
+
+from workers.alerts_prefetch import AlertsPrefetcher
+from workers.train_model import ModelTrainer
+
+__all__ = ["AlertsPrefetcher", "ModelTrainer"]
diff --git a/workers/alerts_prefetch.py b/workers/alerts_prefetch.py
new file mode 100644
index 0000000..f38ef44
--- /dev/null
+++ b/workers/alerts_prefetch.py
@@ -0,0 +1,150 @@
+"""
+Alerts Prefetcher Worker
+
+Background worker that periodically fetches weather alerts for popular locations.
+"""
+
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Optional, Callable
+
+from config import settings
+from logging_config import get_logger
+from cache import get_cache
+
+logger = get_logger(__name__)
+
+
+class AlertsPrefetcher:
+    """
+    Background worker for prefetching weather alerts.
+    
+    Runs periodically to cache alerts for popular locations,
+    ensuring fast response times for common requests.
+    """
+    
+    def __init__(
+        self,
+        fetch_alerts_func: Callable,
+        interval_hours: int = None
+    ):
+        """
+        Initialize the alerts prefetcher.
+        
+        Args:
+            fetch_alerts_func: Function to fetch alerts (lat, lon) -> List[Alert]
+            interval_hours: Prefetch interval in hours
+        """
+        self._fetch_alerts = fetch_alerts_func
+        self._interval = (interval_hours or settings.ALERTS_PREFETCH_INTERVAL_HOURS) * 3600
+        self._thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+        self._last_run: Optional[datetime] = None
+        self._alerts_count = 0
+        
+        logger.info(f"Alerts prefetcher initialized with {self._interval / 3600}h interval")
+    
+    def start(self) -> None:
+        """Start the background prefetcher."""
+        if self._thread and self._thread.is_alive():
+            logger.warning("Prefetcher already running")
+            return
+        
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._run_loop,
+            daemon=True,
+            name="alerts-prefetcher"
+        )
+        self._thread.start()
+        logger.info("Alerts prefetcher started")
+    
+    def stop(self) -> None:
+        """Stop the background prefetcher."""
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join(timeout=10)
+        logger.info("Alerts prefetcher stopped")
+    
+    def _run_loop(self) -> None:
+        """Main prefetch loop."""
+        # Initial prefetch
+        self._prefetch_all()
+        
+        while not self._stop_event.wait(self._interval):
+            self._prefetch_all()
+    
+    def _prefetch_all(self) -> None:
+        """Prefetch alerts for all popular locations."""
+        locations = settings.parse_popular_locations()
+        cache = get_cache()
+        
+        logger.info(f"Starting alerts prefetch for {len(locations)} locations")
+        
+        total_alerts = 0
+        
+        for loc in locations:
+            try:
+                alerts = self._fetch_alerts(loc["lat"], loc["lon"])
+                
+                # Cache the alerts
+                cache_key = f"alerts:{loc['lat']}:{loc['lon']}"
+                cache_data = {
+                    "latitude": loc["lat"],
+                    "longitude": loc["lon"],
+                    "location_name": loc["name"],
+                    "alerts": [a.model_dump() if hasattr(a, 'model_dump') else a for a in alerts],
+                    "count": len(alerts),
+                    "last_updated": datetime.now(timezone.utc).isoformat(),
+                    "source": "prefetch"
+                }
+                
+                cache.set(cache_key, cache_data, ttl=900)  # 15 minutes
+                total_alerts += len(alerts)
+                
+            except Exception as e:
+                logger.error(f"Failed to prefetch alerts for {loc['name']}: {e}")
+        
+        self._last_run = datetime.now(timezone.utc)
+        self._alerts_count = total_alerts
+        
+        logger.info(f"Alerts prefetch complete: {total_alerts} alerts for {len(locations)} locations")
+    
+    def trigger_refresh(self) -> dict:
+        """Manually trigger a refresh."""
+        self._prefetch_all()
+        return {
+            "refreshed_at": self._last_run.isoformat() if self._last_run else None,
+            "alerts_count": self._alerts_count
+        }
+    
+    def get_status(self) -> dict:
+        """Get prefetcher status."""
+        return {
+            "running": self._thread.is_alive() if self._thread else False,
+            "last_run": self._last_run.isoformat() if self._last_run else None,
+            "alerts_count": self._alerts_count,
+            "interval_hours": self._interval / 3600,
+            "locations_count": len(settings.parse_popular_locations())
+        }
+
+
+# Global prefetcher instance
+_prefetcher: Optional[AlertsPrefetcher] = None
+
+
+def get_alerts_prefetcher() -> Optional[AlertsPrefetcher]:
+    """Get the global alerts prefetcher instance."""
+    return _prefetcher
+
+
+def init_alerts_prefetcher(fetch_func: Callable) -> AlertsPrefetcher:
+    """Initialize the global alerts prefetcher."""
+    global _prefetcher
+    
+    if _prefetcher:
+        _prefetcher.stop()
+    
+    _prefetcher = AlertsPrefetcher(fetch_func)
+    return _prefetcher
diff --git a/workers/train_model.py b/workers/train_model.py
new file mode 100644
index 0000000..e8f1821
--- /dev/null
+++ b/workers/train_model.py
@@ -0,0 +1,148 @@
+"""
+Model Training Worker
+
+Background worker for retraining the ML prediction model.
+"""
+
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Optional
+
+from config import settings
+from logging_config import get_logger
+from modules.prediction import get_prediction_service
+
+logger = get_logger(__name__)
+
+
+class ModelTrainer:
+    """
+    Background worker for periodic model retraining.
+    
+    Retrains the prediction model on a schedule to keep it up-to-date
+    with recent weather patterns.
+    """
+    
+    def __init__(self, interval_hours: int = None):
+        """
+        Initialize the model trainer.
+        
+        Args:
+            interval_hours: Retrain interval in hours
+        """
+        self._interval = (interval_hours or settings.ML_MODEL_RETRAIN_HOURS) * 3600
+        self._thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+        self._last_train: Optional[datetime] = None
+        self._train_success = False
+        
+        logger.info(f"Model trainer initialized with {self._interval / 3600}h interval")
+    
+    def start(self) -> None:
+        """Start the background trainer."""
+        if self._thread and self._thread.is_alive():
+            logger.warning("Trainer already running")
+            return
+        
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._run_loop,
+            daemon=True,
+            name="model-trainer"
+        )
+        self._thread.start()
+        logger.info("Model trainer started")
+    
+    def stop(self) -> None:
+        """Stop the background trainer."""
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join(timeout=30)
+        logger.info("Model trainer stopped")
+    
+    def _run_loop(self) -> None:
+        """Main training loop."""
+        # Initial training with a default location
+        self._train_default()
+        
+        while not self._stop_event.wait(self._interval):
+            self._train_default()
+    
+    def _train_default(self) -> None:
+        """Train model with data from a popular location."""
+        locations = settings.parse_popular_locations()
+        
+        if not locations:
+            logger.warning("No popular locations configured for training")
+            return
+        
+        # Use first location for training
+        loc = locations[0]
+        
+        logger.info(f"Starting model training with data from {loc['name']}")
+        
+        try:
+            prediction_service = get_prediction_service()
+            success = prediction_service.train_model(loc["lat"], loc["lon"])
+            
+            self._last_train = datetime.now(timezone.utc)
+            self._train_success = success
+            
+            if success:
+                logger.info("Model training completed successfully")
+            else:
+                logger.warning("Model training failed")
+                
+        except Exception as e:
+            logger.error(f"Model training error: {e}")
+            self._train_success = False
+    
+    def trigger_train(self, lat: float, lon: float) -> dict:
+        """Manually trigger training for a specific location."""
+        try:
+            prediction_service = get_prediction_service()
+            success = prediction_service.train_model(lat, lon)
+            
+            self._last_train = datetime.now(timezone.utc)
+            self._train_success = success
+            
+            return {
+                "success": success,
+                "trained_at": self._last_train.isoformat(),
+                "location": f"{lat}, {lon}"
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e)
+            }
+    
+    def get_status(self) -> dict:
+        """Get trainer status."""
+        return {
+            "running": self._thread.is_alive() if self._thread else False,
+            "last_train": self._last_train.isoformat() if self._last_train else None,
+            "last_success": self._train_success,
+            "interval_hours": self._interval / 3600
+        }
+
+
+# Global trainer instance
+_trainer: Optional[ModelTrainer] = None
+
+
+def get_model_trainer() -> Optional[ModelTrainer]:
+    """Get the global model trainer instance."""
+    return _trainer
+
+
+def init_model_trainer() -> ModelTrainer:
+    """Initialize the global model trainer."""
+    global _trainer
+    
+    if _trainer:
+        _trainer.stop()
+    
+    _trainer = ModelTrainer()
+    return _trainer