# genix2096/disaster-response-system architecture

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

- Interactive diagram: https://gitdiagram.com/genix2096/disaster-response-system
- Repository: https://github.com/genix2096/disaster-response-system

## Overview

This is a disaster-reporting and alert-management web application. Citizens authenticate, submit incident details and optional photographs, then receive a report record; administrators review, classify, update, or delete reports and manage users. The backend assigns priority and departments, enriches submissions with image metadata and an AI summary, stores records, and dispatches alerts. The graph preserves the separate citizen and administrator authentication paths and the documented AWS integrations. Relationships are limited to README statements and shown source references; some page-level and service wiring is documented but not excerpted.

Main entry points: [`backend/src/controllers/incidentController.js`](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/controllers/incidentController.js) (Incident handling), [`frontend/src/services/api.js`](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/services/api.js) (API clients), [`backend/src/services/dynamoService.js`](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/dynamoService.js) (DynamoDB access), [`backend/src/services/s3Service.js`](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/s3Service.js) (Photo storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Citizen portal"]
  node_citizen_ui["Citizen portal<br/>[ReportIncident.jsx]"]
  node_citizen_history["Incident history<br/>[UserDashboard.jsx]"]
  node_user_auth["Citizen auth state"]
  node_cognito_client["Cognito client<br/>[cognito.js]"]
end

subgraph group_admin["Admin workspace"]
  node_admin_ui["Admin dashboard<br/>[AdminDashboard.jsx]"]
  node_incident_review["Incident review"]
  node_user_management["User management<br/>[UserManagement.jsx]"]
  node_admin_auth["Admin auth state<br/>[AuthContext.jsx]"]
end

subgraph group_api["API and identity"]
  node_api_client["API clients<br/>[api.js]"]
  node_api_server["Express API<br/>[server.js]"]
  node_incident_routes["Incident routes<br/>[incidentRoutes.js]"]
end

subgraph group_workflow["Incident processing"]
  node_incident_controller["Incident handling"]
  node_admin_controller["Admin handling<br/>[adminController.js]"]
  node_user_controller["User endpoints<br/>[userController.js]"]
  node_priority["Priority rules<br/>[priority.js]"]
  node_image_validation["Image validation<br/>[imageValidator.js]"]
end

subgraph group_cloud["Cloud services"]
  node_dynamo["DynamoDB access<br/>[dynamoService.js]"]
  node_user_service["User profiles<br/>[userService.js]"]
  node_s3["Photo storage<br/>[s3Service.js]"]
  node_groq["AI summaries<br/>[groqService.js]"]
  node_sns["Department alerts<br/>[snsService.js]"]
end

node_citizen(("Citizen"))
node_administrator(("Administrator"))
node_cognito["Amazon Cognito"]
node_dynamodb_service[("Amazon DynamoDB")]
node_s3_service["Amazon S3"]
node_groq_service["Groq API"]
node_sns_service["Amazon SNS"]

node_citizen -->|"uses"| node_citizen_ui
node_administrator -->|"uses"| node_admin_ui
node_citizen_ui -.->|"submits reports"| node_api_client
node_citizen_history -.->|"fetches history"| node_api_client
node_user_auth -->|"authenticates with"| node_cognito_client
node_user_auth -->|"loads profile"| node_api_client
node_cognito_client -->|"authenticates"| node_cognito
node_admin_ui -->|"manages reports"| node_api_client
node_incident_review -->|"updates reports"| node_api_client
node_user_management -->|"manages users"| node_api_client
node_admin_auth -.->|"supplies admin token"| node_api_client
node_api_client -->|"sends API requests"| node_api_server
node_api_server -->|"mounts routes"| node_incident_routes
node_incident_routes -->|"dispatches requests"| node_incident_controller
node_incident_controller -->|"determines priority"| node_priority
node_incident_controller -->|"validates image"| node_image_validation
node_incident_controller -->|"stores and reads incidents"| node_dynamo
node_incident_controller -->|"uploads and signs photos"| node_s3
node_incident_controller -->|"generates summary"| node_groq
node_incident_controller -->|"publishes alert"| node_sns
node_admin_controller -->|"marks reports fake"| node_dynamo
node_admin_controller -->|"manages user risk"| node_user_service
node_user_controller -->|"reads user incidents"| node_dynamo
node_user_controller -->|"signs photo URLs"| node_s3
node_dynamo -->|"reads and writes"| node_dynamodb_service
node_user_service -->|"reads and writes profiles"| node_dynamodb_service
node_s3 -->|"stores photographs"| node_s3_service
node_groq -->|"requests summaries"| node_groq_service
node_sns -->|"sends notifications"| node_sns_service

click node_citizen_ui "https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/pages/ReportIncident.jsx"
click node_citizen_history "https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/pages/UserDashboard.jsx"
click node_user_auth "https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/context/UserAuthContext.jsx"
click node_cognito_client "https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/services/cognito.js"
click node_admin_ui "https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/pages/AdminDashboard.jsx"
click node_incident_review "https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/pages/IncidentDetails.jsx"
click node_user_management "https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/components/UserManagement.jsx"
click node_admin_auth "https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/context/AuthContext.jsx"
click node_api_client "https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/services/api.js"
click node_api_server "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/server.js"
click node_incident_routes "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/routes/incidentRoutes.js"
click node_incident_controller "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/controllers/incidentController.js"
click node_admin_controller "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/controllers/adminController.js"
click node_user_controller "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/controllers/userController.js"
click node_priority "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/utils/priority.js"
click node_image_validation "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/utils/imageValidator.js"
click node_dynamo "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/dynamoService.js"
click node_user_service "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/userService.js"
click node_s3 "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/s3Service.js"
click node_groq "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/groqService.js"
click node_sns "https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/snsService.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_citizen_ui,node_citizen_history,node_user_auth,node_cognito_client toneBlue
class node_admin_ui,node_incident_review,node_user_management,node_admin_auth,node_dynamodb_service toneAmber
class node_api_client,node_api_server,node_incident_routes,node_groq_service toneMint
class node_incident_controller,node_admin_controller,node_user_controller,node_priority,node_image_validation toneRose
class node_dynamo,node_user_service,node_s3,node_groq,node_sns,node_citizen,node_administrator,node_cognito,node_s3_service,node_sns_service toneIndigo
```

## Components

### Citizen portal

- [Citizen portal](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/pages/ReportIncident.jsx): `frontend/src/pages/ReportIncident.jsx`
- [Incident history](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/pages/UserDashboard.jsx): `frontend/src/pages/UserDashboard.jsx`
- [Citizen auth state](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/context/UserAuthContext.jsx): `frontend/src/context/UserAuthContext.jsx`
- [Cognito client](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/services/cognito.js): `frontend/src/services/cognito.js`

### Admin workspace

- [Admin dashboard](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/pages/AdminDashboard.jsx): `frontend/src/pages/AdminDashboard.jsx`
- [Incident review](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/pages/IncidentDetails.jsx): `frontend/src/pages/IncidentDetails.jsx`
- [User management](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/components/UserManagement.jsx): `frontend/src/components/UserManagement.jsx`
- [Admin auth state](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`

### API and identity

- [API clients](https://github.com/genix2096/disaster-response-system/blob/master/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Express API](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/server.js): `backend/src/server.js`
- [Incident routes](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/routes/incidentRoutes.js): `backend/src/routes/incidentRoutes.js`

### Incident processing

- [Incident handling](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/controllers/incidentController.js): `backend/src/controllers/incidentController.js`
- [Admin handling](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/controllers/adminController.js): `backend/src/controllers/adminController.js`
- [User endpoints](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/controllers/userController.js): `backend/src/controllers/userController.js`
- [Priority rules](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/utils/priority.js): `backend/src/utils/priority.js`
- [Image validation](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/utils/imageValidator.js): `backend/src/utils/imageValidator.js`

### Cloud services

- [DynamoDB access](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/dynamoService.js): `backend/src/services/dynamoService.js`
- [User profiles](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/userService.js): `backend/src/services/userService.js`
- [Photo storage](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/s3Service.js): `backend/src/services/s3Service.js`
- [AI summaries](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/groqService.js): `backend/src/services/groqService.js`
- [Department alerts](https://github.com/genix2096/disaster-response-system/blob/master/backend/src/services/snsService.js): `backend/src/services/snsService.js`

### Other components

- **Citizen**
- **Administrator**
- **Amazon Cognito**
- **Amazon DynamoDB**
- **Amazon S3**
- **Groq API**
- **Amazon SNS**

## Connections

- Citizen → Citizen portal: uses (evidence: `README.md`)
- Administrator → Admin dashboard: uses (evidence: `README.md`)
- Citizen portal → API clients: submits reports
- Incident history → API clients: fetches history
- Citizen auth state → Cognito client: authenticates with (evidence: `frontend/src/context/UserAuthContext.jsx`)
- Citizen auth state → API clients: loads profile (evidence: `frontend/src/context/UserAuthContext.jsx`)
- Cognito client → Amazon Cognito: authenticates (evidence: `README.md`)
- Admin dashboard → API clients: manages reports (evidence: `frontend/src/pages/AdminDashboard.jsx`)
- Incident review → API clients: updates reports (evidence: `frontend/src/pages/IncidentDetails.jsx`)
- User management → API clients: manages users (evidence: `frontend/src/components/UserManagement.jsx`)
- Admin auth state → API clients: supplies admin token
- API clients → Express API: sends API requests (evidence: `README.md`)
- Express API → Incident routes: mounts routes (evidence: `backend/src/server.js`)
- Incident routes → Incident handling: dispatches requests (evidence: `backend/src/routes/incidentRoutes.js`)
- Incident handling → Priority rules: determines priority (evidence: `backend/src/controllers/incidentController.js`)
- Incident handling → Image validation: validates image (evidence: `backend/src/controllers/incidentController.js`)
- Incident handling → DynamoDB access: stores and reads incidents (evidence: `backend/src/controllers/incidentController.js`)
- Incident handling → Photo storage: uploads and signs photos (evidence: `backend/src/controllers/incidentController.js`)
- Incident handling → AI summaries: generates summary (evidence: `backend/src/controllers/incidentController.js`)
- Incident handling → Department alerts: publishes alert (evidence: `backend/src/controllers/incidentController.js`)
- Admin handling → DynamoDB access: marks reports fake (evidence: `backend/src/controllers/adminController.js`)
- Admin handling → User profiles: manages user risk (evidence: `backend/src/controllers/adminController.js`)
- User endpoints → DynamoDB access: reads user incidents (evidence: `backend/src/controllers/userController.js`)
- User endpoints → Photo storage: signs photo URLs (evidence: `backend/src/controllers/userController.js`)
- DynamoDB access → Amazon DynamoDB: reads and writes (evidence: `README.md`)
- User profiles → Amazon DynamoDB: reads and writes profiles (evidence: `README.md`)
- Photo storage → Amazon S3: stores photographs (evidence: `README.md`)
- AI summaries → Groq API: requests summaries (evidence: `README.md`)
- Department alerts → Amazon SNS: sends notifications (evidence: `README.md`)
