# lakshyakushwahaaiml2023-ops/crisora-ai architecture

> Architecture diagram of the GitHub repository lakshyakushwahaaiml2023-ops/crisora-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lakshyakushwahaaiml2023-ops/crisora-ai
- Repository: https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai

## Overview

Crisora AI is a multi-role disaster-management platform: citizens and officials use dashboards to monitor risk, report emergencies, and support response decisions. Backend services ingest weather, river, and seismic data, calculate regional risk, and expose authentication, event, SOS, AI, simulation, and broadcast capabilities. The README documents reporting, historical and Bhopal simulations, and multi-channel alerts. Sampled files establish ingestion and risk calculations; several UI and route details are represented from the README and source index rather than inspected source.

Main entry points: [`backend/src/models`](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/backend/src/models) (Domain records), [`frontend/src/pages`](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/frontend/src/pages) (Role dashboards), [`backend/src/routes`](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/backend/src/routes) (API routes), [`backend/src/jobs/ingestCron.js`](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/jobs/ingestCron.js) (Ingestion scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Role-based app<br/>[App.jsx]"]
  node_auth_context["Session context<br/>[AuthContext.jsx]"]
  node_dashboards["Role dashboards"]
  node_map_risk["Maps and risk UI"]
  node_sos_ui["SOS reporting UI<br/>[SOSButton.jsx]"]
  node_ai_ui["AI assistance UI"]
  node_sim_reports["Simulations and reports"]
end

subgraph group_api["Backend API"]
  node_api_routes["API routes"]
  node_auth_middleware["JWT authentication<br/>[auth.js]"]
  node_ai_agent["AI agent<br/>[aiAgent.js]"]
  node_broadcast["SMS and voice broadcast<br/>[broadcast.js]"]
  node_socket["Live updates<br/>[server.js]"]
end

subgraph group_risk["Risk and ingestion"]
  node_ingest_jobs["Ingestion scheduler<br/>[ingestCron.js]"]
  node_weather_ingest["Weather ingestion<br/>[weatherService.js]"]
  node_river_ingest["River ingestion"]
  node_seismic_ingest["Seismic ingestion<br/>[seismicService.js]"]
  node_risk_engine["Regional risk engine<br/>[riskEngine.js]"]
end

subgraph group_data["Persistence"]
  node_domain_data["Domain records"]
  node_mongodb[("MongoDB")]
end

subgraph group_integrations["External services"]
  node_groq{{"Groq AI"}}
  node_weather_provider{{"Weather and flood APIs"}}
  node_usgs{{"USGS earthquakes"}}
  node_twilio_polly{{"Twilio and Polly"}}
end

node_citizens(("Citizens and officials"))

node_citizens -->|"use dashboards"| node_app
node_app -->|"provides session"| node_auth_context
node_app -->|"routes roles"| node_dashboards
node_dashboards -.->|"show situational maps"| node_map_risk
node_dashboards -.->|"trigger SOS"| node_sos_ui
node_dashboards -->|"open AI assistant"| node_ai_ui
node_dashboards -->|"open analysis tools"| node_sim_reports
node_auth_context -.->|"verify session"| node_api_routes
node_api_routes -->|"protect endpoints"| node_auth_middleware
node_api_routes -->|"request assistance"| node_ai_agent
node_ai_agent -.->|"generate guidance"| node_groq
node_ingest_jobs -->|"fetch weather"| node_weather_ingest
node_ingest_jobs -->|"fetch river data"| node_river_ingest
node_ingest_jobs -->|"fetch earthquakes"| node_seismic_ingest
node_weather_ingest -.->|"query observations"| node_weather_provider
node_river_ingest -->|"query river levels"| node_weather_provider
node_seismic_ingest -->|"query events"| node_usgs
node_weather_ingest -->|"save readings"| node_domain_data
node_river_ingest -->|"save readings"| node_domain_data
node_seismic_ingest -->|"save readings"| node_domain_data
node_ingest_jobs -->|"recalculate risk"| node_risk_engine
node_risk_engine -->|"read readings and update regions"| node_domain_data
node_api_routes -.->|"manage events and SOS"| node_domain_data
node_api_routes -.->|"dispatch live alerts"| node_socket
node_risk_engine -->|"emit risk updates"| node_socket
node_broadcast -.->|"translate alerts"| node_groq
node_broadcast -.->|"send SMS and calls"| node_twilio_polly
node_domain_data -.->|"persist records"| node_mongodb

click node_app "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/frontend/src/context/AuthContext.jsx"
click node_dashboards "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/frontend/src/pages"
click node_map_risk "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/frontend/src/components/Map"
click node_sos_ui "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/frontend/src/components/SOSButton/SOSButton.jsx"
click node_ai_ui "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/frontend/src/pages/AIAssistantPage.jsx"
click node_sim_reports "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/frontend/src/pages"
click node_api_routes "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/backend/src/routes"
click node_auth_middleware "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/middleware/auth.js"
click node_ai_agent "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/aiAgent.js"
click node_ingest_jobs "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/jobs/ingestCron.js"
click node_weather_ingest "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/ingestion/weatherService.js"
click node_river_ingest "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/ingestion/riverGaugeService.js"
click node_seismic_ingest "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/ingestion/seismicService.js"
click node_risk_engine "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/riskEngine.js"
click node_domain_data "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/backend/src/models"
click node_broadcast "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/routes/broadcast.js"
click node_socket "https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/server.js"

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_app,node_auth_context,node_dashboards,node_map_risk,node_sos_ui,node_ai_ui,node_sim_reports toneBlue
class node_api_routes,node_auth_middleware,node_ai_agent,node_broadcast,node_socket toneAmber
class node_ingest_jobs,node_weather_ingest,node_river_ingest,node_seismic_ingest,node_risk_engine toneMint
class node_domain_data,node_mongodb toneRose
class node_groq,node_weather_provider,node_usgs,node_twilio_polly,node_citizens toneIndigo
```

## Components

### User experience

- [Role-based app](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session context](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Role dashboards](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/frontend/src/pages): `frontend/src/pages`
- [Maps and risk UI](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/frontend/src/components/Map): `frontend/src/components/Map`
- [SOS reporting UI](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/frontend/src/components/SOSButton/SOSButton.jsx): `frontend/src/components/SOSButton/SOSButton.jsx`
- [AI assistance UI](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/frontend/src/pages/AIAssistantPage.jsx): `frontend/src/pages/AIAssistantPage.jsx`
- [Simulations and reports](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/frontend/src/pages): `frontend/src/pages`

### Backend API

- [API routes](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/backend/src/routes): `backend/src/routes`
- [JWT authentication](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`
- [AI agent](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/aiAgent.js): `backend/src/services/aiAgent.js`
- [SMS and voice broadcast](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/routes/broadcast.js): `backend/src/routes/broadcast.js`
- [Live updates](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/server.js): `backend/src/server.js`

### Risk and ingestion

- [Ingestion scheduler](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/jobs/ingestCron.js): `backend/src/jobs/ingestCron.js`
- [Weather ingestion](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/ingestion/weatherService.js): `backend/src/services/ingestion/weatherService.js`
- [River ingestion](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/ingestion/riverGaugeService.js): `backend/src/services/ingestion/riverGaugeService.js`
- [Seismic ingestion](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/ingestion/seismicService.js): `backend/src/services/ingestion/seismicService.js`
- [Regional risk engine](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/blob/main/backend/src/services/riskEngine.js): `backend/src/services/riskEngine.js`

### Persistence

- [Domain records](https://github.com/lakshyakushwahaaiml2023-ops/crisora-ai/tree/main/backend/src/models): `backend/src/models`
- **MongoDB**

### External services

- **Groq AI**
- **Weather and flood APIs**
- **USGS earthquakes**
- **Twilio and Polly**

### Other components

- **Citizens and officials**

## Connections

- Citizens and officials → Role-based app: use dashboards (evidence: `frontend/src/App.jsx`)
- Role-based app → Session context: provides session (evidence: `frontend/src/App.jsx`)
- Role-based app → Role dashboards: routes roles (evidence: `frontend/src/App.jsx`)
- Role dashboards → Maps and risk UI: show situational maps (evidence: `README.md`)
- Role dashboards → SOS reporting UI: trigger SOS (evidence: `README.md`)
- Role dashboards → AI assistance UI: open AI assistant
- Role dashboards → Simulations and reports: open analysis tools (evidence: `frontend/src/App.jsx`)
- Session context → API routes: verify session
- API routes → JWT authentication: protect endpoints (evidence: `backend/src/routes/ai.js`)
- API routes → AI agent: request assistance (evidence: `backend/src/routes/ai.js`)
- AI agent → Groq AI: generate guidance (evidence: `README.md`)
- Ingestion scheduler → Weather ingestion: fetch weather (evidence: `backend/src/jobs/ingestCron.js`)
- Ingestion scheduler → River ingestion: fetch river data (evidence: `backend/src/jobs/ingestCron.js`)
- Ingestion scheduler → Seismic ingestion: fetch earthquakes (evidence: `backend/src/jobs/ingestCron.js`)
- Weather ingestion → Weather and flood APIs: query observations (evidence: `README.md`)
- River ingestion → Weather and flood APIs: query river levels (evidence: `backend/src/services/ingestion/riverGaugeService.js`)
- Seismic ingestion → USGS earthquakes: query events (evidence: `backend/src/services/ingestion/seismicService.js`)
- Weather ingestion → Domain records: save readings (evidence: `backend/src/services/ingestion/weatherService.js`)
- River ingestion → Domain records: save readings (evidence: `backend/src/services/ingestion/riverGaugeService.js`)
- Seismic ingestion → Domain records: save readings (evidence: `backend/src/services/ingestion/seismicService.js`)
- Ingestion scheduler → Regional risk engine: recalculate risk (evidence: `backend/src/jobs/ingestCron.js`)
- Regional risk engine → Domain records: read readings and update regions (evidence: `backend/src/services/riskEngine.js`)
- API routes → Domain records: manage events and SOS (evidence: `README.md`)
- API routes → Live updates: dispatch live alerts (evidence: `README.md`)
- Regional risk engine → Live updates: emit risk updates (evidence: `backend/src/services/riskEngine.js`)
- SMS and voice broadcast → Groq AI: translate alerts (evidence: `README.md`)
- SMS and voice broadcast → Twilio and Polly: send SMS and calls (evidence: `README.md`)
- Domain records → MongoDB: persist records
