# huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather architecture

> Architecture diagram of the GitHub repository huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather
- Repository: https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather

## Overview

EpiWeather combines epidemiological and ERA5 weather data to forecast weekly influenza and dengue cases and risk, then presents results through a global risk map, country detail pages, and model analytics. The user workflow runs from selecting disease, region, and week in the React interface through API requests to FastAPI forecast services, which retrieve feature snapshots and invoke production models; results return as map risk, four-week forecasts, and historical trends. The README documents ingestion and cross-correlation stages, but their implementation details were not sampled, so those links are documented at subsystem level.

Main entry points: [`src/backend/app/api/v1/api.py`](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/api.py) (REST endpoints), [`src/backend/app/api/v1/endpoints/forecast.py`](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/endpoints/forecast.py) (Forecast endpoint), [`src/backend/app/models/observation.py`](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/models/observation.py) (Epidemiology and feature store), [`src/backend/app/services/prediction_service.py`](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/services/prediction_service.py) (Prediction service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_sources["WHO, OpenDengue, ERA5"]
  node_ingest["Data synchronization"]
  node_lag["Lag and feature analysis"]
end

subgraph group_backend["Forecast backend"]
  node_db[("Epidemiology and feature store<br/>[observation.py]")]
  node_app["FastAPI application<br/>[main.py]"]
  node_routes["REST endpoints<br/>[api.py]"]
  node_forecast_api["Forecast endpoint<br/>[forecast.py]"]
  node_risk_api["Risk map endpoint<br/>[risk.py]"]
  node_analytics_api["Analytics endpoint<br/>[analytics.py]"]
  node_service["Prediction service"]
  node_features["Feature lookup<br/>[feature_lookup.py]"]
  node_models["Production ML inference<br/>[ml_engine.py]"]
  node_risk["Risk classification<br/>[risk_service.py]"]
end

subgraph group_frontend["User experience"]
  node_home["Global risk map<br/>[HomePage.tsx]"]
  node_detail["Country detail"]
  node_hooks["Query hooks<br/>[useForecast.ts]"]
  node_client["API client<br/>[forecast.ts]"]
  node_contracts["API data contracts<br/>[api.ts]"]
end

subgraph group_analytics["Model evaluation"]
  node_analytics_page["Model analytics<br/>[AnalyticsPage.tsx]"]
end

node_user(("Health user"))

node_user -->|"selects disease and week"| node_home
node_user -->|"opens country"| node_detail
node_sources -->|"provides surveillance and weather data"| node_ingest
node_ingest -->|"prepares aligned data"| node_lag
node_lag -.->|"produces features"| node_db
node_app -->|"mounts"| node_routes
node_routes -->|"routes forecast"| node_forecast_api
node_routes -->|"routes risk"| node_risk_api
node_routes -->|"routes analytics"| node_analytics_api
node_forecast_api -->|"calls"| node_service
node_service -->|"loads snapshots"| node_features
node_service -->|"predicts horizons"| node_models
node_features -->|"reads snapshots"| node_db
node_risk_api -.->|"serves risk results"| node_risk
node_risk -->|"uses feature data"| node_features
node_risk -->|"reads prediction data"| node_db
node_analytics_api -.->|"reports model evaluations"| node_db
node_home -.->|"requests map data"| node_hooks
node_detail -->|"requests forecasts and history"| node_hooks
node_hooks -->|"calls"| node_client
node_client -.->|"requests forecast"| node_forecast_api
node_forecast_api -->|"returns forecast schema"| node_contracts
node_contracts -->|"shapes displayed data"| node_detail
node_analytics_page -.->|"requests evaluation data"| node_analytics_api

click node_ingest "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/tree/main/src/scripts"
click node_lag "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/tree/main/src/scripts"
click node_db "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/models/observation.py"
click node_app "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/main.py"
click node_routes "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/api.py"
click node_forecast_api "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/endpoints/forecast.py"
click node_risk_api "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/endpoints/risk.py"
click node_analytics_api "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/endpoints/analytics.py"
click node_service "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/services/prediction_service.py"
click node_features "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/services/feature_lookup.py"
click node_models "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/services/ml_engine.py"
click node_risk "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/services/risk_service.py"
click node_home "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/pages/HomePage.tsx"
click node_detail "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/pages/DiseaseDetailPage.tsx"
click node_analytics_page "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/pages/AnalyticsPage.tsx"
click node_hooks "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/hooks/useForecast.ts"
click node_client "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/api/forecast.ts"
click node_contracts "https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/types/api.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sources,node_ingest,node_lag,node_user toneBlue
class node_db,node_app,node_routes,node_forecast_api,node_risk_api,node_analytics_api,node_service,node_features,node_models,node_risk toneAmber
class node_home,node_detail,node_hooks,node_client,node_contracts toneMint
class node_analytics_page toneRose
```

## Components

### Data preparation

- **WHO, OpenDengue, ERA5**
- [Data synchronization](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/tree/main/src/scripts): `src/scripts`
- [Lag and feature analysis](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/tree/main/src/scripts): `src/scripts`

### Forecast backend

- [Epidemiology and feature store](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/models/observation.py): `src/backend/app/models/observation.py`
- [FastAPI application](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/main.py): `src/backend/app/main.py`
- [REST endpoints](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/api.py): `src/backend/app/api/v1/api.py`
- [Forecast endpoint](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/endpoints/forecast.py): `src/backend/app/api/v1/endpoints/forecast.py`
- [Risk map endpoint](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/endpoints/risk.py): `src/backend/app/api/v1/endpoints/risk.py`
- [Analytics endpoint](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/api/v1/endpoints/analytics.py): `src/backend/app/api/v1/endpoints/analytics.py`
- [Prediction service](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/services/prediction_service.py): `src/backend/app/services/prediction_service.py`
- [Feature lookup](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/services/feature_lookup.py): `src/backend/app/services/feature_lookup.py`
- [Production ML inference](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/services/ml_engine.py): `src/backend/app/services/ml_engine.py`
- [Risk classification](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/backend/app/services/risk_service.py): `src/backend/app/services/risk_service.py`

### User experience

- [Global risk map](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/pages/HomePage.tsx): `src/frontend/src/pages/HomePage.tsx`
- [Country detail](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/pages/DiseaseDetailPage.tsx): `src/frontend/src/pages/DiseaseDetailPage.tsx`
- [Query hooks](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/hooks/useForecast.ts): `src/frontend/src/hooks/useForecast.ts`
- [API client](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/api/forecast.ts): `src/frontend/src/api/forecast.ts`
- [API data contracts](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/types/api.ts): `src/frontend/src/types/api.ts`

### Model evaluation

- [Model analytics](https://github.com/huuluan186/tn-da22tta-110122016-phamhuuluan-epiweather/blob/main/src/frontend/src/pages/AnalyticsPage.tsx): `src/frontend/src/pages/AnalyticsPage.tsx`

### Other components

- **Health user**

## Connections

- Health user → Global risk map: selects disease and week
- Health user → Country detail: opens country
- WHO, OpenDengue, ERA5 → Data synchronization: provides surveillance and weather data
- Data synchronization → Lag and feature analysis: prepares aligned data
- Lag and feature analysis → Epidemiology and feature store: produces features
- FastAPI application → REST endpoints: mounts (evidence: `src/backend/app/main.py`)
- REST endpoints → Forecast endpoint: routes forecast (evidence: `src/backend/app/api/v1/api.py`)
- REST endpoints → Risk map endpoint: routes risk (evidence: `src/backend/app/api/v1/api.py`)
- REST endpoints → Analytics endpoint: routes analytics (evidence: `src/backend/app/api/v1/api.py`)
- Forecast endpoint → Prediction service: calls (evidence: `src/backend/app/api/v1/endpoints/forecast.py`)
- Prediction service → Feature lookup: loads snapshots (evidence: `src/backend/app/services/prediction_service.py`)
- Prediction service → Production ML inference: predicts horizons (evidence: `src/backend/app/services/prediction_service.py`)
- Feature lookup → Epidemiology and feature store: reads snapshots (evidence: `src/backend/app/services/feature_lookup.py`)
- Risk map endpoint → Risk classification: serves risk results
- Risk classification → Feature lookup: uses feature data (evidence: `src/backend/app/services/risk_service.py`)
- Risk classification → Epidemiology and feature store: reads prediction data (evidence: `src/backend/app/services/risk_service.py`)
- Analytics endpoint → Epidemiology and feature store: reports model evaluations
- Global risk map → Query hooks: requests map data
- Country detail → Query hooks: requests forecasts and history (evidence: `src/frontend/src/pages/DiseaseDetailPage.tsx`)
- Query hooks → API client: calls (evidence: `src/frontend/src/hooks/useForecast.ts`)
- API client → Forecast endpoint: requests forecast
- Forecast endpoint → API data contracts: returns forecast schema (evidence: `src/backend/app/api/v1/endpoints/forecast.py`)
- API data contracts → Country detail: shapes displayed data (evidence: `src/frontend/src/pages/DiseaseDetailPage.tsx`)
- Model analytics → Analytics endpoint: requests evaluation data
