docs/architecture.md

Architecture / 架构

Request flow / 请求流程

┌──────────────┐ 1. click(lat,lon)  ┌──────────────────────────────┐
│   Browser    │ ─────────────────► │  FastAPI  /api/predict        │
│  Vue3 + Map  │                    │                               │
└──────────────┘ ◄───────────────── │  ┌─────────────────────────┐  │
                  6. JSON response  │  │  Cache lookup           │  │
                                    │  │  (WAL SQLite, 60-600s)  │  │
                                    │  └────────┬────────────────┘  │
                                    │           │ miss              │
                                    │           ▼                   │
                                    │  ┌─────────────────────────┐  │
                                    │  │ 2. Parallel fetch       │  │
                                    │  │  - Open-Meteo (weather) │  │
                                    │  │  - Open-Topo-Data (DEM) │  │
                                    │  └────────┬────────────────┘  │
                                    │           ▼                   │
                                    │  ┌─────────────────────────┐  │
                                    │  │ 3. Engine A — RandomFor │  │
                                    │  │    predict_proba → P    │  │
                                    │  └────────┬────────────────┘  │
                                    │           ▼                   │
                                    │  ┌─────────────────────────┐  │
                                    │  │ 4. Engine B — Rules     │  │
                                    │  │  ┌───────────────────┐  │  │
                                    │  │  │ P4.3 four hazard  │  │  │
                                    │  │  │  sub-scorers      │  │  │
                                    │  │  └─────────┬─────────┘  │  │
                                    │  │  ┌───────────────────┐  │  │
                                    │  │  │ §3.7.2 decision   │  │  │
                                    │  │  │  table R1-R4      │  │  │
                                    │  │  └─────────┬─────────┘  │  │
                                    │  │  ┌───────────────────┐  │  │
                                    │  │  │ Veto cascade      │  │  │
                                    │  │  └─────────┬─────────┘  │  │
                                    │  │  ┌───────────────────┐  │  │
                                    │  │  │ P4.4 activity-    │  │  │
                                    │  │  │  weighted composite│ │  │
                                    │  │  └─────────┬─────────┘  │  │
                                    │  │    Bilingual advice    │  │
                                    │  └────────┬───────────────┘  │
                                    │           ▼                   │
                                    │  ┌─────────────────────────┐  │
                                    │  │ 5. Cache + audit log    │  │
                                    │  │    risk-adaptive TTL    │  │
                                    │  └────────┬────────────────┘  │
                                    │           ▼                   │
                                    │      response JSON            │
                                    └──────────────────────────────┘

Why "Hybrid"? / 为什么是混合架构？

Failure mode of pure ML: feed Mt Everest coordinates → trained on tropical Malaysian mountains → predicts ~0 % rain → ignores -30 °C, 80 km/h winds, 8800 m hypoxia → returns "Safe". A hiker dies.

Mitigation: the Rule Engine is the safety net. It encodes physical / medical thresholds that are true everywhere, not learned from data. ML provides nuanced in-distribution probability; rules provide bounded out-of-distribution guarantees.

This split — learnable component + symbolic component — is the Neuro-Symbolic AI paradigm (Garcez & Lamb, 2020).

Engine B internals (D5 proposal §3.7 — P4)

Engine B is structured in one-to-one correspondence with sub-process §3.7 of the proposal so the thesis chapter can quote line numbers directly:

Proposal section	Code artefact	What it does
P4.1 Load Dynamic Risk Rules	backend/config.py — DECISION_TABLE_3_7_2, ACTIVITY_WEIGHTS, all PENALTY_* / threshold constants	Single source of truth for every threshold, weight, and rule, each annotated with the citation it is derived from.
P4.2 Fetch User Context	?activity={hiker,driver,construction,general} query parameter, plumbed to evaluate(activity=…)	Captures who the user is so weights can be applied later.
P4.3 Evaluate Environmental Risks	Four score_*_risk() functions in rule_engine.py: rainfall, fog, wind gust, thunderstorm	Each returns a 0-100 sub-score using ML probability + weather + terrain inputs.
§3.7.2 Table 4.2 Decision Table	apply_decision_table_3_7_2()	Returns which of R1-R4 fire (hidden rain on windward slope; no amplification on leeward; heavy downpour incoming; normal rain). Emits an [table] line in the XAI log per match.
Veto cascade	_collect_veto_triggers()	Life-safety overrides (altitude hypoxia, extreme cold, gale wind, high CAPE, low visibility, valley flash-flood, orographic-lift storm). When any fires, composite is capped at 100 and a Danger verdict is returned regardless of ML probability.
P4.4 Activity-Specific Weighting	apply_activity_weighting() + ACTIVITY_WEIGHTS matrix	Weights per (activity × hazard) pair (e.g. driver weights fog 1.5×, construction weights wind 1.5×).
P4.5 Composite Risk Score	Same function	Composite = 0.80 · max(weighted sub-scores) + 0.20 · mean(rest). Dominant hazard wins; secondary hazards lift the score modestly.
P4.6 Actionable Advice	_normal_advice() / _veto_advice()	Bilingual EN/ZH narrative mentioning the dominant hazard, the terrain, and the activity.

Why "dominant-hazard composite" instead of a plain weighted sum?

A naive arithmetic mean dilutes the dominant hazard — a thunderstorm sub-score of 90 averaged with three sub-scores of 10 would yield only 30, which understates real danger. The dominant-hazard formula gives the single worst hazard for that user 80 % of the weight; the remaining 20 % captures the compounding effect when multiple hazards are simultaneously elevated. Per-hazard scores are clipped to 100 before aggregation so a weight > 1 cannot push a single sub-score past saturation.

Module responsibilities

Module	Responsibility
backend/main.py	FastAPI app + lifespan (model load, DB init, HTTP client)
backend/ml_engine.py	Load joblib RF, run predict_proba; heuristic fallback when no model artefact
backend/rule_engine.py	Veto cascade + additive scoring + bilingual advice + XAI log
backend/terrain.py	3×3 DEM fetch, slope/aspect/TPI, orographic-uplift dot product
backend/cache.py	WAL-SQLite grid cache, risk-adaptive TTL, inference audit log
backend/config.py	Single source of truth for thresholds + academic citations
backend/schemas.py	Pydantic v2 request/response contract
scripts/1_download_dataset.py	Open-Meteo + Open-Topo-Data ingestion (5 Malaysian sites, 5 years)
scripts/2_preprocess.py	Feature engineering + is_rain_event label derivation
scripts/3_train_model.py	Random Forest + time-based CV + classification report + feature importance
frontend/index.html	Single-file Vue3 SPA: Leaflet map, gauge, XAI log, EN/ZH toggle

Concurrency model

• FastAPI is single-event-loop async. All blocking I/O (SQLite) is wrapped in asyncio.to_thread so it never stalls the loop.
• SQLite is opened in WAL mode (PRAGMA journal_mode=WAL) so readers don't block on writers.
• httpx.AsyncClient is shared across the app via app.state.http, instantiated in lifespan.
• External calls use exponential-backoff retries (tenacity) and 15 s timeouts.

Cache strategy

A naive fixed TTL is unsafe — a 10-minute-stale "Safe" verdict during a developing storm can kill someone. We use risk-adaptive TTL:

Risk score / Veto	TTL
Any Veto fired, or score ≥ 70	60 s
Score 40-70	300 s
Score < 40	600 s

Grid key quantises (lat, lon) to ~1.1 km cells (GRID_RESOLUTION_DEG = 0.01).