# raddhikagarg/cold_chain_guardian architecture

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

- Interactive diagram: https://gitdiagram.com/raddhikagarg/cold_chain_guardian
- Repository: https://github.com/raddhikagarg/cold_chain_guardian

## Overview

Cold Chain Guardian is a shipment-monitoring platform with a React dashboard and an Express/MongoDB API. Operators configure cargo limits, assign devices, schedule and depart shipments, review telemetry and exposure history, manage alerts, and complete delivery. Device readings enter through the API, where backend services persist and evaluate them for shipment monitoring. The README also describes opt-in simulated telemetry using that ingestion flow; physical ESP32 integration remains a starter. Relationships for unsampled dashboard and service branches are limited to explicit README documentation or shown imports/routes.

Main entry points: [`frontend/src/App.jsx`](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/App.jsx) (Web Dashboard), [`backend/src/services/readingService.js`](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/readingService.js) (Reading Ingestion), [`backend/src/controllers/shipmentController.js`](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/controllers/shipmentController.js) (Shipment Controller), [`backend/src/app.js`](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/app.js) (Express API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Shipment Operations"]
  node_shipment_service["Shipment Services<br/>[shipmentService.js]"]
  node_lifecycle_service["Lifecycle Service"]
  node_assignment_service["Device Assignment"]
  node_device_service["Device Services<br/>[deviceService.js]"]
end

subgraph group_telemetry["Telemetry and Alerts"]
  node_reading_service["Reading Ingestion<br/>[readingService.js]"]
  node_cargo_evaluation["Cargo Evaluation<br/>[cargoEvaluation.js]"]
  node_alert_service["Alert Evaluation"]
  node_alert_management["Alert Management<br/>[alertService.js]"]
  node_dashboard_service["Dashboard Analytics"]
  node_constants["Monitoring Definitions<br/>[sensors.js]"]
end

subgraph group_backend["Backend API"]
  node_api_app["Express API<br/>[app.js]"]
  node_shipment_routes["Shipment Routes<br/>[shipmentRoutes.js]"]
  node_shipment_controller["Shipment Controller"]
  node_device_controller["Device Controller"]
  node_reading_controller["Reading Controller"]
end

subgraph group_frontend["Dashboard UI"]
  node_dashboard["Web Dashboard<br/>[App.jsx]"]
  node_api_client["API Client<br/>[api.js]"]
  node_shipment_views["Shipment Views<br/>[ShipmentDetail.jsx]"]
  node_device_views["Device Views<br/>[DeviceDetail.jsx]"]
  node_history_views["History Views<br/>[HistoryPage.jsx]"]
  node_alert_views["Alert Views<br/>[AlertsPage.jsx]"]
  node_shipment_utils["Shipment Utilities<br/>[shipments.js]"]
  node_device_utils["Device Utilities<br/>[devices.js]"]
  node_history_utils["History Utilities<br/>[history.js]"]
  node_alert_utils["Alert Utilities<br/>[alerts.js]"]
end

subgraph group_persistence["Persistence"]
  node_database[("MongoDB<br/>[db.js]")]
  node_models[("Domain Models<br/>[index.js]")]
end

node_operator(("Operator"))
node_device(("Monitoring Device"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"calls"| node_api_client
node_api_client -.->|"requests"| node_api_app
node_dashboard -->|"renders"| node_shipment_views
node_dashboard -->|"renders"| node_device_views
node_dashboard -->|"renders"| node_history_views
node_dashboard -->|"renders"| node_alert_views
node_shipment_views -->|"uses"| node_shipment_utils
node_device_views -->|"uses"| node_device_utils
node_history_views -->|"filters with"| node_history_utils
node_alert_views -.->|"uses"| node_alert_utils
node_device -->|"sends readings"| node_api_app
node_api_app -->|"routes"| node_shipment_routes
node_shipment_routes -->|"dispatches"| node_shipment_controller
node_shipment_controller -->|"calls"| node_shipment_service
node_shipment_controller -->|"calls"| node_lifecycle_service
node_shipment_controller -->|"calls"| node_assignment_service
node_device_controller -->|"calls"| node_device_service
node_device_controller -->|"lists readings"| node_reading_service
node_reading_controller -->|"ingests and lists"| node_reading_service
node_reading_service -->|"evaluates cargo"| node_cargo_evaluation
node_reading_service -->|"triggers alerts"| node_alert_service
node_reading_service -->|"loads shipment"| node_shipment_service
node_reading_service -->|"reads and writes"| node_models
node_shipment_service -->|"reads and writes"| node_models
node_lifecycle_service -->|"reads and writes"| node_models
node_cargo_evaluation -.->|"uses sensor definitions"| node_constants
node_dashboard_service -.->|"queries analytics"| node_models
node_api_app -.->|"initializes via server"| node_database
node_operator -->|"acknowledges alerts"| node_alert_management
node_operator -->|"completes delivery"| node_lifecycle_service

click node_dashboard "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/api.js"
click node_shipment_views "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/components/shipments/ShipmentDetail.jsx"
click node_device_views "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/components/devices/DeviceDetail.jsx"
click node_history_views "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/pages/HistoryPage.jsx"
click node_alert_views "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/pages/AlertsPage.jsx"
click node_shipment_utils "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/shipments.js"
click node_device_utils "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/devices.js"
click node_history_utils "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/history.js"
click node_alert_utils "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/alerts.js"
click node_api_app "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/app.js"
click node_shipment_routes "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/routes/shipmentRoutes.js"
click node_shipment_controller "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/controllers/shipmentController.js"
click node_device_controller "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/controllers/deviceController.js"
click node_reading_controller "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/controllers/readingController.js"
click node_shipment_service "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/shipmentService.js"
click node_lifecycle_service "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/shipmentLifecycleService.js"
click node_assignment_service "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/deviceAssignmentService.js"
click node_device_service "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/deviceService.js"
click node_reading_service "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/readingService.js"
click node_cargo_evaluation "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/cargoEvaluation.js"
click node_alert_service "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/systemAlertService.js"
click node_alert_management "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/alertService.js"
click node_dashboard_service "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/dashboardService.js"
click node_database "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/config/db.js"
click node_models "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/models/index.js"
click node_constants "https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/constants/sensors.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_shipment_service,node_lifecycle_service,node_assignment_service,node_device_service toneBlue
class node_reading_service,node_cargo_evaluation,node_alert_service,node_alert_management,node_dashboard_service,node_constants toneAmber
class node_api_app,node_shipment_routes,node_shipment_controller,node_device_controller,node_reading_controller toneMint
class node_dashboard,node_api_client,node_shipment_views,node_device_views,node_history_views,node_alert_views,node_shipment_utils,node_device_utils,node_history_utils,node_alert_utils toneRose
class node_database,node_models,node_operator,node_device toneIndigo
```

## Components

### Shipment Operations

- [Shipment Services](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/shipmentService.js): `backend/src/services/shipmentService.js`
- [Lifecycle Service](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/shipmentLifecycleService.js): `backend/src/services/shipmentLifecycleService.js`
- [Device Assignment](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/deviceAssignmentService.js): `backend/src/services/deviceAssignmentService.js`
- [Device Services](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/deviceService.js): `backend/src/services/deviceService.js`

### Telemetry and Alerts

- [Reading Ingestion](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/readingService.js): `backend/src/services/readingService.js`
- [Cargo Evaluation](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/cargoEvaluation.js): `backend/src/services/cargoEvaluation.js`
- [Alert Evaluation](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/systemAlertService.js): `backend/src/services/systemAlertService.js`
- [Alert Management](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/alertService.js): `backend/src/services/alertService.js`
- [Dashboard Analytics](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/services/dashboardService.js): `backend/src/services/dashboardService.js`
- [Monitoring Definitions](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/constants/sensors.js): `backend/src/constants/sensors.js`

### Backend API

- [Express API](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/app.js): `backend/src/app.js`
- [Shipment Routes](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/routes/shipmentRoutes.js): `backend/src/routes/shipmentRoutes.js`
- [Shipment Controller](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/controllers/shipmentController.js): `backend/src/controllers/shipmentController.js`
- [Device Controller](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/controllers/deviceController.js): `backend/src/controllers/deviceController.js`
- [Reading Controller](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/controllers/readingController.js): `backend/src/controllers/readingController.js`

### Dashboard UI

- [Web Dashboard](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API Client](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/api.js): `frontend/src/utils/api.js`
- [Shipment Views](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/components/shipments/ShipmentDetail.jsx): `frontend/src/components/shipments/ShipmentDetail.jsx`
- [Device Views](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/components/devices/DeviceDetail.jsx): `frontend/src/components/devices/DeviceDetail.jsx`
- [History Views](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/pages/HistoryPage.jsx): `frontend/src/pages/HistoryPage.jsx`
- [Alert Views](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/pages/AlertsPage.jsx): `frontend/src/pages/AlertsPage.jsx`
- [Shipment Utilities](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/shipments.js): `frontend/src/utils/shipments.js`
- [Device Utilities](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/devices.js): `frontend/src/utils/devices.js`
- [History Utilities](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/history.js): `frontend/src/utils/history.js`
- [Alert Utilities](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/frontend/src/utils/alerts.js): `frontend/src/utils/alerts.js`

### Persistence

- [MongoDB](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/config/db.js): `backend/src/config/db.js`
- [Domain Models](https://github.com/raddhikagarg/cold_chain_guardian/blob/main/backend/src/models/index.js): `backend/src/models/index.js`

### Other components

- **Operator**
- **Monitoring Device**

## Connections

- Operator → Web Dashboard: uses (evidence: `README.md`)
- Web Dashboard → API Client: calls (evidence: `frontend/src/App.jsx`)
- API Client → Express API: requests
- Web Dashboard → Shipment Views: renders (evidence: `frontend/src/App.jsx`)
- Web Dashboard → Device Views: renders (evidence: `frontend/src/App.jsx`)
- Web Dashboard → History Views: renders (evidence: `frontend/src/App.jsx`)
- Web Dashboard → Alert Views: renders (evidence: `frontend/src/App.jsx`)
- Shipment Views → Shipment Utilities: uses (evidence: `frontend/src/components/shipments/ShipmentDetail.jsx`)
- Device Views → Device Utilities: uses (evidence: `frontend/src/components/devices/DeviceDetail.jsx`)
- History Views → History Utilities: filters with (evidence: `frontend/src/pages/HistoryPage.jsx`)
- Alert Views → Alert Utilities: uses
- Monitoring Device → Express API: sends readings (evidence: `README.md`)
- Express API → Shipment Routes: routes (evidence: `backend/src/app.js`)
- Shipment Routes → Shipment Controller: dispatches (evidence: `backend/src/routes/shipmentRoutes.js`)
- Shipment Controller → Shipment Services: calls (evidence: `backend/src/controllers/shipmentController.js`)
- Shipment Controller → Lifecycle Service: calls (evidence: `backend/src/controllers/shipmentController.js`)
- Shipment Controller → Device Assignment: calls (evidence: `backend/src/controllers/shipmentController.js`)
- Device Controller → Device Services: calls (evidence: `backend/src/controllers/deviceController.js`)
- Device Controller → Reading Ingestion: lists readings (evidence: `backend/src/controllers/deviceController.js`)
- Reading Controller → Reading Ingestion: ingests and lists (evidence: `backend/src/controllers/readingController.js`)
- Reading Ingestion → Cargo Evaluation: evaluates cargo (evidence: `backend/src/services/readingService.js`)
- Reading Ingestion → Alert Evaluation: triggers alerts (evidence: `backend/src/services/readingService.js`)
- Reading Ingestion → Shipment Services: loads shipment (evidence: `backend/src/services/readingService.js`)
- Reading Ingestion → Domain Models: reads and writes (evidence: `backend/src/services/readingService.js`)
- Shipment Services → Domain Models: reads and writes (evidence: `backend/src/services/shipmentService.js`)
- Lifecycle Service → Domain Models: reads and writes (evidence: `backend/src/services/shipmentLifecycleService.js`)
- Cargo Evaluation → Monitoring Definitions: uses sensor definitions
- Dashboard Analytics → Domain Models: queries analytics
- Express API → MongoDB: initializes via server
- Operator → Alert Management: acknowledges alerts (evidence: `README.md`)
- Operator → Lifecycle Service: completes delivery (evidence: `README.md`)
