# vanshcloud/predictive-maintenance-genai architecture

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

- Interactive diagram: https://gitdiagram.com/vanshcloud/predictive-maintenance-genai
- Repository: https://github.com/vanshcloud/predictive-maintenance-genai

## Overview

This is a predictive-maintenance product: sensor data is validated and transformed into time windows, an LSTM estimates 24-hour failure risk, and a report layer explains predictions as technician-facing maintenance guidance. Users reach predictions and reports through the REST API or dashboard. The README documents the training/data pipeline and dashboard capabilities; source excerpts show API startup, inference preprocessing, and report generation. Some subsystem links rely on README statements or the source index rather than inspected implementations.

Main entry points: [`src/api/main.py`](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/main.py) (API Application), [`src/api/service.py`](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/service.py) (Shared Service State), [`src/prediction/predictor.py`](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/prediction/predictor.py) (Failure Predictor), [`src/api/routes/predict.py`](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/routes/predict.py) (Prediction Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Telemetry and Features"]
  node_sensor_data[("Sensor Tables")]
  node_ingestion["Data Ingestion<br/>[ingestion.py]"]
  node_validation["Data Validation<br/>[validation.py]"]
  node_preprocessing["Feature Pipeline<br/>[preprocessing.py]"]
end

subgraph group_ml["Model and Inference"]
  node_trainer["Model Trainer<br/>[trainer.py]"]
  node_lstm["LSTM Model<br/>[lstm_model.py]"]
  node_evaluator["Model Evaluation<br/>[evaluator.py]"]
  node_predictor["Failure Predictor<br/>[predictor.py]"]
end

subgraph group_api["Service API"]
  node_api_main["API Application<br/>[main.py]"]
  node_api_service["Shared Service State<br/>[service.py]"]
  node_api_schemas["Request Schemas<br/>[schemas.py]"]
  node_predict_routes["Prediction Routes<br/>[predict.py]"]
  node_machine_routes["Machine Routes<br/>[machines.py]"]
  node_health_routes["Health Routes<br/>[health.py]"]
  node_report_routes["Report Routes<br/>[reports.py]"]
end

subgraph group_genai["Maintenance Guidance"]
  node_report_generator["Report Generator<br/>[chains.py]"]
  node_prompt_templates["Grounded Prompts<br/>[prompts.py]"]
end

subgraph group_ui["Technician Dashboard"]
  node_dashboard["Dashboard<br/>[app.py]"]
  node_dashboard_client["API Client<br/>[api_client.py]"]
  node_risk_display["Risk Display<br/>[risk.py]"]
end

node_technician(("Technician"))
node_llm_provider{{"LLM Provider"}}

node_technician -->|"views risk"| node_dashboard
node_dashboard -->|"uses client"| node_dashboard_client
node_dashboard -->|"renders risk"| node_risk_display
node_dashboard_client -->|"calls REST API"| node_api_main
node_technician -->|"requests predictions"| node_api_main
node_api_main -->|"registers route"| node_health_routes
node_api_main -->|"registers route"| node_machine_routes
node_api_main -->|"registers route"| node_predict_routes
node_api_main -->|"registers route"| node_report_routes
node_api_main -->|"starts state"| node_api_service
node_predict_routes -->|"validates requests"| node_api_schemas
node_predict_routes -->|"requests scoring"| node_api_service
node_machine_routes -->|"requests machine data"| node_api_service
node_health_routes -->|"checks readiness"| node_api_service
node_report_routes -->|"gets prediction"| node_api_service
node_report_routes -->|"generates report"| node_report_generator
node_api_service -->|"scores machines"| node_predictor
node_api_service -->|"validates data"| node_validation
node_sensor_data -.->|"supplies tables"| node_ingestion
node_ingestion -.->|"loads for checks"| node_validation
node_validation -.->|"validates before features"| node_preprocessing
node_preprocessing -.->|"builds training features"| node_trainer
node_trainer -->|"trains model"| node_lstm
node_evaluator -->|"evaluates model"| node_lstm
node_predictor -->|"reuses features"| node_preprocessing
node_predictor -->|"scores windows"| node_lstm
node_report_generator -->|"formats context"| node_prompt_templates
node_report_generator -.->|"invokes model"| node_llm_provider

click node_ingestion "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/data/ingestion.py"
click node_validation "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/data/validation.py"
click node_preprocessing "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/data/preprocessing.py"
click node_trainer "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/models/trainer.py"
click node_lstm "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/models/lstm_model.py"
click node_evaluator "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/models/evaluator.py"
click node_predictor "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/prediction/predictor.py"
click node_api_main "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/main.py"
click node_api_service "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/service.py"
click node_api_schemas "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/schemas.py"
click node_predict_routes "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/routes/predict.py"
click node_machine_routes "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/routes/machines.py"
click node_health_routes "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/routes/health.py"
click node_report_routes "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/routes/reports.py"
click node_report_generator "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/genai/chains.py"
click node_prompt_templates "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/genai/prompts.py"
click node_dashboard "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/dashboard/app.py"
click node_dashboard_client "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/dashboard/api_client.py"
click node_risk_display "https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/dashboard/risk.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_sensor_data,node_ingestion,node_validation,node_preprocessing toneBlue
class node_trainer,node_lstm,node_evaluator,node_predictor toneAmber
class node_api_main,node_api_service,node_api_schemas,node_predict_routes,node_machine_routes,node_health_routes,node_report_routes toneMint
class node_report_generator,node_prompt_templates toneRose
class node_dashboard,node_dashboard_client,node_risk_display,node_technician,node_llm_provider toneIndigo
```

## Components

### Telemetry and Features

- **Sensor Tables**
- [Data Ingestion](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/data/ingestion.py): `src/data/ingestion.py`
- [Data Validation](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/data/validation.py): `src/data/validation.py`
- [Feature Pipeline](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/data/preprocessing.py): `src/data/preprocessing.py`

### Model and Inference

- [Model Trainer](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/models/trainer.py): `src/models/trainer.py`
- [LSTM Model](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/models/lstm_model.py): `src/models/lstm_model.py`
- [Model Evaluation](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/models/evaluator.py): `src/models/evaluator.py`
- [Failure Predictor](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/prediction/predictor.py): `src/prediction/predictor.py`

### Service API

- [API Application](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/main.py): `src/api/main.py`
- [Shared Service State](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/service.py): `src/api/service.py`
- [Request Schemas](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/schemas.py): `src/api/schemas.py`
- [Prediction Routes](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/routes/predict.py): `src/api/routes/predict.py`
- [Machine Routes](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/routes/machines.py): `src/api/routes/machines.py`
- [Health Routes](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/routes/health.py): `src/api/routes/health.py`
- [Report Routes](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/api/routes/reports.py): `src/api/routes/reports.py`

### Maintenance Guidance

- [Report Generator](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/genai/chains.py): `src/genai/chains.py`
- [Grounded Prompts](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/src/genai/prompts.py): `src/genai/prompts.py`

### Technician Dashboard

- [Dashboard](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/dashboard/app.py): `dashboard/app.py`
- [API Client](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/dashboard/api_client.py): `dashboard/api_client.py`
- [Risk Display](https://github.com/vanshcloud/predictive-maintenance-genai/blob/main/dashboard/risk.py): `dashboard/risk.py`

### Other components

- **Technician**
- **LLM Provider**

## Connections

- Technician → Dashboard: views risk (evidence: `README.md`)
- Dashboard → API Client: uses client (evidence: `dashboard/app.py`)
- Dashboard → Risk Display: renders risk (evidence: `dashboard/app.py`)
- API Client → API Application: calls REST API (evidence: `README.md`)
- Technician → API Application: requests predictions (evidence: `README.md`)
- API Application → Health Routes: registers route (evidence: `src/api/main.py`)
- API Application → Machine Routes: registers route (evidence: `src/api/main.py`)
- API Application → Prediction Routes: registers route (evidence: `src/api/main.py`)
- API Application → Report Routes: registers route (evidence: `src/api/main.py`)
- API Application → Shared Service State: starts state (evidence: `src/api/main.py`)
- Prediction Routes → Request Schemas: validates requests (evidence: `src/api/routes/predict.py`)
- Prediction Routes → Shared Service State: requests scoring (evidence: `src/api/routes/predict.py`)
- Machine Routes → Shared Service State: requests machine data (evidence: `src/api/routes/machines.py`)
- Health Routes → Shared Service State: checks readiness (evidence: `src/api/routes/health.py`)
- Report Routes → Shared Service State: gets prediction (evidence: `src/api/routes/reports.py`)
- Report Routes → Report Generator: generates report (evidence: `src/api/routes/reports.py`)
- Shared Service State → Failure Predictor: scores machines (evidence: `src/api/service.py`)
- Shared Service State → Data Validation: validates data (evidence: `src/api/service.py`)
- Sensor Tables → Data Ingestion: supplies tables (evidence: `src/data/ingestion.py`)
- Data Ingestion → Data Validation: loads for checks
- Data Validation → Feature Pipeline: validates before features
- Feature Pipeline → Model Trainer: builds training features (evidence: `README.md`)
- Model Trainer → LSTM Model: trains model (evidence: `src/models/trainer.py`)
- Model Evaluation → LSTM Model: evaluates model (evidence: `src/models/evaluator.py`)
- Failure Predictor → Feature Pipeline: reuses features (evidence: `src/prediction/predictor.py`)
- Failure Predictor → LSTM Model: scores windows (evidence: `src/prediction/predictor.py`)
- Report Generator → Grounded Prompts: formats context (evidence: `src/genai/chains.py`)
- Report Generator → LLM Provider: invokes model (evidence: `src/genai/chains.py`)
