System Architecture

🏗️ System Architecture

---

Overview — 3-Layer Stack

┌─────────────────────────────────────────────────────────────┐
│  External Data Sources                                      │
│  Open-Meteo Weather API  ·  OpenAQ Air Quality API          │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│  AI Server — FastAPI Python  (port 8000)                    │
│                                                             │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐   │
│  │  Ensemble   │  │    Cache     │  │    Anomaly        │   │
│  │   Model     │  │   Manager   │  │    Detector        │   │
│  │ RF+ARIMA+XGB│  │  60-min job │  │  Spike + XAI       │   │
│  └─────────────┘  └──────────────┘  └───────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  District Heatmap · 22 quận · ThreadPoolExecutor    │    │
│  └─────────────────────────────────────────────────────┘    │
└──────────────────────────┬──────────────────────────────────┘
                           │ REST / JSON
┌──────────────────────────▼─────────────────────────────────────┐
│  Backend — ASP.NET Core 8  (port 7276)                         │
│                                                                │
│  AirController  ·  DashboardController  ·  ActivityController  │
│  AnomalyController  ·  AssistantController  ·  AdminController │
│  NotificationController                                        │
│                                                                │
│  ┌───────────────────────────────────────────────┐             │
│  │  PostgreSQL 16 — Users · Preferences ·        │             │
│  │  ActivitySchedules · ChatMessages · AlertLogs │             │
│  └───────────────────────────────────────────────┘             │
└──────────────────────────┬─────────────────────────────────────┘
                           │ REST / JWT Bearer
┌──────────────────────────▼──────────────────────────────────┐
│  Frontend — React 18 + TypeScript + Vite  (port 5173)       │
│                                                             │
│  Dashboard  ·  Activity  ·  Heatmap  ·  Assistant  ·  Guide │
└─────────────────────────────────────────────────────────────┘

---

Core Design Principle: Cache-Based Architecture

The AI model never runs per-request. Instead:

APScheduler (every 60 min)
    └── run_compute()
        ├── Fetch weather + air quality from Open-Meteo / OpenAQ
        ├── Run Ensemble model (RF + ARIMA + XGBoost)
        ├── Write forecast_cache.csv   (7-day hourly × 4 profiles)
        ├── Write history_cache.csv    (30-day hourly × 4 profiles)
        ├── Write current_cache.json   (current snapshot × 4 profiles)
        ├── run_anomaly_detection()    → anomaly_log.json
        ├── _trigger_alert_check()     → .NET sends Telegram/Email
        └── compute_district_heatmap() → district_cache.csv

Benefits:

• Client response time < 50ms (reads CSV/JSON, no model inference)
• Stable under high concurrent traffic
• Admin can trigger manual recompute anytime

---

Technology Stack

Layer	Technology	Version
Frontend	React + TypeScript + Vite	18 / 5.x / 5
Backend	ASP.NET Core	8.0
AI Server	FastAPI + Python	0.111 / 3.11
Database	PostgreSQL	16
ORM	Entity Framework Core	8
Charts	Recharts	latest
AI Chat	Google Gemini	2.5 Flash
Notifications	Telegram Bot + SMTP	—
Container	Docker Compose	2.x

---

Key Source Files

AI Server (src/airsafenet_ai/app/)

File	Purpose
api.py	FastAPI routes + lifespan
predict.py	Main RF inference (lazy-loaded)
ensemble_predict.py	RF + ARIMA + XGBoost ensemble
cache_manager.py	60-min compute pipeline
scheduler.py	APScheduler job
anomaly_detector.py	Spike detection + XAI
districts.py	22-district parallel heatmap
features.py	Lag, rolling, cyclical features
data_loader.py	Open-Meteo + OpenAQ fetch
aqi.py	EPA PM2.5 → AQI conversion
profiles.py	5 health group risk/recommendation
config.py	LAT/LON/paths/constants

Backend (src/airsafenet_backend/)

File	Purpose
Controllers/AirController.cs	/api/air/* — current, forecast, history, explain
Controllers/DashboardController.cs	/api/dashboard/* — summary, chart, full
Controllers/ActivityController.cs	/api/activity/* — CRUD + risk scoring
Controllers/AssistantController.cs	/api/assistant/* — Gemini AI chat
Controllers/NotificationController.cs	/api/notification/* — alert dispatch
Controllers/AdminController.cs	/api/admin/* — cache trigger, status
Services/AiCachedService.cs	Reads from AI server cache via HTTP

Frontend (src/airsafenet_frontend/src/)

Directory	Contents
pages/	Dashboard, Activity, Heatmap, Assistant, Guide, Preferences, Admin
components/dashboard/	30+ visualization components
components/assistant/	Chat, conversations, streaming
components/common/	Toast, SectionHeader, StatusChip
api/	http.ts, air.ts, dashboard.ts, assistant.ts, admin.ts
types/	TypeScript type definitions
hooks/	useAdminCache, useAiExplain, useTypewriter