# sa1f27/predictive-maintenance-mlops architecture

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

- Interactive diagram: https://gitdiagram.com/sa1f27/predictive-maintenance-mlops
- Repository: https://github.com/sa1f27/predictive-maintenance-mlops

## Overview

This repository is an end-to-end predictive maintenance ML system with a clear split between offline ML workflows and online inference/serving.

#### 1) High-level system shape

The repo is organized around four major concerns:

1. **Data preparation and model training**
2. **Model tracking and evaluation**
3. **Prediction serving and batch inference**
4. **Deployment/ops automation**

The core architecture is:

- **Raw industrial sensor data** enters from `Data/predictive_maintenance.csv`
- The **training pipeline** ingests and transforms the data into reusable artifacts under `artifacts/`
- A **model trainer** fits and evaluates multiple ML classifiers
- **MLflow** is used for experiment tracking and likely model/version management
- The selected model is used by the **prediction pipeline** and exposed through the **API/web app**
- The entire service is containerized with **Docker**, and CI/CD is handled via **GitHub Actions**
- Deployment targets **AWS ECR + ECS** per the README

#### 2) Main subsystems

##### A. Data ingestion and preparation
Located in `src/components/`:

- `data_ingestion.py`
- `data_transformation.py`

This is the offline ETL layer.

**Role in architecture:**
- Reads the raw CSV dataset
- Splits data into training and test sets
- Persists processed artifacts to `artifacts/`:
  - `artifacts/data.csv`
  - `artifacts/train.csv`
  - `artifacts/test.csv`

**Boundary:**
This layer is the handoff point between raw data and model-ready data. It is separate from training so the same transformed datasets can be reused for evaluation and inference workflows.

##### B. Model training
Located in `src/components/model_trainer.py`

**Role in architecture:**
- Trains one or more classification models on the prepared data
- The README indicates the project compares multiple models such as:
  - Random Forest
  - Gradient Boosting
  - Logistic Regression
  - SVM
- Model selection is based on evaluation metrics like accuracy, precision, recall, and F1

**Boundary:**
This is the core ML experimentation layer. It depends on transformed data, but not on the web/API layer.

##### C. Pipeline orchestration
Located in `src/pipeline/`:

- `train_pipeline.py`
- `model_evaluation.py`
- `predict_pipeline.py`
- `batch_prediction.py`

These files define the executable workflows.

**Their responsibilities are distinct:**
- **Training pipeline**: end-to-end ingestion → transformation → training
- **Model evaluation pipeline**: measures model performance and likely decides whether the model is acceptable for deployment
- **Prediction pipeline**: handles single-record or API-driven inference
- **Batch prediction pipeline**: runs inference over an input file and writes prediction outputs

**Boundary:**
This layer is the orchestration layer connecting components to runtime entry points. It separates business workflows from implementation details.

##### D. MLOps / experiment tracking
Located in `src/mlops/mlflow_manager.py`

**Role in architecture:**
- Centralizes MLflow interactions
- Likely logs metrics, parameters, and model artifacts
- Supports reproducibility and model comparison

**Boundary:**
This is the bridge between training/evaluation code and external experiment tracking infrastructure. It keeps MLflow concerns out of model-training logic.

##### E. Serving layer / application runtime
Top-level `app.py`, plus `templates/` and `static/`

**Role in architecture:**
- Serves the prediction application
- README indicates FastAPI as the API layer
- `templates/home.html` and `templates/index.html` plus `static/css/style.css` suggest there is also a lightweight HTML frontend, likely for manual prediction entry or landing pages

**Boundary:**
This is the online inference boundary. It should be treated separately from offline training pipelines because it consumes the saved model/artifacts rather than raw training data.

##### F. Utilities and cross-cutting concerns
Located in `src/utils.py`, `src/logger.py`, `src/exception.py`

**Role in architecture:**
- Shared helpers
- Structured logging
- Custom exception handling

These are cross-cutting support layers used throughout ingestion, transformation, training, and serving.

#### 3) Data flow through the system

##### Offline training flow
1. **Raw data ingestion**
   - Source: `Data/predictive_maintenance.csv`
2. **Preprocessing and splitting**
   - Output to `artifacts/`
3. **Model training**
   - Trains and compares candidate classifiers
4. **Evaluation**
   - Metrics are computed and likely logged to MLflow
5. **Artifact persistence**
   - Training outputs are stored for reuse by inference code
6. **Visualization/output**
   - Evaluation plots appear under `evaluation_plots/`

##### Online prediction flow
1. A user or client sends input to the **FastAPI app** in `app.py`
2. The app likely calls the **prediction pipeline**
3. The pipeline loads the trained model and any preprocessing artifacts
4. The system returns a failure prediction to the caller
5. For batch jobs, predictions are written to `predictions/` as CSV files

##### Batch inference flow
- Input data file is processed by `src/pipeline/batch_prediction.py`
- Output prediction CSVs are written into `predictions/`
- Example outputs already exist:
  - `predictions/batch_predictions_20250717_151026.csv`
  - `predictions/batch_predictions_20250717_151925.csv`

This is a separate path from interactive/API prediction and is useful for operational reporting or scheduled scoring jobs.

#### 4) Important architectural boundaries

##### Training vs serving
This is the most important boundary in the repo.

- **Training side**: `src/components/`, `src/pipeline/train_pipeline.py`, `model_evaluation.py`
- **Serving side**: `app.py`, `predict_pipeline.py`, templates/static assets

The serving layer should not retrain models; it should only consume trained artifacts.

##### Offline artifacts vs runtime requests
The repository stores multiple artifact types:

- `artifacts/` for processed datasets
- `evaluation_plots/` for metrics/diagnostics
- `predictions/` for batch inference outputs

These are evidence that the system is designed to persist intermediate ML outputs rather than only returning ephemeral results.

##### Model experimentation vs deployment
- **MLflow** handles the experimentation/model-registry side
- **Docker/ECS** handle production execution
- **GitHub Actions** coordinates build/test/deploy automation

This means the project has a clean separation between ML lifecycle management and infrastructure delivery.

#### 5) Deployment and operations

##### Containerization
- `Dockerfile` and `docker-compose.yml` indicate the app runs in a containerized local/production-like environment.
- Docker is the packaging boundary around the API and model runtime.

##### CI/CD
- `.github/workflows/main.yaml` indicates an automated pipeline
- Based on the README, the workflow likely:
  - builds the Docker image
  - runs validation/tests
  - pushes to **AWS ECR**
  - deploys to **AWS ECS**

##### Cloud target
- The architecture is intended for **AWS ECS** as the runtime platform
- **AWS ECR** serves as the image registry

This implies the deployed unit is the containerized API application, not a separate model server.

#### 6) Repository structure summary for diagramming

If you are drawing the architecture, the main boxes should be:

- **Data source**
  - `Data/predictive_maintenance.csv`
- **Offline ML pipeline**
  - ingestion
  - transformation
  - training
  - evaluation
- **Experiment tracking**
  - MLflow manager
- **Artifacts store**
  - `artifacts/`, `evaluation_plots/`, `predictions/`
- **Online inference service**
  - `app.py`
  - FastAPI
  - templates/static UI
- **Batch inference service**
  - `src/pipeline/batch_prediction.py`
- **Packaging/runtime**
  - Docker, Docker Compose
- **CI/CD**
  - GitHub Actions
- **Cloud deployment**
  - AWS ECR
  - AWS ECS

#### 7) What this repo is optimized for

This is not just a model notebook export. It is structured as a production ML application with:

- reproducible training
- tracked experiments
- persisted artifacts
- both interactive and batch inference
- containerized deployment
- automated cloud delivery

So the architecture diagram should emphasize a **production ML lifecycle** rather than a single request/response web app.

Main entry points: [`app.py`](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/app.py) (API app), [`src/pipeline/model_evaluation.py`](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/model_evaluation.py) (Evaluate), [`src/components/model_trainer.py`](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/components/model_trainer.py) (Train models), [`src/pipeline/train_pipeline.py`](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/train_pipeline.py) (Train pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_data["Data & artifacts"]
  node_n_source["Raw data<br/>dataset"]
  node_n_artifacts[("Artifacts<br/>stored data")]
  node_n_plots["Eval plots<br/>metrics output"]
  node_n_preds["Predictions<br/>batch outputs"]
end

subgraph group_g_offline["Offline ML"]
  node_n_ingest["Ingestion<br/>etl component<br/>[data_ingestion.py]"]
  node_n_transform["Transform<br/>preprocess component"]
  node_n_train["Train models<br/>training component<br/>[model_trainer.py]"]
  node_n_eval["Evaluate<br/>pipeline stage"]
  node_n_mlflow["MLflow<br/>tracking layer<br/>[mlflow_manager.py]"]
  node_n_trainpipe["Train pipeline<br/>orchestrator<br/>[train_pipeline.py]"]
end

subgraph group_g_online["Online inference"]
  node_n_predictpipe["Predict pipeline<br/>inference pipeline"]
  node_n_batch["Batch scoring<br/>batch pipeline"]
  node_n_app["API app<br/>serving app<br/>[app.py]"]
  node_n_ui["Web UI<br/>frontend"]
end

subgraph group_g_ops["Delivery & runtime"]
  node_n_run["Run entrypoint<br/>bootstrap<br/>[run_pipeline.py]"]
  node_n_docker["Docker<br/>containerization"]
  node_n_compose["Compose<br/>local runtime<br/>[docker-compose.yml]"]
  node_n_ci["CI workflow<br/>automation<br/>[main.yaml]"]
end

node_n_source -->|"raw input"| node_n_ingest
node_n_ingest -->|"prepared data"| node_n_transform
node_n_transform -->|"writes"| node_n_artifacts
node_n_artifacts -->|"training data"| node_n_train
node_n_train -->|"trained model"| node_n_eval
node_n_eval -->|"diagnostics"| node_n_plots
node_n_train -->|"metrics/artifacts"| node_n_mlflow
node_n_mlflow -.->|"tracking context"| node_n_eval
node_n_eval -->|"gate"| node_n_trainpipe
node_n_trainpipe -->|"pipeline entry"| node_n_run
node_n_trainpipe -->|"saved model"| node_n_app
node_n_app -->|"request handling"| node_n_predictpipe
node_n_predictpipe -->|"loads preprocessing"| node_n_artifacts
node_n_predictpipe -->|"batch output"| node_n_preds
node_n_batch -->|"writes"| node_n_preds
node_n_ui -->|"user interaction"| node_n_app
node_n_docker -->|"packages"| node_n_app
node_n_compose -->|"local run"| node_n_docker
node_n_ci -->|"builds image"| node_n_docker
node_n_ci -->|"deploys"| node_n_app

click node_n_source "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/Data/predictive_maintenance.csv"
click node_n_artifacts "https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/artifacts"
click node_n_plots "https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/evaluation_plots"
click node_n_preds "https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/predictions"
click node_n_ingest "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/components/data_ingestion.py"
click node_n_transform "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/components/data_transformation.py"
click node_n_train "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/components/model_trainer.py"
click node_n_eval "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/model_evaluation.py"
click node_n_mlflow "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/mlops/mlflow_manager.py"
click node_n_trainpipe "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/train_pipeline.py"
click node_n_predictpipe "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/predict_pipeline.py"
click node_n_batch "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/batch_prediction.py"
click node_n_app "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/app.py"
click node_n_ui "https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/templates"
click node_n_run "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/run_pipeline.py"
click node_n_docker "https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/Dockerfile"
click node_n_compose "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/docker-compose.yml"
click node_n_ci "https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/.github/workflows/main.yaml"

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_n_source,node_n_artifacts,node_n_plots,node_n_preds toneBlue
class node_n_ingest,node_n_transform,node_n_train,node_n_eval,node_n_mlflow,node_n_trainpipe toneAmber
class node_n_predictpipe,node_n_batch,node_n_app,node_n_ui toneMint
class node_n_run,node_n_docker,node_n_compose,node_n_ci toneRose
```

## Components

### Data & artifacts

Raw inputs and persisted ML outputs

- [Raw data](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/Data/predictive_maintenance.csv): dataset · Industrial sensor input for the pipeline · `Data/predictive_maintenance.csv`
- [Artifacts](https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/artifacts): stored data · Processed train/test splits and derived datasets · `artifacts`
- [Eval plots](https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/evaluation_plots): metrics output · Saved evaluation diagnostics and plots · `evaluation_plots`
- [Predictions](https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/predictions): batch outputs · Stored batch scoring results · `predictions`

### Offline ML

Training, evaluation, and experiment tracking

- [Ingestion](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/components/data_ingestion.py): etl component · Loads raw CSV and prepares initial data · `src/components/data_ingestion.py`
- [Transform](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/components/data_transformation.py): preprocess component · Cleans, splits, and writes model-ready datasets · `src/components/data_transformation.py`
- [Train models](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/components/model_trainer.py): training component · Fits and compares candidate classifiers · `src/components/model_trainer.py`
- [Evaluate](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/model_evaluation.py): pipeline stage · Computes metrics and determines model quality · `src/pipeline/model_evaluation.py`
- [MLflow](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/mlops/mlflow_manager.py): tracking layer · Logs metrics, parameters, and artifacts · `src/mlops/mlflow_manager.py`
- [Train pipeline](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/train_pipeline.py): orchestrator · End-to-end offline training workflow · `src/pipeline/train_pipeline.py`

### Online inference

API and batch prediction runtime

- [Predict pipeline](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/predict_pipeline.py): inference pipeline · Loads trained artifacts for single-request inference · `src/pipeline/predict_pipeline.py`
- [Batch scoring](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/src/pipeline/batch_prediction.py): batch pipeline · Runs inference over files and writes CSV outputs · `src/pipeline/batch_prediction.py`
- [API app](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/app.py): serving app · FastAPI service and web entrypoint · `app.py`
- [Web UI](https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/templates): frontend · HTML templates and static styling for manual use · `templates`

### Delivery & runtime

Packaging and deployment automation

- [Run entrypoint](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/run_pipeline.py): bootstrap · Launches the project pipelines · `run_pipeline.py`
- [Docker](https://github.com/sa1f27/predictive-maintenance-mlops/tree/main/Dockerfile): containerization · Builds the runtime image and local service stack · `Dockerfile`
- [Compose](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/docker-compose.yml): local runtime · Coordinates the containerized app locally · `docker-compose.yml`
- [CI workflow](https://github.com/sa1f27/predictive-maintenance-mlops/blob/main/.github/workflows/main.yaml): automation · Builds and deploys through GitHub Actions · `.github/workflows/main.yaml`

## Connections

- Raw data → Ingestion: raw input · Reads the industrial dataset
- Ingestion → Transform: prepared data · Hands off cleaned data for splitting and processing
- Transform → Artifacts: writes · Persists train/test and derived datasets
- Artifacts → Train models: training data · Provides reusable model-ready inputs
- Train models → Evaluate: trained model · Sends candidate models for assessment
- Evaluate → Eval plots: diagnostics · Stores evaluation outputs and plots
- Train models → MLflow: metrics/artifacts · Tracks experiments and model metadata
- MLflow → Evaluate: tracking context · Supports evaluation and comparison
- Evaluate → Train pipeline: gate · Feeds the end-to-end offline workflow
- Train pipeline → Run entrypoint: pipeline entry · Executed from the repository entrypoint
- Train pipeline → API app: saved model · Produces artifacts consumed by serving
- API app → Predict pipeline: request handling · Delegates prediction logic to the inference pipeline
- Predict pipeline → Artifacts: loads preprocessing · Uses persisted training artifacts for inference
- Predict pipeline → Predictions: batch output · Writes scored records for offline jobs
- Batch scoring → Predictions: writes · Persists batch prediction CSVs
- Web UI → API app: user interaction · Front-end pages are served by the application
- Docker → API app: packages · Containerizes the API/runtime
- Compose → Docker: local run · Starts the containerized stack
- CI workflow → Docker: builds image · Automated packaging in CI
- CI workflow → API app: deploys · Delivery pipeline targets the service runtime
