# zephyrus2822/sih2025 architecture

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

- Interactive diagram: https://gitdiagram.com/zephyrus2822/sih2025
- Repository: https://github.com/zephyrus2822/sih2025

## Overview

#### Purpose and Entry Points
This is a railway operations platform with role-specific web dashboards, passenger services, predictive maintenance/ML, complaints, chatbot support, and automated engineer job assignment. It consists of a Next.js frontend and Python backend. Main entry points are `src/app/page.tsx`, `src/app/layout.tsx`, and `src/backend/main.py`.

#### Frontend Application Shell and Localization
The frontend uses the Next.js App Router. Global layout and styling originate at `src/app/layout.tsx` and `src/app/globals.css`. Locale-scoped pages use `src/app/[locale]/layout.tsx` and `src/app/[locale]/page.tsx`, backed by translation assets in `public/locales/en/common.json` and `public/locales/hi/common.json`. Shared i18n setup is in `src/components/I18nProvider.tsx` and `src/lib/i18n.ts`.

#### Role-Oriented Operational Portals
Separate route groups expose tailored interfaces for employees, engineers, locomotive pilots, maintainers, and passengers. Each dashboard generally has a server route page that mounts a client-side interaction component:
- Engineer work management: `src/app/engineer_dashboard/page.tsx`, `src/app/engineer_dashboard/EngineerDashboardClient.tsx`
- Employee job view: `src/app/employee_dashboard/page.tsx`, `src/app/employee_dashboard/EmployeeJobsClient.tsx`
- Loco-pilot and maintainer views: `src/app/locopilot_dashboard/LocoPilotDashboardClient.tsx`, `src/app/maintainer_dashboard/MaintainerDashboardClient.tsx`
- Passenger-facing services: `src/app/passenger_dashboard/page.tsx`, `src/app/passenger_dashboard/complaints/page.tsx`, `src/app/passenger_dashboard/schedule/page.tsx`

#### Backend API Boundary
The Python service is organized by domain routers registered from `src/backend/main.py`. Domain APIs isolate authentication, chat, complaints, personnel workflows, contact/footer data, and pilot workflows:
- `src/backend/auth/routes.py`
- `src/backend/chatbot/routes.py`
- `src/backend/complaints/routes.py`
- `src/backend/engineer/routes.py`
- `src/backend/locopilot/routes.py`

The frontend’s client components are the primary consumer boundary for these APIs; API implementation, persistence, and business rules remain under `src/backend`.

#### Persistence and Validation
Relational database connectivity and ORM-style data models are centralized in `src/backend/db/database_connection.py` and `src/backend/db/database_models.py`. The validation domain has its own data-access, models, schemas, routes, and service layer, separating request contracts from validation business logic: `src/backend/validation/routes.py`, `src/backend/validation/service.py`, and `src/backend/validation/db.py`. SQL bootstrap/snapshot assets are provided by `backup.sql` and `backup_clean.sql`.

#### Predictive Model Pipeline
The deep-learning subsystem serves model-driven predictions through `src/backend/dl_model/routes.py`. It contains request/database schemas, model persistence, data import, training, metrics, and reporting stages:
- Model artifacts/implementation: `src/backend/dl_model/model.h5`, `src/backend/dl_model/model/model.py`
- Training and evaluation: `src/backend/dl_model/services/training_service.py`, `src/backend/dl_model/services/metrics.py`
- Dataset ingestion/reporting: `src/backend/dl_model/scripts/import_csv.py`, `src/backend/dl_model/services/report_service.py`

Its UI is mounted at `src/app/predictor/page.tsx` and `src/app/predictor/PredictorClient.tsx`.

#### Asynchronous Job Distribution
Engineer-job allocation is a distinct asynchronous subsystem. API requests enter through `src/backend/job_distributor/api.py`; assignment decisions are implemented in `src/backend/job_distributor/assigner.py`; work is dispatched and executed through Celery configuration/tasks in `src/backend/job_distributor/celery_app.py` and `src/backend/job_distributor/tasks.py`. Worker deployment is represented by `src/backend/job_distributor/worker_entrypoint.sh`. This boundary prevents allocation work from blocking normal API requests.

#### Runtime, Deployment, and Observability
The frontend runs in the Node/Next.js ecosystem (`package.json`, `next.config.ts`). The backend is containerized with `src/backend/Dockerfile` and Python dependencies in `src/backend/requirements.txt`; compose definitions exist at `docker-compose.yml` and `src/backend/backend-docker-compose.yml`. Monitoring infrastructure uses Prometheus and Grafana assets in `observibility/prometheus.yml`, `observibility/docker-compose.yml`, and `observibility/grafana_dashboard.json`. The frontend includes a Grafana embedding component at `src/components/ui/grafanaembed.tsx`.

Main entry points: [`src/backend/main.py`](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/main.py) (Backend API app), [`src/app/layout.tsx`](https://github.com/zephyrus2822/sih2025/blob/main/src/app/layout.tsx) (App shell & locales), [`src/backend/db/database_connection.py`](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/db/database_connection.py) (Relational database), [`src/backend/dl_model/routes.py`](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/dl_model/routes.py) (Prediction API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js Frontend"]
  node_app_shell["App shell &amp; locales<br/>Next.js App Router<br/>[layout.tsx]"]
  node_i18n["i18n provider<br/>localization<br/>[I18nProvider.tsx]"]
  node_staff_portals["Staff portals<br/>dashboard routes"]
  node_passenger_portal["Passenger services<br/>dashboard routes<br/>[page.tsx]"]
  node_predictor_ui["Predictor UI<br/>client dashboard"]
  node_grafana_embed["Grafana embed<br/>monitoring UI<br/>[grafanaembed.tsx]"]
end

subgraph group_backend["Python API"]
  node_api_app["Backend API app<br/>Python service<br/>[main.py]"]
  node_domain_routers["Domain routers<br/>API routes<br/>[routes.py]"]
  node_validation["Validation service<br/>service layer<br/>[service.py]"]
  node_database[("Relational database<br/>ORM persistence")]
end

subgraph group_ml["Predictive Maintenance"]
  node_ml_api["Prediction API<br/>ML routes<br/>[routes.py]"]
  node_ml_model["Trained model<br/>model artifact<br/>[model.py]"]
  node_ml_training["Training &amp; metrics<br/>ML services"]
  node_ml_data["Dataset import &amp; reports<br/>ML data pipeline<br/>[import_csv.py]"]
end

subgraph group_jobs["Async Job Distribution"]
  node_job_api["Job allocation API<br/>async API<br/>[api.py]"]
  node_assigner["Assignment engine<br/>allocation logic<br/>[assigner.py]"]
  node_celery_tasks["Celery tasks<br/>task queue worker<br/>[tasks.py]"]
  node_worker["Worker deployment<br/>worker entrypoint"]
end

subgraph group_ops["Runtime &amp; Observability"]
  node_containers["Container deployment<br/>Docker Compose<br/>[docker-compose.yml]"]
  node_monitoring["Prometheus &amp; Grafana<br/>observability stack<br/>[docker-compose.yml]"]
end

node_app_shell -->|"provides locale context"| node_i18n
node_app_shell -->|"routes to"| node_staff_portals
node_app_shell -->|"routes to"| node_passenger_portal
node_app_shell -->|"routes to"| node_predictor_ui
node_staff_portals -->|"calls APIs"| node_api_app
node_passenger_portal -->|"calls APIs"| node_api_app
node_predictor_ui -->|"requests predictions"| node_ml_api
node_api_app -->|"registers"| node_domain_routers
node_api_app -->|"routes validation"| node_validation
node_api_app -->|"exposes allocation"| node_job_api
node_domain_routers -->|"persists domain data"| node_database
node_validation -->|"reads and writes"| node_database
node_ml_api -->|"uses"| node_ml_model
node_ml_api -->|"uses schemas and data"| node_database
node_ml_data -->|"supplies datasets"| node_ml_training
node_ml_training -->|"produces artifact"| node_ml_model
node_ml_training -->|"reports results"| node_ml_data
node_job_api -->|"submits allocation"| node_assigner
node_assigner -->|"dispatches"| node_celery_tasks
node_worker -->|"executes"| node_celery_tasks
node_celery_tasks -->|"updates assignments"| node_database
node_containers -->|"deploys"| node_api_app
node_containers -->|"runs stack"| node_monitoring
node_monitoring -->|"visualized in"| node_grafana_embed

click node_app_shell "https://github.com/zephyrus2822/sih2025/blob/main/src/app/layout.tsx"
click node_i18n "https://github.com/zephyrus2822/sih2025/blob/main/src/components/I18nProvider.tsx"
click node_staff_portals "https://github.com/zephyrus2822/sih2025/blob/main/src/app/engineer_dashboard/EngineerDashboardClient.tsx"
click node_passenger_portal "https://github.com/zephyrus2822/sih2025/blob/main/src/app/passenger_dashboard/page.tsx"
click node_predictor_ui "https://github.com/zephyrus2822/sih2025/blob/main/src/app/predictor/PredictorClient.tsx"
click node_grafana_embed "https://github.com/zephyrus2822/sih2025/blob/main/src/components/ui/grafanaembed.tsx"
click node_api_app "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/main.py"
click node_domain_routers "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/engineer/routes.py"
click node_validation "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/validation/service.py"
click node_database "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/db/database_connection.py"
click node_ml_api "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/dl_model/routes.py"
click node_ml_model "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/dl_model/model/model.py"
click node_ml_training "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/dl_model/services/training_service.py"
click node_ml_data "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/dl_model/scripts/import_csv.py"
click node_job_api "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/job_distributor/api.py"
click node_assigner "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/job_distributor/assigner.py"
click node_celery_tasks "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/job_distributor/tasks.py"
click node_worker "https://github.com/zephyrus2822/sih2025/blob/main/src/backend/job_distributor/worker_entrypoint.sh"
click node_containers "https://github.com/zephyrus2822/sih2025/blob/main/docker-compose.yml"
click node_monitoring "https://github.com/zephyrus2822/sih2025/blob/main/observibility/docker-compose.yml"

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_shell,node_i18n,node_staff_portals,node_passenger_portal,node_predictor_ui,node_grafana_embed toneBlue
class node_api_app,node_domain_routers,node_validation,node_database toneAmber
class node_ml_api,node_ml_model,node_ml_training,node_ml_data toneMint
class node_job_api,node_assigner,node_celery_tasks,node_worker toneRose
class node_containers,node_monitoring toneIndigo
```

## Components

### Next.js Frontend

- [App shell & locales](https://github.com/zephyrus2822/sih2025/blob/main/src/app/layout.tsx): Next.js App Router · Global and locale layouts provide localized application entry. · `src/app/layout.tsx`
- [i18n provider](https://github.com/zephyrus2822/sih2025/blob/main/src/components/I18nProvider.tsx): localization · Translation setup serves English and Hindi assets. · `src/components/I18nProvider.tsx`
- [Staff portals](https://github.com/zephyrus2822/sih2025/blob/main/src/app/engineer_dashboard/EngineerDashboardClient.tsx): dashboard routes · Engineer, employee, loco-pilot, and maintainer operational views. · `src/app/engineer_dashboard/EngineerDashboardClient.tsx`
- [Passenger services](https://github.com/zephyrus2822/sih2025/blob/main/src/app/passenger_dashboard/page.tsx): dashboard routes · Passenger dashboard, complaints, and schedule services. · `src/app/passenger_dashboard/page.tsx`
- [Predictor UI](https://github.com/zephyrus2822/sih2025/blob/main/src/app/predictor/PredictorClient.tsx): client dashboard · `src/app/predictor/PredictorClient.tsx`
- [Grafana embed](https://github.com/zephyrus2822/sih2025/blob/main/src/components/ui/grafanaembed.tsx): monitoring UI · `src/components/ui/grafanaembed.tsx`

### Python API

- [Backend API app](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/main.py): Python service · Registers domain routers and serves the frontend boundary. · `src/backend/main.py`
- [Domain routers](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/engineer/routes.py): API routes · Auth, chat, complaints, engineer, and loco-pilot endpoints. · `src/backend/engineer/routes.py`
- [Validation service](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/validation/service.py): service layer · Separates validation contracts, data access, and business logic. · `src/backend/validation/service.py`
- [Relational database](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/db/database_connection.py): ORM persistence · Shared connectivity and data models for backend domains. · `src/backend/db/database_connection.py`

### Predictive Maintenance

- [Prediction API](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/dl_model/routes.py): ML routes · `src/backend/dl_model/routes.py`
- [Trained model](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/dl_model/model/model.py): model artifact · Deep-learning model used for prediction serving. · `src/backend/dl_model/model/model.py`
- [Training & metrics](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/dl_model/services/training_service.py): ML services · Trains and evaluates predictive models. · `src/backend/dl_model/services/training_service.py`
- [Dataset import & reports](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/dl_model/scripts/import_csv.py): ML data pipeline · Imports datasets and produces model reports. · `src/backend/dl_model/scripts/import_csv.py`

### Async Job Distribution

- [Job allocation API](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/job_distributor/api.py): async API · Accepts engineer allocation requests without blocking APIs. · `src/backend/job_distributor/api.py`
- [Assignment engine](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/job_distributor/assigner.py): allocation logic · `src/backend/job_distributor/assigner.py`
- [Celery tasks](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/job_distributor/tasks.py): task queue worker · Dispatches and executes allocation work. · `src/backend/job_distributor/tasks.py`
- [Worker deployment](https://github.com/zephyrus2822/sih2025/blob/main/src/backend/job_distributor/worker_entrypoint.sh): worker entrypoint · `src/backend/job_distributor/worker_entrypoint.sh`

### Runtime & Observability

- [Container deployment](https://github.com/zephyrus2822/sih2025/blob/main/docker-compose.yml): Docker Compose · Runs frontend and backend service environments. · `docker-compose.yml`
- [Prometheus & Grafana](https://github.com/zephyrus2822/sih2025/blob/main/observibility/docker-compose.yml): observability stack · Collects and visualizes runtime monitoring data. · `observibility/docker-compose.yml`

## Connections

- App shell & locales → i18n provider: provides locale context
- App shell & locales → Staff portals: routes to
- App shell & locales → Passenger services: routes to
- App shell & locales → Predictor UI: routes to
- Staff portals → Backend API app: calls APIs
- Passenger services → Backend API app: calls APIs
- Predictor UI → Prediction API: requests predictions
- Backend API app → Domain routers: registers
- Backend API app → Validation service: routes validation
- Backend API app → Job allocation API: exposes allocation
- Domain routers → Relational database: persists domain data
- Validation service → Relational database: reads and writes
- Prediction API → Trained model: uses
- Prediction API → Relational database: uses schemas and data
- Dataset import & reports → Training & metrics: supplies datasets
- Training & metrics → Trained model: produces artifact
- Training & metrics → Dataset import & reports: reports results
- Job allocation API → Assignment engine: submits allocation
- Assignment engine → Celery tasks: dispatches
- Worker deployment → Celery tasks: executes
- Celery tasks → Relational database: updates assignments
- Container deployment → Backend API app: deploys
- Container deployment → Prometheus & Grafana: runs stack
- Prometheus & Grafana → Grafana embed: visualized in