# prabham205/telecom-customer-churn-prediction-and-retention-recommendation architecture

> Architecture diagram of the GitHub repository prabham205/telecom-customer-churn-prediction-and-retention-recommendation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation
- Repository: https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation

## Overview

#### Purpose and entry points
This repository implements telecom customer churn prediction and retention recommendations, with analytical dashboards, an API surface, and an AI retention assistant. Primary runtime entry points are `api/main.py` for the service layer and `app/streamlit_app.py` plus `app/pages/` for the Streamlit interface. Model training is initiated through `scripts/train.py`.

#### Data and feature pipeline
Raw customer data originates at `data/raw/Telco_customer_churn.xlsx`. The data path is organized as load, clean, engineer features, and preprocess:
- `src/data/loader.py`
- `src/data/cleaner.py`
- `src/data/feature_engineering.py`
- `src/preprocessing/pipeline.py`

The fitted preprocessing artifact is persisted at `artifacts/preprocessor.joblib`, creating a boundary between training-time transformations and inference-time inputs.

#### Model training, evaluation, and inference
The training layer supports several model implementations under `src/models/`, including `lightgbm_model.py`, `xgboost_model.py`, `random_forest.py`, `logistic_regression.py`, and `dnn_model.py`. Evaluation is centralized in `src/models/evaluate.py`, with recorded metrics at `models/model_metrics.json`.

Online or application-facing scoring is separated into `src/prediction/predictor.py`. This boundary should consume the persisted preprocessing/model artifacts rather than reproduce training logic.

#### Risk, value, and retention decisioning
Prediction outputs are converted into business actions through distinct domain modules:
- Churn-risk interpretation: `src/risk/risk_engine.py`
- Revenue-at-risk calculation: `src/business/revenue_at_risk.py`
- Customer prioritization: `src/recommendation/priority_engine.py`
- Rule-based retention and offer selection: `src/recommendation/retention_rules.py` and `src/recommendation/offer_engine.py`

This establishes a control flow of customer data → churn prediction → risk/value assessment → prioritized retention recommendation.

#### Generative AI and agent workflow
The AI retention assistant is structured as an agent graph rather than being embedded directly in the dashboard. Its workflow/state boundary is represented by:
- `agent/graph.py`
- `agent/nodes.py`
- `agent/state.py`

Prompt content is isolated in `agent/prompts.py`; LLM access and offer generation are isolated in `genai/llm_client.py` and `genai/offer_generator.py`. This separates deterministic recommendation logic from external LLM-driven assistance.

#### Delivery surfaces and operational concerns
The Streamlit UI exposes executive KPIs, customer-risk views, retention recommendations, AI assistance, and model performance through `app/pages/01_Executive_Dashboard.py` through `app/pages/05_Model_Performance.py`. Reusable visualization and presentation components reside in `app/components/`.

The API request/response boundary is represented by `api/main.py` and `api/schemas.py`. Monitoring is explicitly separated in `src/monitoring/drift_monitor.py`. Deployment infrastructure includes `Dockerfile`; dependencies and environment configuration are defined by `requirements.txt`, `.env.example`, and `config.yaml`.

Main entry points: [`src/prediction/predictor.py`](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/prediction/predictor.py) (Churn predictor), [`api/main.py`](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/api/main.py) (API service), [`src/preprocessing/pipeline.py`](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/preprocessing/pipeline.py) (Preprocessing pipeline), [`src/recommendation/offer_engine.py`](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/recommendation/offer_engine.py) (Offer selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data & ML"]
  node_raw_data[("Telco churn data<br/>source data")]
  node_loader["Data loader<br/>ingestion<br/>[loader.py]"]
  node_cleaner["Data cleaner<br/>transformation<br/>[cleaner.py]"]
  node_features["Feature engineering<br/>transformation"]
  node_preprocessing["Preprocessing pipeline<br/>ML transformation<br/>[pipeline.py]"]
  node_preprocessor_artifact["Fitted preprocessor<br/>ML artifact"]
  node_training["Model training<br/>training job<br/>[train.py]"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
  node_metrics["Model metrics<br/>metrics artifact<br/>[model_metrics.json]"]
  node_predictor["Churn predictor<br/>inference<br/>[predictor.py]"]
end

subgraph group_decisioning["Retention Decisioning"]
  node_risk_engine["Risk interpretation<br/>risk engine<br/>[risk_engine.py]"]
  node_revenue_risk["Revenue at risk<br/>business value<br/>[revenue_at_risk.py]"]
  node_priority["Customer prioritization<br/>decision engine<br/>[priority_engine.py]"]
  node_retention_rules["Retention rules<br/>rule engine<br/>[retention_rules.py]"]
  node_offer_engine["Offer selection<br/>recommendation engine<br/>[offer_engine.py]"]
end

subgraph group_ai["AI Assistant"]
  node_agent_graph{{"Retention agent workflow<br/>agent graph<br/>[graph.py]"}}
  node_agent_nodes["Agent nodes &amp; state<br/>agent workflow<br/>[nodes.py]"]
  node_prompts["Agent prompts<br/>prompt templates<br/>[prompts.py]"]
  node_llm_offers["LLM offer generation<br/>GenAI integration<br/>[offer_generator.py]"]
end

subgraph group_surfaces["Delivery Surfaces"]
  node_api["API service<br/>service interface<br/>[main.py]"]
  node_streamlit["Streamlit dashboards<br/>dashboard UI<br/>[streamlit_app.py]"]
  node_drift_monitor["Drift monitoring<br/>[drift_monitor.py]"]
end

node_raw_data -->|"load"| node_loader
node_loader -->|"clean"| node_cleaner
node_cleaner -->|"engineer"| node_features
node_features -->|"transform"| node_preprocessing
node_preprocessing -->|"persist"| node_preprocessor_artifact
node_preprocessing -->|"training features"| node_training
node_training -->|"evaluate"| node_evaluation
node_evaluation -->|"record"| node_metrics
node_preprocessor_artifact -->|"load"| node_predictor
node_predictor -->|"churn scores"| node_risk_engine
node_risk_engine -->|"risk assessment"| node_revenue_risk
node_revenue_risk -->|"value at risk"| node_priority
node_priority -->|"ranked customers"| node_retention_rules
node_retention_rules -->|"eligible actions"| node_offer_engine
node_offer_engine -->|"deterministic context"| node_agent_graph
node_agent_graph -->|"orchestrate"| node_agent_nodes
node_prompts -->|"instructions"| node_agent_nodes
node_agent_nodes -->|"generate assistance"| node_llm_offers
node_predictor -->|"serve scoring"| node_api
node_offer_engine -->|"serve recommendations"| node_api
node_agent_graph -->|"serve assistant"| node_api
node_api -->|"application data"| node_streamlit
node_metrics -->|"performance views"| node_streamlit
node_predictor -.->|"inference signals"| node_drift_monitor

click node_raw_data "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/data/raw/Telco_customer_churn.xlsx"
click node_loader "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/data/loader.py"
click node_cleaner "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/data/cleaner.py"
click node_features "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/data/feature_engineering.py"
click node_preprocessing "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/preprocessing/pipeline.py"
click node_preprocessor_artifact "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/artifacts/preprocessor.joblib"
click node_training "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/scripts/train.py"
click node_evaluation "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/models/evaluate.py"
click node_metrics "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/models/model_metrics.json"
click node_predictor "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/prediction/predictor.py"
click node_risk_engine "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/risk/risk_engine.py"
click node_revenue_risk "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/business/revenue_at_risk.py"
click node_priority "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/recommendation/priority_engine.py"
click node_retention_rules "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/recommendation/retention_rules.py"
click node_offer_engine "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/recommendation/offer_engine.py"
click node_agent_graph "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/agent/graph.py"
click node_agent_nodes "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/agent/nodes.py"
click node_prompts "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/agent/prompts.py"
click node_llm_offers "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/genai/offer_generator.py"
click node_api "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/api/main.py"
click node_streamlit "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/app/streamlit_app.py"
click node_drift_monitor "https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/monitoring/drift_monitor.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_raw_data,node_loader,node_cleaner,node_features,node_preprocessing,node_preprocessor_artifact,node_training,node_evaluation,node_metrics,node_predictor toneBlue
class node_risk_engine,node_revenue_risk,node_priority,node_retention_rules,node_offer_engine toneAmber
class node_agent_graph,node_agent_nodes,node_prompts,node_llm_offers toneMint
class node_api,node_streamlit,node_drift_monitor toneRose
```

## Components

### Data & ML

- [Telco churn data](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/data/raw/Telco_customer_churn.xlsx): source data · `data/raw/Telco_customer_churn.xlsx`
- [Data loader](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/data/loader.py): ingestion · `src/data/loader.py`
- [Data cleaner](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/data/cleaner.py): transformation · `src/data/cleaner.py`
- [Feature engineering](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/data/feature_engineering.py): transformation · `src/data/feature_engineering.py`
- [Preprocessing pipeline](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/preprocessing/pipeline.py): ML transformation · `src/preprocessing/pipeline.py`
- [Fitted preprocessor](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/artifacts/preprocessor.joblib): ML artifact · Shared training and inference transformation contract. · `artifacts/preprocessor.joblib`
- [Model training](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/scripts/train.py): training job · Trains supported LightGBM, XGBoost, random forest, logistic, and DNN models. · `scripts/train.py`
- [Model evaluation](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/models/evaluate.py): evaluation · `src/models/evaluate.py`
- [Model metrics](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/models/model_metrics.json): metrics artifact · `models/model_metrics.json`
- [Churn predictor](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/prediction/predictor.py): inference · Scores customers using persisted preprocessing and model artifacts. · `src/prediction/predictor.py`

### Retention Decisioning

- [Risk interpretation](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/risk/risk_engine.py): risk engine · `src/risk/risk_engine.py`
- [Revenue at risk](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/business/revenue_at_risk.py): business value · `src/business/revenue_at_risk.py`
- [Customer prioritization](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/recommendation/priority_engine.py): decision engine · `src/recommendation/priority_engine.py`
- [Retention rules](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/recommendation/retention_rules.py): rule engine · `src/recommendation/retention_rules.py`
- [Offer selection](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/recommendation/offer_engine.py): recommendation engine · `src/recommendation/offer_engine.py`

### AI Assistant

- [Retention agent workflow](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/agent/graph.py): agent graph · Stateful orchestration for AI retention assistance. · `agent/graph.py`
- [Agent nodes & state](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/agent/nodes.py): agent workflow · `agent/nodes.py`
- [Agent prompts](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/agent/prompts.py): prompt templates · `agent/prompts.py`
- [LLM offer generation](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/genai/offer_generator.py): GenAI integration · `genai/offer_generator.py`

### Delivery Surfaces

- [API service](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/api/main.py): service interface · Request and response contracts are defined in api/schemas.py. · `api/main.py`
- [Streamlit dashboards](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/app/streamlit_app.py): dashboard UI · Executive, risk, recommendation, AI, and model-performance views. · `app/streamlit_app.py`
- [Drift monitoring](https://github.com/prabham205/telecom-customer-churn-prediction-and-retention-recommendation/blob/main/src/monitoring/drift_monitor.py): monitoring · `src/monitoring/drift_monitor.py`

## Connections

- Telco churn data → Data loader: load
- Data loader → Data cleaner: clean
- Data cleaner → Feature engineering: engineer
- Feature engineering → Preprocessing pipeline: transform
- Preprocessing pipeline → Fitted preprocessor: persist
- Preprocessing pipeline → Model training: training features
- Model training → Model evaluation: evaluate
- Model evaluation → Model metrics: record
- Fitted preprocessor → Churn predictor: load
- Churn predictor → Risk interpretation: churn scores
- Risk interpretation → Revenue at risk: risk assessment
- Revenue at risk → Customer prioritization: value at risk
- Customer prioritization → Retention rules: ranked customers
- Retention rules → Offer selection: eligible actions
- Offer selection → Retention agent workflow: deterministic context
- Retention agent workflow → Agent nodes & state: orchestrate
- Agent prompts → Agent nodes & state: instructions
- Agent nodes & state → LLM offer generation: generate assistance
- Churn predictor → API service: serve scoring
- Offer selection → API service: serve recommendations
- Retention agent workflow → API service: serve assistant
- API service → Streamlit dashboards: application data
- Model metrics → Streamlit dashboards: performance views
- Churn predictor → Drift monitoring: inference signals