# anandrajjee981-max/urbanshield-ai architecture

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

- Interactive diagram: https://gitdiagram.com/anandrajjee981-max/urbanshield-ai
- Repository: https://github.com/anandrajjee981-max/urbanshield-ai

## Overview

UrbanShield AI is a civic-issue platform spanning citizen reporting, administrator review, AI-assisted task planning, and authority work through resolution. The graph combines the documented product workflow with source-indexed backend and frontend entry points. Several workflow and analytics capabilities are documented but their implementing code was not sampled, so those subsystem paths and links are limited to exact directories or documented relationships; the graph does not imply that unsampled internals were inspected.

Main entry points: [`backend/src/dao/authority.dao.ts`](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/dao/authority.dao.ts) (Authority data access), [`frontend/src/App.tsx`](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/App.tsx) (Web application), [`backend/src/app.ts`](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/app.ts) (API application), [`backend/src/dao/issue.dao.ts`](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/dao/issue.dao.ts) (Issue data access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_users["User experiences"]
end

subgraph group_frontend["Frontend application"]
  node_app["Web application<br/>[App.tsx]"]
  node_reporting["Issue reporting<br/>[Reports.tsx]"]
  node_admin_review_ui["Admin review<br/>[AdminReview.tsx]"]
  node_authority_tasks_ui["Authority tasks<br/>[AuthorityTasks.tsx]"]
  node_workflow_state["Workflow state<br/>[workflowSlice.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_city_features["City insights<br/>[MapPage.tsx]"]
  node_weather["Weather forecasts<br/>[WeatherPage.tsx]"]
  node_weather_service["Weather service<br/>[weatherService.ts]"]
  node_map_service["Map service<br/>[mapService.ts]"]
end

subgraph group_backend["Backend API"]
  node_issue_api["Issue endpoints<br/>[issue.routes.ts]"]
  node_admin_issue_api["Admin issue endpoints"]
  node_authority_issue_api["Authority issue endpoints"]
  node_auth["Authentication<br/>[auth.routes.ts]"]
  node_server_app["API application<br/>[app.ts]"]
  node_image_storage["ImageKit storage<br/>[image.service.ts]"]
end

subgraph group_domain["Issue and workforce workflow"]
  node_issue_review["Issue review"]
  node_issue_submission["Issue submission"]
  node_admin_planning["Admin task planning"]
  node_authority_management["Authority management"]
  node_authority_app_review["Authority applications"]
  node_ai_assignment["AI assignment support"]
end

subgraph group_foundation["Data and shared infrastructure"]
  node_db_config["Database configuration<br/>[db.ts]"]
  node_issue_data["Issue data access<br/>[issue.dao.ts]"]
  node_authority_data["Authority data access<br/>[authority.dao.ts]"]
  node_domain_models["Domain models<br/>[issue.model.ts]"]
  node_auth_middleware["Authentication middleware<br/>[auth.middleware.ts]"]
  node_validation["Request validation"]
  node_shared_types["Domain types<br/>[issue.types.ts]"]
  node_api_utilities["API utilities<br/>[api-response.ts]"]
end

node_citizens(("Citizens"))
node_administrators(("Administrators"))
node_authorities(("Authorities"))
node_imagekit["ImageKit"]

node_citizens -->|"use"| node_app
node_administrators -->|"use"| node_app
node_authorities -->|"use"| node_app
node_app -->|"routes to"| node_admin_review_ui
node_app -->|"routes to"| node_authority_tasks_ui
node_citizens -->|"submit reports"| node_reporting
node_administrators -->|"review issues"| node_admin_review_ui
node_authorities -->|"update work"| node_authority_tasks_ui
node_admin_review_ui -->|"dispatches"| node_workflow_state
node_authority_tasks_ui -->|"dispatches"| node_workflow_state
node_workflow_state -.->|"requests data"| node_api_client
node_reporting -.->|"requests data"| node_api_client
node_city_features -.->|"uses"| node_map_service
node_weather -.->|"loads forecasts"| node_weather_service
node_server_app -->|"mounts"| node_issue_api
node_server_app -->|"mounts"| node_admin_issue_api
node_server_app -->|"mounts"| node_authority_issue_api
node_server_app -->|"mounts"| node_auth
node_issue_submission -->|"reads and writes"| node_issue_data
node_issue_review -->|"reads and writes"| node_issue_data
node_admin_planning -.->|"uses workforce data"| node_authority_data
node_authority_app_review -->|"reads and writes"| node_authority_data
node_authority_management -->|"reads and writes"| node_authority_data
node_administrators -->|"review recommendations"| node_ai_assignment
node_issue_review -->|"verified issues enter planning"| node_admin_planning
node_admin_planning -->|"requests analysis"| node_ai_assignment
node_ai_assignment -->|"recommends assignment"| node_authorities
node_authorities -->|"complete assigned work"| node_issue_review
node_issue_submission -.->|"stores evidence"| node_image_storage
node_image_storage -.->|"uploads images"| node_imagekit
node_issue_data -->|"uses database"| node_db_config
node_authority_data -->|"uses database"| node_db_config
node_authority_data -->|"uses model"| node_domain_models
node_issue_data -->|"uses model"| node_domain_models
node_authority_issue_api -->|"requires authentication"| node_auth_middleware
node_authority_issue_api -->|"validates requests"| node_validation
node_issue_submission -->|"formats responses"| node_api_utilities
node_authority_app_review -->|"loads audit records"| node_authority_data

click node_app "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/App.tsx"
click node_reporting "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/Reports.tsx"
click node_admin_review_ui "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/AdminReview.tsx"
click node_authority_tasks_ui "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/AuthorityTasks.tsx"
click node_workflow_state "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/store/slices/workflowSlice.ts"
click node_api_client "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/services/api.ts"
click node_city_features "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/MapPage.tsx"
click node_weather "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/WeatherPage.tsx"
click node_issue_api "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/routes/issue.routes.ts"
click node_admin_issue_api "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/routes/admin-issue.routes.ts"
click node_authority_issue_api "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/routes/authority-issue.routes.ts"
click node_issue_review "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/authority-issue.service.ts"
click node_issue_submission "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/controller/issue.controller.ts"
click node_admin_planning "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/admin-issue.service.ts"
click node_authority_management "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/authority.service.ts"
click node_authority_app_review "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/admin-authority.service.ts"
click node_ai_assignment "https://github.com/anandrajjee981-max/urbanshield-ai/tree/main/backend/src/service"
click node_auth "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/routes/auth.routes.ts"
click node_server_app "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/app.ts"
click node_db_config "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/config/db.ts"
click node_issue_data "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/dao/issue.dao.ts"
click node_authority_data "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/dao/authority.dao.ts"
click node_domain_models "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/models/issue.model.ts"
click node_auth_middleware "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/middleware/auth.middleware.ts"
click node_validation "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/middleware/validate.middleware.ts"
click node_shared_types "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/types/issue.types.ts"
click node_api_utilities "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/utils/api-response.ts"
click node_weather_service "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/services/weatherService.ts"
click node_map_service "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/services/mapService.ts"
click node_image_storage "https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/image.service.ts"

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_reporting,node_admin_review_ui,node_authority_tasks_ui,node_workflow_state,node_api_client,node_city_features,node_weather,node_weather_service,node_map_service toneAmber
class node_issue_api,node_admin_issue_api,node_authority_issue_api,node_auth,node_server_app,node_image_storage toneMint
class node_issue_review,node_issue_submission,node_admin_planning,node_authority_management,node_authority_app_review,node_ai_assignment toneRose
class node_db_config,node_issue_data,node_authority_data,node_domain_models,node_auth_middleware,node_validation,node_shared_types,node_api_utilities,node_citizens,node_administrators,node_authorities,node_imagekit toneIndigo
```

## Components

### Frontend application

- [Web application](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Issue reporting](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/Reports.tsx): `frontend/src/pages/Reports.tsx`
- [Admin review](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/AdminReview.tsx): `frontend/src/pages/AdminReview.tsx`
- [Authority tasks](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/AuthorityTasks.tsx): `frontend/src/pages/AuthorityTasks.tsx`
- [Workflow state](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/store/slices/workflowSlice.ts): `frontend/src/store/slices/workflowSlice.ts`
- [API client](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [City insights](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/MapPage.tsx): `frontend/src/pages/MapPage.tsx`
- [Weather forecasts](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/pages/WeatherPage.tsx): `frontend/src/pages/WeatherPage.tsx`
- [Weather service](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/services/weatherService.ts): `frontend/src/services/weatherService.ts`
- [Map service](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/frontend/src/services/mapService.ts): `frontend/src/services/mapService.ts`

### Backend API

- [Issue endpoints](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/routes/issue.routes.ts): `backend/src/routes/issue.routes.ts`
- [Admin issue endpoints](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/routes/admin-issue.routes.ts): `backend/src/routes/admin-issue.routes.ts`
- [Authority issue endpoints](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/routes/authority-issue.routes.ts): `backend/src/routes/authority-issue.routes.ts`
- [Authentication](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/routes/auth.routes.ts): `backend/src/routes/auth.routes.ts`
- [API application](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [ImageKit storage](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/image.service.ts): `backend/src/service/image.service.ts`

### Issue and workforce workflow

- [Issue review](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/authority-issue.service.ts): `backend/src/service/authority-issue.service.ts`
- [Issue submission](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/controller/issue.controller.ts): `backend/src/controller/issue.controller.ts`
- [Admin task planning](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/admin-issue.service.ts): `backend/src/service/admin-issue.service.ts`
- [Authority management](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/authority.service.ts): `backend/src/service/authority.service.ts`
- [Authority applications](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/service/admin-authority.service.ts): `backend/src/service/admin-authority.service.ts`
- [AI assignment support](https://github.com/anandrajjee981-max/urbanshield-ai/tree/main/backend/src/service): `backend/src/service`

### Data and shared infrastructure

- [Database configuration](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/config/db.ts): `backend/src/config/db.ts`
- [Issue data access](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/dao/issue.dao.ts): `backend/src/dao/issue.dao.ts`
- [Authority data access](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/dao/authority.dao.ts): `backend/src/dao/authority.dao.ts`
- [Domain models](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/models/issue.model.ts): `backend/src/models/issue.model.ts`
- [Authentication middleware](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/middleware/auth.middleware.ts): `backend/src/middleware/auth.middleware.ts`
- [Request validation](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/middleware/validate.middleware.ts): `backend/src/middleware/validate.middleware.ts`
- [Domain types](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/types/issue.types.ts): `backend/src/types/issue.types.ts`
- [API utilities](https://github.com/anandrajjee981-max/urbanshield-ai/blob/main/backend/src/utils/api-response.ts): `backend/src/utils/api-response.ts`

### Other components

- **Citizens**
- **Administrators**
- **Authorities**
- **ImageKit**

## Connections

- Citizens → Web application: use
- Administrators → Web application: use
- Authorities → Web application: use
- Web application → Admin review: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Authority tasks: routes to (evidence: `frontend/src/App.tsx`)
- Citizens → Issue reporting: submit reports
- Administrators → Admin review: review issues
- Authorities → Authority tasks: update work
- Admin review → Workflow state: dispatches (evidence: `frontend/src/pages/AdminReview.tsx`)
- Authority tasks → Workflow state: dispatches (evidence: `frontend/src/pages/AuthorityTasks.tsx`)
- Workflow state → API client: requests data
- Issue reporting → API client: requests data
- City insights → Map service: uses
- Weather forecasts → Weather service: loads forecasts
- API application → Issue endpoints: mounts (evidence: `backend/src/app.ts`)
- API application → Admin issue endpoints: mounts (evidence: `backend/src/app.ts`)
- API application → Authority issue endpoints: mounts (evidence: `backend/src/app.ts`)
- API application → Authentication: mounts (evidence: `backend/src/app.ts`)
- Issue submission → Issue data access: reads and writes (evidence: `backend/src/controller/issue.controller.ts`)
- Issue review → Issue data access: reads and writes (evidence: `backend/src/service/authority-issue.service.ts`)
- Admin task planning → Authority data access: uses workforce data
- Authority applications → Authority data access: reads and writes (evidence: `backend/src/service/admin-authority.service.ts`)
- Authority management → Authority data access: reads and writes (evidence: `backend/src/service/authority.service.ts`)
- Administrators → AI assignment support: review recommendations
- Issue review → Admin task planning: verified issues enter planning
- Admin task planning → AI assignment support: requests analysis
- AI assignment support → Authorities: recommends assignment
- Authorities → Issue review: complete assigned work
- Issue submission → ImageKit storage: stores evidence
- ImageKit storage → ImageKit: uploads images
- Issue data access → Database configuration: uses database (evidence: `backend/src/dao/issue.dao.ts`)
- Authority data access → Database configuration: uses database (evidence: `backend/src/dao/authority.dao.ts`)
- Authority data access → Domain models: uses model (evidence: `backend/src/dao/authority.dao.ts`)
- Issue data access → Domain models: uses model (evidence: `backend/src/dao/issue.dao.ts`)
- Authority issue endpoints → Authentication middleware: requires authentication (evidence: `backend/src/routes/authority-issue.routes.ts`)
- Authority issue endpoints → Request validation: validates requests (evidence: `backend/src/routes/authority-issue.routes.ts`)
- Issue submission → API utilities: formats responses (evidence: `backend/src/controller/issue.controller.ts`)
- Authority applications → Authority data access: loads audit records (evidence: `backend/src/service/admin-authority.service.ts`)
