# teamdenkwerk/nivara architecture

> Architecture diagram of the GitHub repository teamdenkwerk/nivara, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teamdenkwerk/nivara
- Repository: https://github.com/teamdenkwerk/nivara

## Overview

NIVARA is a disaster-management decision-support platform that turns multi-hazard and population-risk information into evacuation priorities, relocation options, capacity checks, and authority actions. Its user workflow spans hazard intelligence, priority evacuation, safe-site selection, capacity assessment, and operational response; the README also identifies GIS, simulation, reports, voice alerts, and explainable AI as product capabilities. The graph combines those documented capabilities with sampled API, engine, and UI evidence; unsampled feature wiring is represented only where the README documents the workflow.

Main entry points: [`frontend/src/App.tsx`](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/App.tsx) (Web application), [`backend/app/routes/v2_routes.py`](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/routes/v2_routes.py) (Risk and alert routes), [`frontend/src/pages/HazardCommandCenter.tsx`](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/HazardCommandCenter.tsx) (Hazard command), [`backend/app/api/endpoints.py`](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/api/endpoints.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_users["Users & interface"]
  node_frontend["Web application<br/>[App.tsx]"]
  node_risk_ui["Hazard command"]
  node_priority_ui["Evacuation queue<br/>[PriorityQueue.tsx]"]
  node_relocation_ui["Relocation planner"]
  node_capacity_ui["Capacity assessment"]
  node_action_ui["Authority action"]
  node_simulation_ui["Scenario simulator"]
  node_reports_ui["Situation reports<br/>[ProjectReport.tsx]"]
  node_gis_ui["GIS map views<br/>[MapComponent.tsx]"]
end

subgraph group_hazards["Hazard intelligence"]
  node_api["REST API<br/>[endpoints.py]"]
  node_routes_v2["Risk and alert routes<br/>[v2_routes.py]"]
  node_hazard_engines["Hazard engines"]
  node_catchments["Catchment hydrology"]
  node_runout["Runout cascades<br/>[runout_engine.py]"]
  node_bayesian["Bayesian risk"]
  node_xgboost["XGBoost risk<br/>[train_xgboost.py]"]
  node_hazard_modules["Hazard modules"]
  node_maturity["Model trust gate<br/>[maturity_engine.py]"]
end

subgraph group_decisions["Relocation decisions"]
  node_relocation_data["Site and hazard registries"]
  node_capacity_calc["Capacity calculator"]
end

subgraph group_operations["Response &amp; assistance"]
  node_alert_service["Alert lifecycle<br/>[alert_service.py]"]
  node_voice["Voice notifications<br/>[voice_service.py]"]
  node_sms["SMS provider<br/>[sms_provider.py]"]
  node_gemini["AI assistance<br/>[gemini_service.py]"]
end

subgraph group_data["Data &amp; integrations"]
  node_risk_context["Risk context"]
  node_dem["Terrain data<br/>[dem_engine.py]"]
  node_weather["Weather service<br/>[weatherService.ts]"]
end

node_authority(("Emergency authorities"))
node_twilio(("Twilio"))
node_gemini_service(("Gemini service"))

node_authority -->|"uses"| node_frontend
node_frontend -->|"presents"| node_risk_ui
node_frontend -->|"presents"| node_priority_ui
node_frontend -->|"presents"| node_relocation_ui
node_frontend -->|"presents"| node_capacity_ui
node_frontend -->|"presents"| node_action_ui
node_frontend -->|"presents"| node_simulation_ui
node_frontend -->|"presents"| node_reports_ui
node_frontend -->|"presents"| node_gis_ui
node_risk_ui -->|"requests intelligence"| node_api
node_api -->|"dispatches routes"| node_routes_v2
node_routes_v2 -->|"queries catchments"| node_catchments
node_routes_v2 -->|"queries corridors"| node_runout
node_routes_v2 -->|"evaluates trust"| node_maturity
node_routes_v2 -->|"loads context"| node_risk_context
node_routes_v2 -->|"uses inference"| node_bayesian
node_routes_v2 -->|"uses model"| node_xgboost
node_catchments -->|"uses terrain"| node_dem
node_hazard_modules -.->|"expose hazard data"| node_api
node_risk_ui -->|"informs priority"| node_priority_ui
node_priority_ui -->|"sets evacuation need"| node_relocation_ui
node_relocation_ui -->|"reads site profiles"| node_relocation_data
node_relocation_ui -->|"calculates capacity"| node_capacity_calc
node_relocation_ui -->|"opens capacity review"| node_capacity_ui
node_capacity_ui -->|"informs action"| node_action_ui
node_action_ui -->|"requests response"| node_api
node_api -->|"dispatches alert actions"| node_alert_service
node_alert_service -->|"initiates voice call"| node_voice
node_voice -.->|"calls provider"| node_twilio
node_alert_service -.->|"sends SMS"| node_sms
node_maturity -->|"gates dispatch"| node_alert_service
node_simulation_ui -->|"explores scenarios"| node_risk_ui
node_reports_ui -->|"delivers reports"| node_authority
node_gemini -.->|"calls model"| node_gemini_service
node_risk_ui -.->|"requests assistance"| node_gemini
node_risk_ui -.->|"requests weather"| node_weather
node_gis_ui -->|"requests map data"| node_api

click node_frontend "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/App.tsx"
click node_risk_ui "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/HazardCommandCenter.tsx"
click node_priority_ui "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/PriorityQueue.tsx"
click node_relocation_ui "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/RelocationEngine.tsx"
click node_capacity_ui "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/CarryingCapacity.tsx"
click node_action_ui "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/AuthorityAction.tsx"
click node_simulation_ui "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/WhatIfSimulation.tsx"
click node_reports_ui "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/ProjectReport.tsx"
click node_gis_ui "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/components/map/MapComponent.tsx"
click node_api "https://github.com/teamdenkwerk/nivara/blob/main/backend/app/api/endpoints.py"
click node_routes_v2 "https://github.com/teamdenkwerk/nivara/blob/main/backend/app/routes/v2_routes.py"
click node_hazard_engines "https://github.com/teamdenkwerk/nivara/tree/main/backend/app/engines"
click node_catchments "https://github.com/teamdenkwerk/nivara/blob/main/backend/app/engines/catchment_engine.py"
click node_runout "https://github.com/teamdenkwerk/nivara/blob/main/backend/app/engines/runout_engine.py"
click node_bayesian "https://github.com/teamdenkwerk/nivara/blob/main/ml/prediction/bayesian_risk_inference.py"
click node_xgboost "https://github.com/teamdenkwerk/nivara/blob/main/ml/training/train_xgboost.py"
click node_risk_context "https://github.com/teamdenkwerk/nivara/blob/main/backend/app/services/risk_context_service.py"
click node_dem "https://github.com/teamdenkwerk/nivara/blob/main/backend/models/dem_engine.py"
click node_hazard_modules "https://github.com/teamdenkwerk/nivara/tree/main/modules"
click node_maturity "https://github.com/teamdenkwerk/nivara/blob/main/backend/models/maturity_engine.py"
click node_relocation_data "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/data/areaHazardProfiles.ts"
click node_capacity_calc "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/utils/capacityCalculator.ts"
click node_alert_service "https://github.com/teamdenkwerk/nivara/blob/main/backend/app/services/alert_service.py"
click node_voice "https://github.com/teamdenkwerk/nivara/blob/main/backend/app/services/voice_service.py"
click node_sms "https://github.com/teamdenkwerk/nivara/blob/main/backend/app/notifications/sms_provider.py"
click node_gemini "https://github.com/teamdenkwerk/nivara/blob/main/backend/app/services/gemini_service.py"
click node_weather "https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/services/weatherService.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_frontend,node_risk_ui,node_priority_ui,node_relocation_ui,node_capacity_ui,node_action_ui,node_simulation_ui,node_reports_ui,node_gis_ui toneBlue
class node_api,node_routes_v2,node_hazard_engines,node_catchments,node_runout,node_bayesian,node_xgboost,node_hazard_modules,node_maturity toneAmber
class node_relocation_data,node_capacity_calc toneMint
class node_alert_service,node_voice,node_sms,node_gemini toneRose
class node_risk_context,node_dem,node_weather,node_authority,node_twilio,node_gemini_service toneIndigo
```

## Components

### Users & interface

- [Web application](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Hazard command](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/HazardCommandCenter.tsx): `frontend/src/pages/HazardCommandCenter.tsx`
- [Evacuation queue](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/PriorityQueue.tsx): `frontend/src/pages/PriorityQueue.tsx`
- [Relocation planner](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/RelocationEngine.tsx): `frontend/src/pages/RelocationEngine.tsx`
- [Capacity assessment](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/CarryingCapacity.tsx): `frontend/src/pages/CarryingCapacity.tsx`
- [Authority action](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/AuthorityAction.tsx): `frontend/src/pages/AuthorityAction.tsx`
- [Scenario simulator](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/WhatIfSimulation.tsx): `frontend/src/pages/WhatIfSimulation.tsx`
- [Situation reports](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/pages/ProjectReport.tsx): `frontend/src/pages/ProjectReport.tsx`
- [GIS map views](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/components/map/MapComponent.tsx): `frontend/src/components/map/MapComponent.tsx`

### Hazard intelligence

- [REST API](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/api/endpoints.py): `backend/app/api/endpoints.py`
- [Risk and alert routes](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/routes/v2_routes.py): `backend/app/routes/v2_routes.py`
- [Hazard engines](https://github.com/teamdenkwerk/nivara/tree/main/backend/app/engines): `backend/app/engines`
- [Catchment hydrology](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/engines/catchment_engine.py): `backend/app/engines/catchment_engine.py`
- [Runout cascades](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/engines/runout_engine.py): `backend/app/engines/runout_engine.py`
- [Bayesian risk](https://github.com/teamdenkwerk/nivara/blob/main/ml/prediction/bayesian_risk_inference.py): `ml/prediction/bayesian_risk_inference.py`
- [XGBoost risk](https://github.com/teamdenkwerk/nivara/blob/main/ml/training/train_xgboost.py): `ml/training/train_xgboost.py`
- [Hazard modules](https://github.com/teamdenkwerk/nivara/tree/main/modules): `modules`
- [Model trust gate](https://github.com/teamdenkwerk/nivara/blob/main/backend/models/maturity_engine.py): `backend/models/maturity_engine.py`

### Relocation decisions

- [Site and hazard registries](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/data/areaHazardProfiles.ts): `frontend/src/data/areaHazardProfiles.ts`
- [Capacity calculator](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/utils/capacityCalculator.ts): `frontend/src/utils/capacityCalculator.ts`

### Response & assistance

- [Alert lifecycle](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/services/alert_service.py): `backend/app/services/alert_service.py`
- [Voice notifications](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/services/voice_service.py): `backend/app/services/voice_service.py`
- [SMS provider](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/notifications/sms_provider.py): `backend/app/notifications/sms_provider.py`
- [AI assistance](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/services/gemini_service.py): `backend/app/services/gemini_service.py`

### Data & integrations

- [Risk context](https://github.com/teamdenkwerk/nivara/blob/main/backend/app/services/risk_context_service.py): `backend/app/services/risk_context_service.py`
- [Terrain data](https://github.com/teamdenkwerk/nivara/blob/main/backend/models/dem_engine.py): `backend/models/dem_engine.py`
- [Weather service](https://github.com/teamdenkwerk/nivara/blob/main/frontend/src/services/weatherService.ts): `frontend/src/services/weatherService.ts`

### Other components

- **Emergency authorities**
- **Twilio**
- **Gemini service**

## Connections

- Emergency authorities → Web application: uses
- Web application → Hazard command: presents
- Web application → Evacuation queue: presents
- Web application → Relocation planner: presents
- Web application → Capacity assessment: presents
- Web application → Authority action: presents
- Web application → Scenario simulator: presents
- Web application → Situation reports: presents
- Web application → GIS map views: presents
- Hazard command → REST API: requests intelligence
- REST API → Risk and alert routes: dispatches routes
- Risk and alert routes → Catchment hydrology: queries catchments
- Risk and alert routes → Runout cascades: queries corridors
- Risk and alert routes → Model trust gate: evaluates trust
- Risk and alert routes → Risk context: loads context
- Risk and alert routes → Bayesian risk: uses inference
- Risk and alert routes → XGBoost risk: uses model
- Catchment hydrology → Terrain data: uses terrain
- Hazard modules → REST API: expose hazard data
- Hazard command → Evacuation queue: informs priority
- Evacuation queue → Relocation planner: sets evacuation need
- Relocation planner → Site and hazard registries: reads site profiles
- Relocation planner → Capacity calculator: calculates capacity
- Relocation planner → Capacity assessment: opens capacity review
- Capacity assessment → Authority action: informs action
- Authority action → REST API: requests response
- REST API → Alert lifecycle: dispatches alert actions
- Alert lifecycle → Voice notifications: initiates voice call
- Voice notifications → Twilio: calls provider
- Alert lifecycle → SMS provider: sends SMS
- Model trust gate → Alert lifecycle: gates dispatch
- Scenario simulator → Hazard command: explores scenarios
- Situation reports → Emergency authorities: delivers reports
- AI assistance → Gemini service: calls model
- Hazard command → AI assistance: requests assistance
- Hazard command → Weather service: requests weather
- GIS map views → REST API: requests map data