# m-shas/railway-track-fault-detection-and-predictive-maintenance architecture

> Architecture diagram of the GitHub repository m-shas/railway-track-fault-detection-and-predictive-maintenance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m-shas/railway-track-fault-detection-and-predictive-maintenance
- Repository: https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance

## Overview

The product is a railway-track fault detection and predictive-maintenance system. Its main workflow loads PLC and vibration sensor data, preprocesses it, runs anomaly and fault/RUL models, then produces maintenance alerts and dashboard outputs. The README also documents optional sequence models and SHAP explainability. The pipeline excerpt confirms alert and dashboard-data generation; other orchestration links reflect the README’s phase description, while uncertain wiring is omitted.

Main entry points: [`src/pipeline.py`](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/pipeline.py) (Pipeline Orchestrator), [`src/preprocess.py`](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/preprocess.py) (Preprocessing), [`src/classifier.py`](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/classifier.py) (Fault Classifier), [`src/alerts.py`](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/alerts.py) (Alert & Action Rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Sensor Inputs"]
  node_preprocess["Preprocessing<br/>[preprocess.py]"]
end

subgraph group_analysis["Data &amp; Models"]
  node_pipeline["Pipeline Orchestrator<br/>[pipeline.py]"]
  node_anomaly["Anomaly Detection<br/>[anomaly_model.py]"]
  node_rul["RUL Predictor<br/>[rul_model.py]"]
  node_classifier["Fault Classifier<br/>[classifier.py]"]
  node_bilstm["BiLSTM RUL<br/>[lstm_rul_model.py]"]
  node_cnn_lstm["CNN-LSTM Classifier<br/>[cnn_lstm_model.py]"]
  node_xai["SHAP Explainability<br/>[xai_explainer.py]"]
  node_relabel["Data Relabeling<br/>[relabel_data.py]"]
end

subgraph group_maintenance["Maintenance Decisions"]
  node_alerts["Alert &amp; Action Rules<br/>[alerts.py]"]
  node_alert_log["Alert Log<br/>[alerts.py]"]
end

subgraph group_presentation["Dashboards &amp; Outputs"]
  node_html_dashboard["HTML Dashboard<br/>[pipeline.py]"]
  node_dashboard_data["Dashboard Data<br/>[pipeline.py]"]
  node_streamlit["Streamlit Dashboard<br/>[app.py]"]
end

node_sensor_data(("PLC &amp; Vibration Data"))
node_maintainer(("Maintenance User"))

node_sensor_data -->|"starts run"| node_pipeline
node_pipeline -->|"runs preprocessing"| node_preprocess
node_preprocess -->|"returns features"| node_pipeline
node_pipeline -->|"trains detector"| node_anomaly
node_pipeline -->|"trains RUL model"| node_rul
node_pipeline -->|"trains classifier"| node_classifier
node_pipeline -.->|"trains optional model"| node_bilstm
node_pipeline -.->|"trains optional model"| node_cnn_lstm
node_pipeline -->|"generates alerts"| node_alerts
node_alerts -->|"returns alert log"| node_pipeline
node_pipeline -->|"exports CSV"| node_alert_log
node_pipeline -->|"builds and saves"| node_dashboard_data
node_pipeline -->|"builds dashboard"| node_html_dashboard
node_dashboard_data -->|"displayed by"| node_streamlit
node_maintainer -->|"views dashboard"| node_html_dashboard
node_maintainer -->|"uses dashboard"| node_streamlit
node_classifier -.->|"explains predictions"| node_xai

click node_pipeline "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/pipeline.py"
click node_preprocess "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/preprocess.py"
click node_anomaly "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/anomaly_model.py"
click node_rul "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/rul_model.py"
click node_classifier "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/classifier.py"
click node_bilstm "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/lstm_rul_model.py"
click node_cnn_lstm "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/cnn_lstm_model.py"
click node_xai "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/xai_explainer.py"
click node_alerts "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/alerts.py"
click node_relabel "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/relabel_data.py"
click node_html_dashboard "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/pipeline.py"
click node_dashboard_data "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/pipeline.py"
click node_alert_log "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/alerts.py"
click node_streamlit "https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/app.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_preprocess,node_maintainer toneBlue
class node_pipeline,node_anomaly,node_rul,node_classifier,node_bilstm,node_cnn_lstm,node_xai,node_relabel toneAmber
class node_alerts,node_alert_log toneMint
class node_html_dashboard,node_dashboard_data,node_streamlit toneRose
class node_sensor_data toneIndigo
```

## Components

### Sensor Inputs

- [Preprocessing](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/preprocess.py): `src/preprocess.py`

### Data & Models

- [Pipeline Orchestrator](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/pipeline.py): `src/pipeline.py`
- [Anomaly Detection](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/anomaly_model.py): `src/anomaly_model.py`
- [RUL Predictor](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/rul_model.py): `src/rul_model.py`
- [Fault Classifier](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/classifier.py): `src/classifier.py`
- [BiLSTM RUL](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/lstm_rul_model.py): `src/lstm_rul_model.py`
- [CNN-LSTM Classifier](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/cnn_lstm_model.py): `src/cnn_lstm_model.py`
- [SHAP Explainability](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/xai_explainer.py): `src/xai_explainer.py`
- [Data Relabeling](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/relabel_data.py): `src/relabel_data.py`

### Maintenance Decisions

- [Alert & Action Rules](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/alerts.py): `src/alerts.py`
- [Alert Log](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/alerts.py): `src/alerts.py`

### Dashboards & Outputs

- [HTML Dashboard](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/pipeline.py): `src/pipeline.py`
- [Dashboard Data](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/src/pipeline.py): `src/pipeline.py`
- [Streamlit Dashboard](https://github.com/m-shas/railway-track-fault-detection-and-predictive-maintenance/blob/master/app.py): `app.py`

### Other components

- **PLC & Vibration Data**
- **Maintenance User**

## Connections

- PLC & Vibration Data → Pipeline Orchestrator: starts run
- Pipeline Orchestrator → Preprocessing: runs preprocessing
- Preprocessing → Pipeline Orchestrator: returns features
- Pipeline Orchestrator → Anomaly Detection: trains detector
- Pipeline Orchestrator → RUL Predictor: trains RUL model
- Pipeline Orchestrator → Fault Classifier: trains classifier
- Pipeline Orchestrator → BiLSTM RUL: trains optional model
- Pipeline Orchestrator → CNN-LSTM Classifier: trains optional model
- Pipeline Orchestrator → Alert & Action Rules: generates alerts
- Alert & Action Rules → Pipeline Orchestrator: returns alert log
- Pipeline Orchestrator → Alert Log: exports CSV
- Pipeline Orchestrator → Dashboard Data: builds and saves
- Pipeline Orchestrator → HTML Dashboard: builds dashboard
- Dashboard Data → Streamlit Dashboard: displayed by
- Maintenance User → HTML Dashboard: views dashboard
- Maintenance User → Streamlit Dashboard: uses dashboard
- Fault Classifier → SHAP Explainability: explains predictions