# hwy21i/sirasense architecture

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

- Interactive diagram: https://gitdiagram.com/hwy21i/sirasense
- Repository: https://github.com/hwy21i/sirasense

## Overview

SiraSense is a crowdsourced road-hazard reporting and repair-prioritization application for Addis Ababa. Citizens submit hazard details, photos, and mapped locations; the client calculates transparent priority scores and presents reports on maps. Administrators review reports and update their status. The sampled client service uses in-memory mock data, while the sampled Express backend exposes a health endpoint; the README describes broader GIS, duplicate-detection, persistence, export, and offline capabilities that are not represented by sampled server implementation. Arrows follow explicit routing, imports, or documented behavior.

Main entry points: [`client/src/App.tsx`](https://github.com/hwy21i/sirasense/blob/main/client/src/App.tsx) (App routing), [`client/src/services/hazardService.ts`](https://github.com/hwy21i/sirasense/blob/main/client/src/services/hazardService.ts) (Hazard service), [`client/src/pages/citizen/ReportHazardWizardPage.tsx`](https://github.com/hwy21i/sirasense/blob/main/client/src/pages/citizen/ReportHazardWizardPage.tsx) (Hazard report wizard), [`client/src/pages/citizen/InteractiveMapPage.tsx`](https://github.com/hwy21i/sirasense/blob/main/client/src/pages/citizen/InteractiveMapPage.tsx) (Interactive hazard map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen["Citizen experience"]
  node_report_wizard["Hazard report wizard"]
  node_location_picker["Location picker"]
  node_photo_upload["Photo upload<br/>[FileDropzone.tsx]"]
end

subgraph group_prioritization["Map and prioritization"]
  node_hazard_service["Hazard service<br/>[hazardService.ts]"]
  node_priority_calculator["Priority calculator"]
  node_mock_data[("Demo hazard data<br/>[mockData.ts]")]
  node_interactive_map["Interactive hazard map"]
  node_hazard_map["Map visualization<br/>[HazardMap.tsx]"]
  node_priority_widget["Priority score widget"]
end

subgraph group_administration["Report administration"]
  node_admin_reports["Reports queue"]
  node_report_review["Report review"]
  node_admin_settings["Priority settings"]
end

subgraph group_platform["Client platform"]
  node_app_routes["App routing<br/>[App.tsx]"]
  node_offline_queue[("Offline reports<br/>[OfflineContext.tsx]")]
  node_auth_context["Authentication context<br/>[AuthContext.tsx]"]
  node_service_worker["Service worker<br/>[sw.js]"]
end

subgraph group_backend["API backend"]
  node_health_route["Health route<br/>[health.routes.ts]"]
  node_health_controller["Health controller"]
  node_api_app["Express API app<br/>[app.ts]"]
  node_api_routes["API router<br/>[index.ts]"]
  node_api_config["Environment config<br/>[env.ts]"]
end

node_citizen_actor(("Citizen"))
node_admin_actor(("Administrator"))

node_citizen_actor -->|"uses"| node_app_routes
node_admin_actor -->|"uses"| node_app_routes
node_app_routes -->|"routes to"| node_report_wizard
node_app_routes -->|"routes to"| node_interactive_map
node_app_routes -->|"routes to"| node_admin_reports
node_app_routes -->|"routes to"| node_report_review
node_app_routes -->|"routes to"| node_admin_settings
node_report_wizard -->|"submits to"| node_hazard_service
node_report_wizard -->|"queues offline"| node_offline_queue
node_report_wizard -->|"uses"| node_location_picker
node_report_wizard -->|"uses"| node_photo_upload
node_hazard_service -->|"calculates scores"| node_priority_calculator
node_hazard_service -->|"reads and updates"| node_mock_data
node_interactive_map -->|"loads reports"| node_hazard_service
node_interactive_map -->|"renders"| node_hazard_map
node_admin_reports -->|"loads reports"| node_hazard_service
node_report_review -->|"reviews and updates"| node_hazard_service
node_report_review -->|"renders"| node_hazard_map
node_priority_widget -->|"calculates score"| node_priority_calculator
node_priority_widget -->|"uses demo data"| node_mock_data
node_auth_context -->|"loads demo users"| node_mock_data
node_api_app -->|"mounts"| node_api_routes
node_api_app -->|"configures from"| node_api_config
node_api_routes -->|"registers"| node_health_route
node_health_route -->|"dispatches to"| node_health_controller
node_service_worker -.->|"supports offline mode"| node_offline_queue

click node_app_routes "https://github.com/hwy21i/sirasense/blob/main/client/src/App.tsx"
click node_report_wizard "https://github.com/hwy21i/sirasense/blob/main/client/src/pages/citizen/ReportHazardWizardPage.tsx"
click node_offline_queue "https://github.com/hwy21i/sirasense/blob/main/client/src/context/OfflineContext.tsx"
click node_location_picker "https://github.com/hwy21i/sirasense/blob/main/client/src/components/map/LocationPickerMap.tsx"
click node_photo_upload "https://github.com/hwy21i/sirasense/blob/main/client/src/components/common/FileDropzone.tsx"
click node_hazard_service "https://github.com/hwy21i/sirasense/blob/main/client/src/services/hazardService.ts"
click node_priority_calculator "https://github.com/hwy21i/sirasense/blob/main/client/src/utils/priorityCalculator.ts"
click node_mock_data "https://github.com/hwy21i/sirasense/blob/main/client/src/data/mockData.ts"
click node_interactive_map "https://github.com/hwy21i/sirasense/blob/main/client/src/pages/citizen/InteractiveMapPage.tsx"
click node_hazard_map "https://github.com/hwy21i/sirasense/blob/main/client/src/components/map/HazardMap.tsx"
click node_admin_reports "https://github.com/hwy21i/sirasense/blob/main/client/src/pages/admin/AdminReportsPage.tsx"
click node_report_review "https://github.com/hwy21i/sirasense/blob/main/client/src/pages/admin/AdminReportReviewPage.tsx"
click node_admin_settings "https://github.com/hwy21i/sirasense/blob/main/client/src/pages/admin/SuperAdminSettingsPage.tsx"
click node_priority_widget "https://github.com/hwy21i/sirasense/blob/main/client/src/components/home/PriorityScoreWidget.tsx"
click node_auth_context "https://github.com/hwy21i/sirasense/blob/main/client/src/context/AuthContext.tsx"
click node_health_route "https://github.com/hwy21i/sirasense/blob/main/server/src/routes/health.routes.ts"
click node_health_controller "https://github.com/hwy21i/sirasense/blob/main/server/src/controllers/health.controller.ts"
click node_api_app "https://github.com/hwy21i/sirasense/blob/main/server/src/app.ts"
click node_api_routes "https://github.com/hwy21i/sirasense/blob/main/server/src/routes/index.ts"
click node_api_config "https://github.com/hwy21i/sirasense/blob/main/server/src/config/env.ts"
click node_service_worker "https://github.com/hwy21i/sirasense/blob/main/client/public/sw.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_report_wizard,node_location_picker,node_photo_upload toneBlue
class node_hazard_service,node_priority_calculator,node_mock_data,node_interactive_map,node_hazard_map,node_priority_widget toneAmber
class node_admin_reports,node_report_review,node_admin_settings toneMint
class node_app_routes,node_offline_queue,node_auth_context,node_service_worker toneRose
class node_health_route,node_health_controller,node_api_app,node_api_routes,node_api_config,node_citizen_actor,node_admin_actor toneIndigo
```

## Components

### Citizen experience

- [Hazard report wizard](https://github.com/hwy21i/sirasense/blob/main/client/src/pages/citizen/ReportHazardWizardPage.tsx): `client/src/pages/citizen/ReportHazardWizardPage.tsx`
- [Location picker](https://github.com/hwy21i/sirasense/blob/main/client/src/components/map/LocationPickerMap.tsx): `client/src/components/map/LocationPickerMap.tsx`
- [Photo upload](https://github.com/hwy21i/sirasense/blob/main/client/src/components/common/FileDropzone.tsx): `client/src/components/common/FileDropzone.tsx`

### Map and prioritization

- [Hazard service](https://github.com/hwy21i/sirasense/blob/main/client/src/services/hazardService.ts): `client/src/services/hazardService.ts`
- [Priority calculator](https://github.com/hwy21i/sirasense/blob/main/client/src/utils/priorityCalculator.ts): `client/src/utils/priorityCalculator.ts`
- [Demo hazard data](https://github.com/hwy21i/sirasense/blob/main/client/src/data/mockData.ts): `client/src/data/mockData.ts`
- [Interactive hazard map](https://github.com/hwy21i/sirasense/blob/main/client/src/pages/citizen/InteractiveMapPage.tsx): `client/src/pages/citizen/InteractiveMapPage.tsx`
- [Map visualization](https://github.com/hwy21i/sirasense/blob/main/client/src/components/map/HazardMap.tsx): `client/src/components/map/HazardMap.tsx`
- [Priority score widget](https://github.com/hwy21i/sirasense/blob/main/client/src/components/home/PriorityScoreWidget.tsx): `client/src/components/home/PriorityScoreWidget.tsx`

### Report administration

- [Reports queue](https://github.com/hwy21i/sirasense/blob/main/client/src/pages/admin/AdminReportsPage.tsx): `client/src/pages/admin/AdminReportsPage.tsx`
- [Report review](https://github.com/hwy21i/sirasense/blob/main/client/src/pages/admin/AdminReportReviewPage.tsx): `client/src/pages/admin/AdminReportReviewPage.tsx`
- [Priority settings](https://github.com/hwy21i/sirasense/blob/main/client/src/pages/admin/SuperAdminSettingsPage.tsx): `client/src/pages/admin/SuperAdminSettingsPage.tsx`

### Client platform

- [App routing](https://github.com/hwy21i/sirasense/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Offline reports](https://github.com/hwy21i/sirasense/blob/main/client/src/context/OfflineContext.tsx): `client/src/context/OfflineContext.tsx`
- [Authentication context](https://github.com/hwy21i/sirasense/blob/main/client/src/context/AuthContext.tsx): `client/src/context/AuthContext.tsx`
- [Service worker](https://github.com/hwy21i/sirasense/blob/main/client/public/sw.js): `client/public/sw.js`

### API backend

- [Health route](https://github.com/hwy21i/sirasense/blob/main/server/src/routes/health.routes.ts): `server/src/routes/health.routes.ts`
- [Health controller](https://github.com/hwy21i/sirasense/blob/main/server/src/controllers/health.controller.ts): `server/src/controllers/health.controller.ts`
- [Express API app](https://github.com/hwy21i/sirasense/blob/main/server/src/app.ts): `server/src/app.ts`
- [API router](https://github.com/hwy21i/sirasense/blob/main/server/src/routes/index.ts): `server/src/routes/index.ts`
- [Environment config](https://github.com/hwy21i/sirasense/blob/main/server/src/config/env.ts): `server/src/config/env.ts`

### Other components

- **Citizen**
- **Administrator**

## Connections

- Citizen → App routing: uses
- Administrator → App routing: uses
- App routing → Hazard report wizard: routes to (evidence: `client/src/App.tsx`)
- App routing → Interactive hazard map: routes to (evidence: `client/src/App.tsx`)
- App routing → Reports queue: routes to (evidence: `client/src/App.tsx`)
- App routing → Report review: routes to (evidence: `client/src/App.tsx`)
- App routing → Priority settings: routes to (evidence: `client/src/App.tsx`)
- Hazard report wizard → Hazard service: submits to (evidence: `client/src/pages/citizen/ReportHazardWizardPage.tsx`)
- Hazard report wizard → Offline reports: queues offline (evidence: `client/src/pages/citizen/ReportHazardWizardPage.tsx`)
- Hazard report wizard → Location picker: uses (evidence: `client/src/pages/citizen/ReportHazardWizardPage.tsx`)
- Hazard report wizard → Photo upload: uses (evidence: `client/src/pages/citizen/ReportHazardWizardPage.tsx`)
- Hazard service → Priority calculator: calculates scores (evidence: `client/src/services/hazardService.ts`)
- Hazard service → Demo hazard data: reads and updates (evidence: `client/src/services/hazardService.ts`)
- Interactive hazard map → Hazard service: loads reports (evidence: `client/src/pages/citizen/InteractiveMapPage.tsx`)
- Interactive hazard map → Map visualization: renders (evidence: `client/src/pages/citizen/InteractiveMapPage.tsx`)
- Reports queue → Hazard service: loads reports (evidence: `client/src/pages/admin/AdminReportsPage.tsx`)
- Report review → Hazard service: reviews and updates (evidence: `client/src/pages/admin/AdminReportReviewPage.tsx`)
- Report review → Map visualization: renders (evidence: `client/src/pages/admin/AdminReportReviewPage.tsx`)
- Priority score widget → Priority calculator: calculates score (evidence: `client/src/components/home/PriorityScoreWidget.tsx`)
- Priority score widget → Demo hazard data: uses demo data (evidence: `client/src/pages/public/LandingPage.tsx`)
- Authentication context → Demo hazard data: loads demo users (evidence: `client/src/context/AuthContext.tsx`)
- Express API app → API router: mounts (evidence: `server/src/app.ts`)
- Express API app → Environment config: configures from (evidence: `server/src/app.ts`)
- API router → Health route: registers (evidence: `server/src/routes/index.ts`)
- Health route → Health controller: dispatches to (evidence: `server/src/routes/health.routes.ts`)
- Service worker → Offline reports: supports offline mode