# koppakaranjeethguptha0307-lab/neuroute architecture

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

- Interactive diagram: https://gitdiagram.com/koppakaranjeethguptha0307-lab/neuroute
- Repository: https://github.com/koppakaranjeethguptha0307-lab/neuroute

## Overview

NEURoute is a software-only logistics and accessibility platform for disruption-aware operations in Northeast India. Operators use its web interface and APIs to monitor corridors, report incidents, track shipments and vehicles, and plan safer routes; the documented operational flow combines weather, hazards, incidents, risk and delay estimates, rerouting, alerts, and live map updates. The backend also supports authentication, GIS, analytics, simulation, and offline field-report synchronization. Several route and API subsystems are represented by their existing directories because their implementations were not sampled.

Main entry points: [`backend/app/services/simulation_service.py`](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/simulation_service.py) (Scenario Simulation), [`backend/app/repositories`](https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/repositories) (Persistence Repositories), [`backend/app/services/route_orchestrator.py`](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/route_orchestrator.py) (Route Orchestrator), [`backend/app/services/incident_service.py`](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/incident_service.py) (Incident Handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Operator Web App"]
  node_webapp["Web Application<br/>[App.tsx]"]
  node_pages["Operations Screens"]
  node_offline["Offline Report Queue<br/>[offlineQueue.ts]"]
end

subgraph group_api["Backend API"]
  node_backend["FastAPI Application<br/>[main.py]"]
  node_api_routes["Domain API Routes"]
  node_route_api["Route Planning API<br/>[routes.py]"]
end

subgraph group_ops["Operational Services"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_incident["Incident Handling"]
  node_shipment["Shipment Lifecycle"]
  node_simulation["Scenario Simulation"]
  node_events["Live Event Broadcast"]
  node_gis["GIS Services<br/>[gis_service.py]"]
  node_orchestrator["Route Orchestrator"]
end

subgraph group_intelligence["Risk And Routing"]
  node_risk["Risk Prediction<br/>[risk_predictor.py]"]
  node_delay["Delay Estimation<br/>[delay_estimator.py]"]
  node_optimizer["Route Optimization<br/>[route_optimizer.py]"]
  node_classifier["Incident Classification<br/>[classifier.py]"]
end

subgraph group_data["Adapters And Storage"]
  node_telemetry["Software Telemetry"]
  node_routing["Routing Providers"]
  node_weather["Weather Providers"]
  node_db[("Relational Database<br/>[session.py]")]
  node_repositories["Persistence Repositories"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_pages
node_operator -->|"queues field reports"| node_offline
node_backend -->|"registers routes"| node_api_routes
node_api_routes -.->|"authenticates users"| node_auth
node_route_api -->|"plans routes"| node_orchestrator
node_simulation -->|"calculates risk"| node_risk
node_simulation -->|"estimates delay"| node_delay
node_simulation -->|"selects routes"| node_optimizer
node_simulation -->|"reads telemetry"| node_telemetry
node_simulation -->|"broadcasts updates"| node_events
node_incident -.->|"alerts operators"| node_events
node_incident -->|"persists incidents"| node_repositories
node_shipment -->|"persists shipments"| node_repositories
node_auth -->|"reads and writes users"| node_repositories
node_repositories -->|"accesses"| node_db
node_orchestrator -.->|"optimizes alternatives"| node_optimizer
node_orchestrator -.->|"requests geometry"| node_routing
node_weather -.->|"provides provenance badges"| node_operator
node_pages -.->|"displays live updates"| node_events
node_classifier -.->|"classifies reports"| node_incident

click node_webapp "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/frontend/src/App.tsx"
click node_pages "https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/frontend/src/pages"
click node_offline "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/frontend/src/utils/offlineQueue.ts"
click node_backend "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/main.py"
click node_api_routes "https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/api/routes"
click node_auth "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/auth_service.py"
click node_incident "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/incident_service.py"
click node_shipment "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/shipment_service.py"
click node_simulation "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/simulation_service.py"
click node_events "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/event_broadcaster.py"
click node_gis "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/gis_service.py"
click node_risk "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/ai/services/risk_predictor.py"
click node_delay "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/ai/services/delay_estimator.py"
click node_optimizer "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/ai/services/route_optimizer.py"
click node_classifier "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/ai/services/classifier.py"
click node_route_api "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/api/routes/routes.py"
click node_orchestrator "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/route_orchestrator.py"
click node_telemetry "https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/adapters"
click node_routing "https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/adapters/routing"
click node_weather "https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/adapters/weather"
click node_db "https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/database/session.py"
click node_repositories "https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/repositories"

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_webapp,node_pages,node_offline toneBlue
class node_backend,node_api_routes,node_route_api toneAmber
class node_auth,node_incident,node_shipment,node_simulation,node_events,node_gis,node_orchestrator toneMint
class node_risk,node_delay,node_optimizer,node_classifier toneRose
class node_telemetry,node_routing,node_weather,node_db,node_repositories,node_operator toneIndigo
```

## Components

### Operator Web App

- [Web Application](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Operations Screens](https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/frontend/src/pages): `frontend/src/pages`
- [Offline Report Queue](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/frontend/src/utils/offlineQueue.ts): `frontend/src/utils/offlineQueue.ts`

### Backend API

- [FastAPI Application](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/main.py): `backend/app/main.py`
- [Domain API Routes](https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/api/routes): `backend/app/api/routes`
- [Route Planning API](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/api/routes/routes.py): `backend/app/api/routes/routes.py`

### Operational Services

- [Authentication](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Incident Handling](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/incident_service.py): `backend/app/services/incident_service.py`
- [Shipment Lifecycle](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/shipment_service.py): `backend/app/services/shipment_service.py`
- [Scenario Simulation](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/simulation_service.py): `backend/app/services/simulation_service.py`
- [Live Event Broadcast](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/event_broadcaster.py): `backend/app/services/event_broadcaster.py`
- [GIS Services](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/gis_service.py): `backend/app/services/gis_service.py`
- [Route Orchestrator](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/services/route_orchestrator.py): `backend/app/services/route_orchestrator.py`

### Risk And Routing

- [Risk Prediction](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/ai/services/risk_predictor.py): `ai/services/risk_predictor.py`
- [Delay Estimation](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/ai/services/delay_estimator.py): `ai/services/delay_estimator.py`
- [Route Optimization](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/ai/services/route_optimizer.py): `ai/services/route_optimizer.py`
- [Incident Classification](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/ai/services/classifier.py): `ai/services/classifier.py`

### Adapters And Storage

- [Software Telemetry](https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/adapters): `backend/app/adapters`
- [Routing Providers](https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/adapters/routing): `backend/app/adapters/routing`
- [Weather Providers](https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/adapters/weather): `backend/app/adapters/weather`
- [Relational Database](https://github.com/koppakaranjeethguptha0307-lab/neuroute/blob/Rasagna-integration/backend/app/database/session.py): `backend/app/database/session.py`
- [Persistence Repositories](https://github.com/koppakaranjeethguptha0307-lab/neuroute/tree/Rasagna-integration/backend/app/repositories): `backend/app/repositories`

### Other components

- **Operator**

## Connections

- Operator → Web Application: uses
- Web Application → Operations Screens: routes to (evidence: `frontend/src/App.tsx`)
- Operator → Offline Report Queue: queues field reports
- FastAPI Application → Domain API Routes: registers routes (evidence: `backend/app/main.py`)
- Domain API Routes → Authentication: authenticates users (evidence: `backend/app/api/routes/auth.py`)
- Route Planning API → Route Orchestrator: plans routes (evidence: `backend/app/api/routes/routes.py`)
- Scenario Simulation → Risk Prediction: calculates risk (evidence: `backend/app/services/simulation_service.py`)
- Scenario Simulation → Delay Estimation: estimates delay (evidence: `backend/app/services/simulation_service.py`)
- Scenario Simulation → Route Optimization: selects routes (evidence: `backend/app/services/simulation_service.py`)
- Scenario Simulation → Software Telemetry: reads telemetry (evidence: `backend/app/services/simulation_service.py`)
- Scenario Simulation → Live Event Broadcast: broadcasts updates (evidence: `backend/app/services/simulation_service.py`)
- Incident Handling → Live Event Broadcast: alerts operators
- Incident Handling → Persistence Repositories: persists incidents (evidence: `backend/app/services/incident_service.py`)
- Shipment Lifecycle → Persistence Repositories: persists shipments (evidence: `backend/app/services/shipment_service.py`)
- Authentication → Persistence Repositories: reads and writes users (evidence: `backend/app/services/auth_service.py`)
- Persistence Repositories → Relational Database: accesses (evidence: `backend/app/repositories/base.py`)
- Route Orchestrator → Route Optimization: optimizes alternatives
- Route Orchestrator → Routing Providers: requests geometry
- Weather Providers → Operator: provides provenance badges
- Operations Screens → Live Event Broadcast: displays live updates
- Incident Classification → Incident Handling: classifies reports
