# nitin020305/ann-customer-churn-e2e-pipeline architecture

> Architecture diagram of the GitHub repository nitin020305/ann-customer-churn-e2e-pipeline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nitin020305/ann-customer-churn-e2e-pipeline
- Repository: https://github.com/nitin020305/ann-customer-churn-e2e-pipeline

## Overview

1. This repository is an end-to-end customer churn prediction system built around an ANN. It has two distinct runtime paths: an offline training/tuning pipeline that produces versioned artifacts, and an online Flask inference app that loads the latest trained artifacts to serve predictions.

2. The main domain flow starts with the raw dataset in `notebooks/data/Churn_Modelling.csv`. Training reads that CSV, validates it, transforms categorical/numeric features, trains a neural network, and writes outputs under a timestamped `artifacts/` run folder. Each training run is isolated so previous runs are preserved.

3. `src/churn_predictor/components/` contains the pipeline stages as separate units with clear boundaries:
   - `data_ingestion.py` loads the CSV and creates train/test splits.
   - `data_validation.py` checks schema and data quality.
   - `data_transformation.py` encodes `Gender`, one-hot encodes `Geography`, and scales features using train-fitted preprocessors only.
   - `model_trainer.py` builds and fits the ANN.
   - `hyperparameter_tuning.py` runs `GridSearchCV` over ANN settings using `scikeras`.
   - `model_evaluation.py` computes metrics and writes them to disk.

4. The orchestration layer lives in `src/churn_predictor/pipeline/`. `training_pipeline.py` chains the components in order and is the core of `train.py`. `prediction_pipeline.py` is separate from training and is responsible for inference-time preprocessing plus model loading.

5. The repository uses explicit typed boundaries between stages via `src/churn_predictor/entity/`. `config_entity.py` defines stage-specific configuration and artifact paths, while `artifact_entity.py` defines the outputs passed from one stage to the next. This keeps component dependencies explicit and reduces reliance on globals.

6. `src/churn_predictor/constants.py` acts as the central source of truth for magic values: file names, column names, split ratios, and ANN-related hyperparameters. That makes the training and inference logic consistent across modules and simplifies tuning.

7. Persistence and reproducibility are handled through `artifacts/`. The training pipeline stores preprocessors, transformed arrays, the Keras model (`model.h5`), TensorBoard logs, and evaluation outputs such as `metrics.yaml`. The prediction pipeline discovers the latest artifact set instead of hardcoding a path, so the app always targets the newest trained model.

8. Supporting infrastructure sits in `src/churn_predictor/utils/main_utils.py`, which provides YAML and pickle/numpy serialization helpers. Logging and error handling are centralized in `src/churn_predictor/logger/` and `src/churn_predictor/exception/`, giving all stages a consistent operational and debugging model.

9. The runtime-facing app is `app.py`, backed by Flask templates in `templates/index.html` and styles in `static/css/style.css`. It does not train anything; it only collects user input, sends it through `PredictionPipeline`, and returns the churn result.

10. `train.py` and `tune.py` are thin entry points for the two offline workflows: full retraining and hyperparameter search. The notebooks under `notebooks/` contain the original exploratory analysis and tuning experiments that were later refactored into the modular source tree.

11. Deployment is containerized with `Dockerfile` and `docker-compose.yml`. The container expects trained artifacts to exist, and compose also mounts `artifacts/` so newly generated models can be picked up without rebuilding the image.

12. Tests are lightweight and focused on component behavior via `tests/test_components.py`. Overall, the architecture is a classic layered ML application: data ingestion/validation at the bottom, transformation and model training in the middle, artifact persistence at the boundary, and a separate inference service on top.

Main entry points: [`src/churn_predictor/pipeline/training_pipeline.py`](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/pipeline/training_pipeline.py) (Training pipeline), [`src/churn_predictor/components/data_transformation.py`](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/data_transformation.py) (Transformation), [`src/churn_predictor/pipeline/prediction_pipeline.py`](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/pipeline/prediction_pipeline.py) (Prediction pipeline), [`src/churn_predictor/components/data_ingestion.py`](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/data_ingestion.py) (Ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtimes"]
  node_train_py["train.py<br/>entrypoint<br/>[train.py]"]
  node_tune_py["tune.py<br/>entrypoint<br/>[tune.py]"]
  node_app_py["app.py<br/>flask app<br/>[app.py]"]
end

subgraph group_pipeline["ML Pipeline"]
  node_training_pipeline["Training pipeline<br/>orchestrator"]
  node_prediction_pipeline["Prediction pipeline<br/>orchestrator"]
  node_data_ingestion["Ingestion<br/>pipeline stage<br/>[data_ingestion.py]"]
  node_data_validation["Validation<br/>pipeline stage<br/>[data_validation.py]"]
  node_data_transformation["Transformation<br/>pipeline stage"]
  node_model_trainer["Trainer<br/>pipeline stage<br/>[model_trainer.py]"]
  node_hyperparameter_tuning["Tuning<br/>pipeline stage"]
  node_model_evaluation["Evaluation<br/>pipeline stage"]
end

subgraph group_support["Support"]
  node_config_entity["Config entity<br/>typed boundary<br/>[config_entity.py]"]
  node_artifact_entity["Artifact entity<br/>typed boundary<br/>[artifact_entity.py]"]
  node_constants["Constants<br/>shared config<br/>[constants.py]"]
  node_main_utils["Main utils<br/>serialization<br/>[main_utils.py]"]
  node_logger(("Logger<br/>ops support"))
  node_exception(("Exception<br/>ops support"))
  node_artifacts_dir[("artifacts/<br/>versioned storage")]
  node_dataset["Churn CSV<br/>raw data"]
  node_tests_components["Component tests<br/>[test_components.py]"]
end

node_train_py -->|"runs"| node_training_pipeline
node_tune_py -->|"runs"| node_hyperparameter_tuning
node_app_py -->|"uses"| node_prediction_pipeline
node_training_pipeline -->|"orders"| node_data_ingestion
node_training_pipeline -->|"orders"| node_data_validation
node_training_pipeline -->|"orders"| node_data_transformation
node_training_pipeline -->|"orders"| node_model_trainer
node_training_pipeline -->|"orders"| node_model_evaluation
node_prediction_pipeline -->|"reuses"| node_data_transformation
node_prediction_pipeline -->|"loads latest"| node_artifacts_dir
node_data_ingestion -->|"reads"| node_dataset
node_data_ingestion -->|"emits"| node_artifact_entity
node_data_validation -->|"checks"| node_constants
node_data_transformation -->|"maps"| node_constants
node_model_trainer -->|"configures"| node_constants
node_hyperparameter_tuning -->|"searches"| node_constants
node_model_evaluation -->|"writes"| node_artifacts_dir
node_data_transformation -->|"serializes"| node_main_utils
node_model_trainer -->|"writes"| node_artifacts_dir
node_training_pipeline -->|"builds"| node_config_entity
node_training_pipeline -->|"passes"| node_artifact_entity
node_app_py -->|"logs"| node_logger
node_training_pipeline -->|"handles"| node_exception
node_prediction_pipeline -->|"handles"| node_exception
node_tests_components -->|"covers"| node_data_ingestion
node_tests_components -->|"covers"| node_data_transformation
node_tests_components -->|"covers"| node_model_trainer

click node_train_py "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/train.py"
click node_tune_py "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/tune.py"
click node_app_py "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/app.py"
click node_training_pipeline "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/pipeline/training_pipeline.py"
click node_prediction_pipeline "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/pipeline/prediction_pipeline.py"
click node_data_ingestion "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/data_ingestion.py"
click node_data_validation "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/data_validation.py"
click node_data_transformation "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/data_transformation.py"
click node_model_trainer "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/model_trainer.py"
click node_hyperparameter_tuning "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/hyperparameter_tuning.py"
click node_model_evaluation "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/model_evaluation.py"
click node_config_entity "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/entity/config_entity.py"
click node_artifact_entity "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/entity/artifact_entity.py"
click node_constants "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/constants.py"
click node_main_utils "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/utils/main_utils.py"
click node_logger "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/tree/main/src/churn_predictor/logger"
click node_exception "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/tree/main/src/churn_predictor/exception"
click node_artifacts_dir "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/tree/main/artifacts"
click node_dataset "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/notebooks/data/Churn_Modelling.csv"
click node_tests_components "https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/tests/test_components.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_train_py,node_tune_py,node_app_py toneBlue
class node_training_pipeline,node_prediction_pipeline,node_data_ingestion,node_data_validation,node_data_transformation,node_model_trainer,node_hyperparameter_tuning,node_model_evaluation toneAmber
class node_config_entity,node_artifact_entity,node_constants,node_main_utils,node_logger,node_exception,node_artifacts_dir,node_dataset,node_tests_components toneMint
```

## Components

### Runtimes

Offline training/tuning and online prediction entrypoints

- [train.py](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/train.py): entrypoint · Starts full offline retraining · `train.py`
- [tune.py](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/tune.py): entrypoint · Starts hyperparameter search · `tune.py`
- [app.py](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/app.py): flask app · Serves churn predictions to users · `app.py`

### ML Pipeline

Core training and inference stages

- [Training pipeline](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/pipeline/training_pipeline.py): orchestrator · Coordinates the offline end-to-end training flow · `src/churn_predictor/pipeline/training_pipeline.py`
- [Prediction pipeline](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/pipeline/prediction_pipeline.py): orchestrator · Loads latest artifacts and prepares inference-time predictions · `src/churn_predictor/pipeline/prediction_pipeline.py`
- [Ingestion](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/data_ingestion.py): pipeline stage · Loads CSV and creates train/test splits · `src/churn_predictor/components/data_ingestion.py`
- [Validation](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/data_validation.py): pipeline stage · Checks schema and data quality · `src/churn_predictor/components/data_validation.py`
- [Transformation](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/data_transformation.py): pipeline stage · Encodes and scales features using train-fitted preprocessors · `src/churn_predictor/components/data_transformation.py`
- [Trainer](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/model_trainer.py): pipeline stage · Builds and fits the ANN model · `src/churn_predictor/components/model_trainer.py`
- [Tuning](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/hyperparameter_tuning.py): pipeline stage · Searches ANN settings with scikeras and GridSearchCV · `src/churn_predictor/components/hyperparameter_tuning.py`
- [Evaluation](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/components/model_evaluation.py): pipeline stage · Computes metrics and writes evaluation outputs · `src/churn_predictor/components/model_evaluation.py`

### Support

Artifacts, utilities, and shared boundaries

- [Config entity](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/entity/config_entity.py): typed boundary · Stage-specific configuration and artifact paths · `src/churn_predictor/entity/config_entity.py`
- [Artifact entity](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/entity/artifact_entity.py): typed boundary · Structured outputs passed between stages · `src/churn_predictor/entity/artifact_entity.py`
- [Constants](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/constants.py): shared config · File names, columns, split ratios, and hyperparameters · `src/churn_predictor/constants.py`
- [Main utils](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/src/churn_predictor/utils/main_utils.py): serialization · YAML, pickle, and numpy helpers · `src/churn_predictor/utils/main_utils.py`
- [Logger](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/tree/main/src/churn_predictor/logger): ops support · Central logging facility · `src/churn_predictor/logger`
- [Exception](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/tree/main/src/churn_predictor/exception): ops support · Centralized error handling · `src/churn_predictor/exception`
- [artifacts/](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/tree/main/artifacts): versioned storage · Versioned run outputs including model, preprocessors, logs, and metrics · `artifacts`
- [Churn CSV](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/notebooks/data/Churn_Modelling.csv): raw data · Source dataset for training · `notebooks/data/Churn_Modelling.csv`
- [Component tests](https://github.com/nitin020305/ann-customer-churn-e2e-pipeline/blob/main/tests/test_components.py): tests · Lightweight behavioral tests for pipeline components · `tests/test_components.py`

## Connections

- train.py → Training pipeline: runs · Launches full training workflow
- tune.py → Tuning: runs · Launches tuning workflow
- app.py → Prediction pipeline: uses · Requests inference through the prediction pipeline
- Training pipeline → Ingestion: orders · Executes ingestion first
- Training pipeline → Validation: orders · Validates ingested data
- Training pipeline → Transformation: orders · Transforms features for training
- Training pipeline → Trainer: orders · Trains the ANN model
- Training pipeline → Evaluation: orders · Evaluates trained model
- Prediction pipeline → Transformation: reuses · Applies inference-time preprocessing
- Prediction pipeline → artifacts/: loads latest · Discovers the newest trained artifacts
- Ingestion → Churn CSV: reads · Consumes raw churn dataset
- Ingestion → Artifact entity: emits · Produces split data artifacts
- Validation → Constants: checks · Uses canonical schema and column settings
- Transformation → Constants: maps · Uses shared feature and preprocessing settings
- Trainer → Constants: configures · Uses ANN-related hyperparameters
- Tuning → Constants: searches · Uses tuning parameter space
- Evaluation → artifacts/: writes · Persists metrics and evaluation outputs
- Transformation → Main utils: serializes · Uses shared persistence helpers
- Trainer → artifacts/: writes · Stores model and run outputs
- Training pipeline → Config entity: builds · Constructs stage configuration objects
- Training pipeline → Artifact entity: passes · Threads artifacts between stages
- app.py → Logger: logs · Uses shared logging
- Training pipeline → Exception: handles · Uses centralized exception handling
- Prediction pipeline → Exception: handles · Uses centralized exception handling
- Component tests → Ingestion: covers · Checks component behavior
- Component tests → Transformation: covers · Checks component behavior
- Component tests → Trainer: covers · Checks component behavior