# phanikatikala-cmd/minerva architecture

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

- Interactive diagram: https://gitdiagram.com/phanikatikala-cmd/minerva
- Repository: https://github.com/phanikatikala-cmd/minerva

## Overview

MINERVA is a mining-safety application for assessing zone hazards, tracking workers, and issuing targeted evacuation alerts. The principal workflow is telemetry assessment, risk inference and zone-state evaluation, then alert dispatch to affected on-duty workers; workers can view and acknowledge alerts or send SOS, while administrators manage mines, zones, workers, simulations, and analytics. The graph includes the documented inference and alert behavior, plus the frontend/API entry points. Several backend endpoint-to-service links and unsampled feature implementations are not shown because their wiring cannot be verified from the excerpts.

Main entry points: [`backend/app/db/session.py`](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/db/session.py) (Application database), [`frontend/src/app/routes.tsx`](https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/app/routes.tsx) (Role routes), [`backend/app/services/zone_risk_engine.py`](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/zone_risk_engine.py) (Zone risk engine), [`backend/app/services/emergency_alert_engine.py`](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/emergency_alert_engine.py) (Emergency alerts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Web app<br/>[App.tsx]"]
  node_routes["Role routes<br/>[routes.tsx]"]
  node_adminpages["Admin pages"]
  node_workerpages["Worker pages"]
  node_workerhooks["Worker queries<br/>[useWorkers.ts]"]
  node_dashboardhook["Safety dashboard"]
  node_apiclient["HTTP client<br/>[apiClient.ts]"]
end

subgraph group_api["API and operations"]
  node_server["FastAPI app<br/>[main.py]"]
  node_endpoints["API endpoints"]
end

subgraph group_safety["Hazard response"]
  node_inference["Hazard inference"]
  node_risk["Zone risk engine"]
  node_alerts["Emergency alerts"]
end

subgraph group_domain["Mine operations"]
  node_workersvc["Worker services<br/>[worker_service.py]"]
  node_zonesvc["Zone services<br/>[zone_service.py]"]
  node_minesvc["Mine services<br/>[mine_service.py]"]
  node_simulation["Simulation"]
  node_analytics["Analytics<br/>[analytics.py]"]
  node_store[("Application database<br/>[session.py]")]
end

subgraph group_ml["Modeling"]
  node_classical["Classical training"]
  node_deep["Deep learning"]
end

node_admin(("Administrator"))
node_worker(("Field worker"))
node_telemetry(("Mine telemetry"))

node_admin -->|"uses"| node_app
node_worker -->|"uses"| node_app
node_app -->|"renders"| node_routes
node_routes -->|"routes admins"| node_adminpages
node_routes -->|"routes workers"| node_workerpages
node_adminpages -->|"manages workers"| node_workerhooks
node_workerpages -->|"loads safety view"| node_dashboardhook
node_workerhooks -->|"requests worker data"| node_apiclient
node_dashboardhook -->|"requests dashboard"| node_apiclient
node_apiclient -->|"HTTP requests"| node_server
node_server -->|"mounts router"| node_endpoints
node_telemetry -->|"submits readings"| node_endpoints
node_endpoints -->|"requests prediction"| node_inference
node_inference -->|"assesses risk"| node_risk
node_risk -->|"dispatches hazard alerts"| node_alerts
node_alerts -->|"alerts and routes"| node_worker
node_worker -->|"views and acknowledges"| node_dashboardhook
node_risk -->|"persists assessment"| node_store
node_alerts -->|"stores alerts"| node_store
node_workersvc -->|"reads and writes"| node_store
node_zonesvc -->|"reads and writes"| node_store
node_minesvc -->|"reads and writes"| node_store
node_simulation -.->|"simulates prediction"| node_inference
node_analytics -->|"queries operational data"| node_store
node_classical -.->|"alternative training"| node_deep

click node_app "https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/App.tsx"
click node_routes "https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/app/routes.tsx"
click node_adminpages "https://github.com/phanikatikala-cmd/minerva/tree/main/frontend/src/pages"
click node_workerpages "https://github.com/phanikatikala-cmd/minerva/tree/main/frontend/src/pages"
click node_workerhooks "https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/features/workers/hooks/useWorkers.ts"
click node_dashboardhook "https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/features/workers/hooks/useWorkerDashboard.ts"
click node_apiclient "https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/services/apiClient.ts"
click node_server "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/main.py"
click node_endpoints "https://github.com/phanikatikala-cmd/minerva/tree/main/backend/app/api/v1/endpoints"
click node_inference "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/inference_service.py"
click node_risk "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/zone_risk_engine.py"
click node_alerts "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/emergency_alert_engine.py"
click node_workersvc "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/worker_service.py"
click node_zonesvc "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/zone_service.py"
click node_minesvc "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/mine_service.py"
click node_simulation "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/simulation_service.py"
click node_analytics "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/api/v1/endpoints/analytics.py"
click node_store "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/db/session.py"
click node_classical "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/ml/classical_pipeline.py"
click node_deep "https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/ml/deep_learning_pipeline.py"

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_routes,node_adminpages,node_workerpages,node_workerhooks,node_dashboardhook,node_apiclient toneBlue
class node_server,node_endpoints toneAmber
class node_inference,node_risk,node_alerts toneMint
class node_workersvc,node_zonesvc,node_minesvc,node_simulation,node_analytics,node_store,node_worker toneRose
class node_classical,node_deep,node_admin,node_telemetry toneIndigo
```

## Components

### Web application

- [Web app](https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Role routes](https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/app/routes.tsx): `frontend/src/app/routes.tsx`
- [Admin pages](https://github.com/phanikatikala-cmd/minerva/tree/main/frontend/src/pages): `frontend/src/pages`
- [Worker pages](https://github.com/phanikatikala-cmd/minerva/tree/main/frontend/src/pages): `frontend/src/pages`
- [Worker queries](https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/features/workers/hooks/useWorkers.ts): `frontend/src/features/workers/hooks/useWorkers.ts`
- [Safety dashboard](https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/features/workers/hooks/useWorkerDashboard.ts): `frontend/src/features/workers/hooks/useWorkerDashboard.ts`
- [HTTP client](https://github.com/phanikatikala-cmd/minerva/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`

### API and operations

- [FastAPI app](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/main.py): `backend/app/main.py`
- [API endpoints](https://github.com/phanikatikala-cmd/minerva/tree/main/backend/app/api/v1/endpoints): `backend/app/api/v1/endpoints`

### Hazard response

- [Hazard inference](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/inference_service.py): `backend/app/services/inference_service.py`
- [Zone risk engine](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/zone_risk_engine.py): `backend/app/services/zone_risk_engine.py`
- [Emergency alerts](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/emergency_alert_engine.py): `backend/app/services/emergency_alert_engine.py`

### Mine operations

- [Worker services](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/worker_service.py): `backend/app/services/worker_service.py`
- [Zone services](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/zone_service.py): `backend/app/services/zone_service.py`
- [Mine services](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/mine_service.py): `backend/app/services/mine_service.py`
- [Simulation](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/services/simulation_service.py): `backend/app/services/simulation_service.py`
- [Analytics](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/api/v1/endpoints/analytics.py): `backend/app/api/v1/endpoints/analytics.py`
- [Application database](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/db/session.py): `backend/app/db/session.py`

### Modeling

- [Classical training](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/ml/classical_pipeline.py): `backend/app/ml/classical_pipeline.py`
- [Deep learning](https://github.com/phanikatikala-cmd/minerva/blob/main/backend/app/ml/deep_learning_pipeline.py): `backend/app/ml/deep_learning_pipeline.py`

### Other components

- **Administrator**
- **Field worker**
- **Mine telemetry**

## Connections

- Administrator → Web app: uses
- Field worker → Web app: uses
- Web app → Role routes: renders
- Role routes → Admin pages: routes admins
- Role routes → Worker pages: routes workers
- Admin pages → Worker queries: manages workers
- Worker pages → Safety dashboard: loads safety view
- Worker queries → HTTP client: requests worker data
- Safety dashboard → HTTP client: requests dashboard
- HTTP client → FastAPI app: HTTP requests
- FastAPI app → API endpoints: mounts router
- Mine telemetry → API endpoints: submits readings
- API endpoints → Hazard inference: requests prediction
- Hazard inference → Zone risk engine: assesses risk
- Zone risk engine → Emergency alerts: dispatches hazard alerts
- Emergency alerts → Field worker: alerts and routes
- Field worker → Safety dashboard: views and acknowledges
- Zone risk engine → Application database: persists assessment
- Emergency alerts → Application database: stores alerts
- Worker services → Application database: reads and writes
- Zone services → Application database: reads and writes
- Mine services → Application database: reads and writes
- Simulation → Hazard inference: simulates prediction
- Analytics → Application database: queries operational data
- Classical training → Deep learning: alternative training