# syedmuhammadubaidurrehman22/customer_churn_prediction architecture

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

- Interactive diagram: https://gitdiagram.com/syedmuhammadubaidurrehman22/customer_churn_prediction
- Repository: https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction

## Overview

Customer Churn Analytics turns a Telco snapshot into validated MySQL tables, trains and registers an explicitly unapproved XGBoost benchmark, scores the snapshot, and analyzes business scenarios. The principal workflow is CSV ingestion → raw data → versioned labels and features → benchmark training → optional registration → explicit benchmark scoring → predictions and business validation. Training, scoring, and validation are distinct downstream capabilities, not one automatic pipeline. The README and excerpts support the main data flow; unsampled SQL and module internals are represented only where documented, with evidence limits reflected in the edges.

Main entry points: [`src/utils.py`](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/utils.py) (Database engine helper), [`src/business_validation.py`](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/business_validation.py) (Scenario analysis), [`src/train.py`](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/train.py) (Train benchmark), [`src/score.py`](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/score.py) (Benchmark scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Ingestion"]
  node_pipeline["Pipeline runner<br/>[run_pipeline.py]"]
  node_ingest["Validate and ingest<br/>[ingest.py]"]
end

subgraph group_data["Snapshot data"]
  node_raw[("Raw customers")]
  node_labels["Snapshot labels<br/>[labels.py]"]
  node_labelstore[("Label table")]
  node_features["Feature materializer<br/>[features.py]"]
  node_featurestore[("Feature table")]
end

subgraph group_model["Benchmark modeling"]
  node_trainer["Train benchmark<br/>[train.py]"]
  node_artifacts["Model artifacts<br/>[train.py]"]
  node_registry[("Model registry")]
  node_registrycode["Register and load<br/>[registry.py]"]
end

subgraph group_scoring["Scoring"]
  node_scorer["Benchmark scoring<br/>[score.py]"]
  node_predictions[("Prediction table")]
end

subgraph group_validation["Business validation"]
  node_business["Scenario analysis"]
  node_validationstore[("Validation records")]
end

subgraph group_shared["Shared infrastructure"]
  node_config["Stage configuration<br/>[config.py]"]
  node_dbhelper["Database engine helper<br/>[utils.py]"]
end

node_csv["Telco CSV"]
node_mysql[("MySQL")]

node_csv -->|"loads and validates"| node_ingest
node_pipeline -->|"runs"| node_ingest
node_pipeline -->|"runs"| node_labels
node_pipeline -->|"runs"| node_features
node_ingest -->|"replaces rows"| node_raw
node_labels -->|"reads outcome"| node_raw
node_labels -->|"materializes labels"| node_labelstore
node_features -->|"reads attributes"| node_raw
node_features -->|"materializes features"| node_featurestore
node_trainer -->|"reads features"| node_featurestore
node_trainer -->|"reads labels"| node_labelstore
node_trainer -->|"writes model and report"| node_artifacts
node_trainer -->|"optionally registers"| node_registrycode
node_registrycode -->|"validates and loads"| node_artifacts
node_registrycode -->|"registers metadata"| node_registry
node_scorer -->|"selects model"| node_registry
node_scorer -->|"loads artifacts"| node_registrycode
node_scorer -->|"reads snapshot"| node_featurestore
node_scorer -->|"writes scores"| node_predictions
node_business -->|"reads model metadata"| node_registry
node_business -->|"reads benchmark scores"| node_predictions
node_business -->|"checks feature snapshot"| node_featurestore
node_business -->|"joins labels"| node_labelstore
node_business -->|"optionally saves scenarios"| node_validationstore
node_ingest -->|"gets engine"| node_dbhelper
node_labels -->|"gets engine"| node_dbhelper
node_features -->|"gets engine"| node_dbhelper
node_trainer -->|"gets engine"| node_dbhelper
node_registrycode -->|"gets engine"| node_dbhelper
node_scorer -->|"gets engine"| node_dbhelper
node_business -->|"gets engine"| node_dbhelper
node_dbhelper -->|"reads connection settings"| node_config

click node_csv "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/data/raw/WA_Fn-UseC_-Telco-Customer-Churn.csv"
click node_pipeline "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/run_pipeline.py"
click node_ingest "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/ingest.py"
click node_raw "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/01_create_tables.sql"
click node_labels "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/labels.py"
click node_labelstore "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/02_create_labels.sql"
click node_features "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/features.py"
click node_featurestore "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/03_create_feature_store.sql"
click node_trainer "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/train.py"
click node_artifacts "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/train.py"
click node_registry "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/04_create_model_registry.sql"
click node_registrycode "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/registry.py"
click node_scorer "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/score.py"
click node_predictions "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/05_create_model_predictions.sql"
click node_business "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/business_validation.py"
click node_validationstore "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/06_create_business_validation.sql"
click node_config "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/config.py"
click node_dbhelper "https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/utils.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_pipeline,node_ingest toneBlue
class node_raw,node_labels,node_labelstore,node_features,node_featurestore,node_mysql toneAmber
class node_trainer,node_artifacts,node_registry,node_registrycode toneMint
class node_scorer,node_predictions toneRose
class node_business,node_validationstore toneIndigo
class node_config,node_dbhelper,node_csv toneTeal
```

## Components

### Ingestion

- [Pipeline runner](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/run_pipeline.py): `run_pipeline.py`
- [Validate and ingest](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/ingest.py): `src/ingest.py`

### Snapshot data

- [Raw customers](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/01_create_tables.sql): `sql/01_create_tables.sql`
- [Snapshot labels](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/labels.py): `src/labels.py`
- [Label table](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/02_create_labels.sql): `sql/02_create_labels.sql`
- [Feature materializer](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/features.py): `src/features.py`
- [Feature table](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/03_create_feature_store.sql): `sql/03_create_feature_store.sql`

### Benchmark modeling

- [Train benchmark](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/train.py): `src/train.py`
- [Model artifacts](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/train.py): `src/train.py`
- [Model registry](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/04_create_model_registry.sql): `sql/04_create_model_registry.sql`
- [Register and load](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/registry.py): `src/registry.py`

### Scoring

- [Benchmark scoring](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/score.py): `src/score.py`
- [Prediction table](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/05_create_model_predictions.sql): `sql/05_create_model_predictions.sql`

### Business validation

- [Scenario analysis](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/business_validation.py): `src/business_validation.py`
- [Validation records](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/sql/06_create_business_validation.sql): `sql/06_create_business_validation.sql`

### Shared infrastructure

- [Stage configuration](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/config.py): `src/config.py`
- [Database engine helper](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/src/utils.py): `src/utils.py`

### Other components

- [Telco CSV](https://github.com/syedmuhammadubaidurrehman22/customer_churn_prediction/blob/main/data/raw/WA_Fn-UseC_-Telco-Customer-Churn.csv): `data/raw/WA_Fn-UseC_-Telco-Customer-Churn.csv`
- **MySQL**

## Connections

- Telco CSV → Validate and ingest: loads and validates (evidence: `src/ingest.py`)
- Pipeline runner → Validate and ingest: runs (evidence: `run_pipeline.py`)
- Pipeline runner → Snapshot labels: runs (evidence: `run_pipeline.py`)
- Pipeline runner → Feature materializer: runs (evidence: `run_pipeline.py`)
- Validate and ingest → Raw customers: replaces rows (evidence: `src/ingest.py`)
- Snapshot labels → Raw customers: reads outcome (evidence: `README.md`)
- Snapshot labels → Label table: materializes labels (evidence: `src/labels.py`)
- Feature materializer → Raw customers: reads attributes (evidence: `src/features.py`)
- Feature materializer → Feature table: materializes features (evidence: `src/features.py`)
- Train benchmark → Feature table: reads features (evidence: `src/train.py`)
- Train benchmark → Label table: reads labels (evidence: `src/train.py`)
- Train benchmark → Model artifacts: writes model and report (evidence: `src/train.py`)
- Train benchmark → Register and load: optionally registers (evidence: `src/train.py`)
- Register and load → Model artifacts: validates and loads (evidence: `src/registry.py`)
- Register and load → Model registry: registers metadata (evidence: `src/registry.py`)
- Benchmark scoring → Model registry: selects model (evidence: `src/score.py`)
- Benchmark scoring → Register and load: loads artifacts (evidence: `src/score.py`)
- Benchmark scoring → Feature table: reads snapshot (evidence: `src/score.py`)
- Benchmark scoring → Prediction table: writes scores (evidence: `src/score.py`)
- Scenario analysis → Model registry: reads model metadata (evidence: `src/business_validation.py`)
- Scenario analysis → Prediction table: reads benchmark scores (evidence: `src/business_validation.py`)
- Scenario analysis → Feature table: checks feature snapshot (evidence: `src/business_validation.py`)
- Scenario analysis → Label table: joins labels (evidence: `src/business_validation.py`)
- Scenario analysis → Validation records: optionally saves scenarios (evidence: `src/business_validation.py`)
- Validate and ingest → Database engine helper: gets engine (evidence: `src/ingest.py`)
- Snapshot labels → Database engine helper: gets engine (evidence: `src/labels.py`)
- Feature materializer → Database engine helper: gets engine (evidence: `src/features.py`)
- Train benchmark → Database engine helper: gets engine (evidence: `src/train.py`)
- Register and load → Database engine helper: gets engine (evidence: `src/registry.py`)
- Benchmark scoring → Database engine helper: gets engine (evidence: `src/score.py`)
- Scenario analysis → Database engine helper: gets engine (evidence: `src/business_validation.py`)
- Database engine helper → Stage configuration: reads connection settings (evidence: `src/utils.py`)
