# iam-pradeepkumar/chainquake architecture

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

- Interactive diagram: https://gitdiagram.com/iam-pradeepkumar/chainquake
- Repository: https://github.com/iam-pradeepkumar/chainquake

## Overview

ChainQuake monitors supply-chain disruptions, models their cascading impact, and supports operator response through alerts, recovery plans, and simulations. The principal workflow runs from an operator dashboard request through the frontend API client and FastAPI routes into graph, risk, or simulation services; results return to dashboard views. README capabilities include news and weather ingestion, neural graph mapping, email and voice dispatch, and Firebase persistence. Some subsystem links are documented or indexed rather than shown in full source excerpts, so uncertain integrations are omitted.

Main entry points: [`frontend/src/services/api.js`](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/services/api.js) (Frontend API client), [`frontend/src/pages/Dashboard.jsx`](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/pages/Dashboard.jsx) (Dashboard), [`backend/main.py`](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/main.py) (FastAPI application), [`backend/api/simulate.py`](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/simulate.py) (Simulation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator_ui["Operator interface"]
  node_app["App and auth state<br/>[App.jsx]"]
  node_auth_page["Sign-in<br/>[AuthPage.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_network_view["Supply-chain graph"]
  node_risk_view["Risk insights"]
  node_alerts_view["Alerts and dispatch<br/>[AlertsPanel.jsx]"]
  node_simulation_view["Crisis simulator"]
  node_news_view["News feed<br/>[NewsFeed.jsx]"]
  node_chat_view["Chat commander<br/>[ChatCommander.jsx]"]
  node_api_client["Frontend API client<br/>[api.js]"]
end

subgraph group_api["API orchestration"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_alerts_api["Alerts API<br/>[alerts.py]"]
  node_risk_api["Risk API<br/>[risk.py]"]
  node_simulation_api["Simulation API<br/>[simulate.py]"]
  node_news_api["News API<br/>[news.py]"]
  node_chat_api["Chat API<br/>[chat.py]"]
end

subgraph group_intelligence["Supply-chain intelligence"]
  node_graph["Supply-chain graph engine<br/>[graph_engine.py]"]
  node_ai["Risk prediction<br/>[ai_engine.py]"]
  node_simulation["Scenario and recovery engine"]
  node_news_service["News and weather ingestion<br/>[news_service.py]"]
  node_weather["Weather integration<br/>[weather_service.py]"]
  node_notifications["Notification service"]
end

subgraph group_platform["Identity and persistence"]
  node_firebase_client["Firebase web auth<br/>[firebase.js]"]
  node_firebase_admin[("Firebase admin and Firestore<br/>[firebase_admin.py]")]
  node_seed_data["Network and event seed data<br/>[seed_data.py]"]
end

node_operator(("Operator"))
node_operator_email(("Email recipient"))
node_operator_phone(("Phone recipient"))
node_news_sources["News and weather sources"]

node_operator -->|"opens"| node_app
node_app -->|"renders"| node_auth_page
node_app -->|"renders"| node_dashboard
node_app -->|"checks auth"| node_firebase_client
node_auth_page -->|"uses"| node_firebase_client
node_dashboard -->|"renders"| node_network_view
node_dashboard -->|"renders"| node_risk_view
node_dashboard -->|"renders"| node_alerts_view
node_dashboard -->|"renders"| node_simulation_view
node_dashboard -->|"renders"| node_news_view
node_dashboard -->|"renders"| node_chat_view
node_alerts_view -->|"requests"| node_api_client
node_simulation_view -->|"requests"| node_api_client
node_chat_view -->|"requests"| node_api_client
node_api_client -->|"calls alert routes"| node_alerts_api
node_api_client -->|"calls risk routes"| node_risk_api
node_api_client -->|"calls simulation routes"| node_simulation_api
node_api_client -->|"calls news route"| node_news_api
node_api_client -->|"calls chat route"| node_chat_api
node_api_client -->|"calls auth routes"| node_auth_api
node_fastapi -->|"routes to"| node_alerts_api
node_fastapi -->|"routes to"| node_risk_api
node_fastapi -->|"routes to"| node_simulation_api
node_fastapi -->|"routes to"| node_news_api
node_fastapi -->|"routes to"| node_chat_api
node_fastapi -->|"routes to"| node_auth_api
node_alerts_api -->|"reads network risk"| node_graph
node_alerts_api -->|"dispatches alerts"| node_notifications
node_risk_api -->|"queries network"| node_graph
node_risk_api -->|"requests predictions"| node_ai
node_simulation_api -->|"runs scenarios"| node_simulation
node_simulation_api -->|"uses network"| node_graph
node_simulation_api -->|"adds alerts"| node_alerts_api
node_simulation_api -->|"dispatches notifications"| node_notifications
node_news_api -->|"gets news"| node_news_service
node_chat_api -->|"uses intelligence"| node_ai
node_chat_api -->|"queries network"| node_graph
node_simulation -->|"loads disruption templates"| node_seed_data
node_simulation -->|"simulates and recovers"| node_graph
node_graph -->|"persists graph updates"| node_firebase_admin
node_news_service -->|"uses weather data"| node_weather
node_news_sources -.->|"provides signals"| node_news_service
node_notifications -.->|"sends email"| node_operator_email
node_notifications -.->|"places voice call"| node_operator_phone
node_auth_api -->|"verifies and saves users"| node_firebase_admin
node_firebase_admin -->|"seeds network"| node_seed_data

click node_app "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/App.jsx"
click node_auth_page "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/pages/AuthPage.jsx"
click node_dashboard "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/pages/Dashboard.jsx"
click node_network_view "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/SupplyChainGraph.jsx"
click node_risk_view "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/AIInsightsPanel.jsx"
click node_alerts_view "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/AlertsPanel.jsx"
click node_simulation_view "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/SimulationPanel.jsx"
click node_news_view "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/NewsFeed.jsx"
click node_chat_view "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/ChatCommander.jsx"
click node_api_client "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/services/api.js"
click node_fastapi "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/main.py"
click node_auth_api "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/auth.py"
click node_alerts_api "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/alerts.py"
click node_risk_api "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/risk.py"
click node_simulation_api "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/simulate.py"
click node_news_api "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/news.py"
click node_chat_api "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/chat.py"
click node_graph "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/graph_engine.py"
click node_ai "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/ai_engine.py"
click node_simulation "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/simulation_engine.py"
click node_news_service "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/news_service.py"
click node_weather "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/weather_service.py"
click node_notifications "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/notification_service.py"
click node_firebase_client "https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/firebase.js"
click node_firebase_admin "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/core/firebase_admin.py"
click node_seed_data "https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/core/seed_data.py"

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_page,node_dashboard,node_network_view,node_risk_view,node_alerts_view,node_simulation_view,node_news_view,node_chat_view,node_api_client toneBlue
class node_fastapi,node_auth_api,node_alerts_api,node_risk_api,node_simulation_api,node_news_api,node_chat_api toneAmber
class node_graph,node_ai,node_simulation,node_news_service,node_weather,node_notifications toneMint
class node_firebase_client,node_firebase_admin,node_seed_data toneRose
class node_operator,node_operator_email,node_operator_phone,node_news_sources toneIndigo
```

## Components

### Operator interface

- [App and auth state](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/pages/AuthPage.jsx): `frontend/src/pages/AuthPage.jsx`
- [Dashboard](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Supply-chain graph](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/SupplyChainGraph.jsx): `frontend/src/components/SupplyChainGraph.jsx`
- [Risk insights](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/AIInsightsPanel.jsx): `frontend/src/components/AIInsightsPanel.jsx`
- [Alerts and dispatch](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/AlertsPanel.jsx): `frontend/src/components/AlertsPanel.jsx`
- [Crisis simulator](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/SimulationPanel.jsx): `frontend/src/components/SimulationPanel.jsx`
- [News feed](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/NewsFeed.jsx): `frontend/src/components/NewsFeed.jsx`
- [Chat commander](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/components/ChatCommander.jsx): `frontend/src/components/ChatCommander.jsx`
- [Frontend API client](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API orchestration

- [FastAPI application](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/main.py): `backend/main.py`
- [Authentication API](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/auth.py): `backend/api/auth.py`
- [Alerts API](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/alerts.py): `backend/api/alerts.py`
- [Risk API](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/risk.py): `backend/api/risk.py`
- [Simulation API](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/simulate.py): `backend/api/simulate.py`
- [News API](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/news.py): `backend/api/news.py`
- [Chat API](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/api/chat.py): `backend/api/chat.py`

### Supply-chain intelligence

- [Supply-chain graph engine](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/graph_engine.py): `backend/services/graph_engine.py`
- [Risk prediction](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/ai_engine.py): `backend/services/ai_engine.py`
- [Scenario and recovery engine](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/simulation_engine.py): `backend/services/simulation_engine.py`
- [News and weather ingestion](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/news_service.py): `backend/services/news_service.py`
- [Weather integration](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/weather_service.py): `backend/services/weather_service.py`
- [Notification service](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/services/notification_service.py): `backend/services/notification_service.py`

### Identity and persistence

- [Firebase web auth](https://github.com/iam-pradeepkumar/chainquake/blob/main/frontend/src/firebase.js): `frontend/src/firebase.js`
- [Firebase admin and Firestore](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/core/firebase_admin.py): `backend/core/firebase_admin.py`
- [Network and event seed data](https://github.com/iam-pradeepkumar/chainquake/blob/main/backend/core/seed_data.py): `backend/core/seed_data.py`

### Other components

- **Operator**
- **Email recipient**
- **Phone recipient**
- **News and weather sources**

## Connections

- Operator → App and auth state: opens (evidence: `frontend/src/App.jsx`)
- App and auth state → Sign-in: renders (evidence: `frontend/src/App.jsx`)
- App and auth state → Dashboard: renders (evidence: `frontend/src/App.jsx`)
- App and auth state → Firebase web auth: checks auth (evidence: `frontend/src/App.jsx`)
- Sign-in → Firebase web auth: uses (evidence: `frontend/src/pages/AuthPage.jsx`)
- Dashboard → Supply-chain graph: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Risk insights: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Alerts and dispatch: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Crisis simulator: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → News feed: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Chat commander: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Alerts and dispatch → Frontend API client: requests (evidence: `frontend/src/components/AlertsPanel.jsx`)
- Crisis simulator → Frontend API client: requests (evidence: `frontend/src/components/SimulationPanel.jsx`)
- Chat commander → Frontend API client: requests (evidence: `frontend/src/components/ChatCommander.jsx`)
- Frontend API client → Alerts API: calls alert routes (evidence: `frontend/src/services/api.js`)
- Frontend API client → Risk API: calls risk routes (evidence: `frontend/src/services/api.js`)
- Frontend API client → Simulation API: calls simulation routes (evidence: `frontend/src/services/api.js`)
- Frontend API client → News API: calls news route (evidence: `frontend/src/services/api.js`)
- Frontend API client → Chat API: calls chat route (evidence: `frontend/src/services/api.js`)
- Frontend API client → Authentication API: calls auth routes (evidence: `frontend/src/services/api.js`)
- FastAPI application → Alerts API: routes to (evidence: `backend/main.py`)
- FastAPI application → Risk API: routes to (evidence: `backend/main.py`)
- FastAPI application → Simulation API: routes to (evidence: `backend/main.py`)
- FastAPI application → News API: routes to (evidence: `backend/main.py`)
- FastAPI application → Chat API: routes to (evidence: `backend/main.py`)
- FastAPI application → Authentication API: routes to (evidence: `backend/main.py`)
- Alerts API → Supply-chain graph engine: reads network risk (evidence: `backend/api/alerts.py`)
- Alerts API → Notification service: dispatches alerts (evidence: `backend/api/alerts.py`)
- Risk API → Supply-chain graph engine: queries network (evidence: `backend/api/risk.py`)
- Risk API → Risk prediction: requests predictions (evidence: `backend/api/risk.py`)
- Simulation API → Scenario and recovery engine: runs scenarios (evidence: `backend/api/simulate.py`)
- Simulation API → Supply-chain graph engine: uses network (evidence: `backend/api/simulate.py`)
- Simulation API → Alerts API: adds alerts (evidence: `backend/api/simulate.py`)
- Simulation API → Notification service: dispatches notifications (evidence: `backend/api/simulate.py`)
- News API → News and weather ingestion: gets news (evidence: `backend/api/news.py`)
- Chat API → Risk prediction: uses intelligence (evidence: `backend/api/chat.py`)
- Chat API → Supply-chain graph engine: queries network (evidence: `backend/api/chat.py`)
- Scenario and recovery engine → Network and event seed data: loads disruption templates (evidence: `backend/services/simulation_engine.py`)
- Scenario and recovery engine → Supply-chain graph engine: simulates and recovers (evidence: `backend/services/simulation_engine.py`)
- Supply-chain graph engine → Firebase admin and Firestore: persists graph updates (evidence: `backend/services/graph_engine.py`)
- News and weather ingestion → Weather integration: uses weather data (evidence: `backend/services/news_service.py`)
- News and weather sources → News and weather ingestion: provides signals
- Notification service → Email recipient: sends email (evidence: `README.md`)
- Notification service → Phone recipient: places voice call (evidence: `README.md`)
- Authentication API → Firebase admin and Firestore: verifies and saves users (evidence: `backend/api/auth.py`)
- Firebase admin and Firestore → Network and event seed data: seeds network (evidence: `backend/core/firebase_admin.py`)
