# yousra-khallou/ai-telecom-customer-retention-system architecture

> Architecture diagram of the GitHub repository yousra-khallou/ai-telecom-customer-retention-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yousra-khallou/ai-telecom-customer-retention-system
- Repository: https://github.com/yousra-khallou/ai-telecom-customer-retention-system

## Overview

1. **Overall shape**
   - This repo is a three-part retention system: **offline model development**, **online inference APIs**, and a **React dashboard**.
   - The core architectural boundary is between the notebook/data layer that produces trained artifacts, and the runtime layer that only loads those artifacts for prediction.

2. **Offline data and training assets**
   - `Data/raw/Telco-Customer-Churn.csv` is the source customer dataset.
   - `Data/processed/telco_clean.csv` is the cleaned version used by the notebooks.
   - `Notebooks/01_...04_*.ipynb` represent the analysis and training pipeline: exploration, churn modeling, sentiment modeling, and recommendation modeling.
   - These notebooks are the place where feature engineering, model selection, and evaluation happen; the deployed services do not retrain models.

3. **Churn prediction subsystem**
   - The churn model was trained in Notebook 02 and serialized into `api-render/models/churn_model.pkl`.
   - `api-render/models/best_threshold.pkl` stores the decision threshold used to turn churn probabilities into a risk classification.
   - Architecturally, this is a classic tabular ML service: customer attributes in, churn probability and risk level out.

4. **Recommendation subsystem**
   - The recommender is a collaborative-filtering layer built from SVD artifacts under `api-render/models/recommandations/`.
   - Key runtime assets include factor matrices (`U.npy`, `Vt.npy`, `sigma.pkl`), predicted ratings, service matrices, and lookup maps such as `service_to_idx.pkl` and `services_list.pkl`.
   - This subsystem is data-driven and precomputed: it uses stored latent factors and service metadata rather than training online.

5. **Sentiment analysis subsystem**
   - The README describes a separate HuggingFace-hosted sentiment service based on `distilbert-base-multilingual-cased`.
   - That service is not present in the visible tree, but it is still part of the documented system boundary.
   - It accepts free-text customer reviews and returns sentiment class plus confidence, which the dashboard can use independently of churn/recommendation.

6. **Serving layer: `api-render`**
   - `api-render/main.py` is the runtime API for churn prediction and recommendations.
   - It loads the serialized churn model, threshold, and recommendation artifacts at startup, then serves inference endpoints.
   - This layer is the bridge between the frontend and the machine-learning assets.

7. **Frontend layer: `frontend/`**
   - The UI is a React 18 app composed of three feature forms: `ChurnForm`, `SentimentForm`, and `RecoForm`.
   - `App.js` assembles these into one dashboard experience.
   - The frontend is a thin orchestration layer: it collects user input, calls the relevant API service(s), and displays results.

8. **End-to-end data flow**
   - **Tabular customer data** goes from the dashboard to the churn API, which returns churn risk.
   - **Review text** goes from the dashboard to the sentiment service, which returns polarity and confidence.
   - **Churn + sentiment + collaborative signals** feed the recommendation engine, which outputs prioritized retention offers.
   - The system is therefore a hybrid decision pipeline, not three isolated demos.

9. **Deployment and external boundaries**
   - The README shows the frontend deployed on **Vercel** and the Python services deployed on **HuggingFace Spaces**.
   - Security controls called out in the README—API key checking, CORS restriction, and rate limiting—sit at the API boundary, protecting the inference services from unrestricted browser or public access.

10. **What to draw in an architecture diagram**
   - Show one offline box for **data + notebooks + model training**, producing model artifacts.
   - Show one online box for **FastAPI serving** that consumes those artifacts.
   - Show a separate **sentiment service** boundary, since it is logically independent from the churn/recommendation API.
   - Put the **React dashboard** at the edge, with arrows to the APIs, and make the trained model files part of the backend runtime dependencies rather than separate services.

Main entry points: [`api-render/main.py`](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/main.py) (API server), [`Data/processed/telco_clean.csv`](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Data/processed/telco_clean.csv) (Clean data), [`Notebooks/04_recommendation.ipynb`](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Notebooks/04_recommendation.ipynb) (Recommender), [`frontend/src/App.js`](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/frontend/src/App.js) (Dashboard shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline development"]
  node_raw_data["Raw data<br/>dataset"]
  node_clean_data["Clean data<br/>dataset<br/>[telco_clean.csv]"]
  node_notebooks_explore["Exploration<br/>notebook"]
  node_notebooks_churn["Churn model<br/>notebook"]
  node_notebooks_sentiment["Sentiment NLP<br/>notebook"]
  node_notebooks_reco["Recommender<br/>notebook"]
end

subgraph group_runtime["Online serving"]
  node_churn_model[("Churn model<br/>pkl artifact<br/>[churn_model.pkl]")]
  node_churn_threshold[("Risk threshold<br/>pkl artifact<br/>[best_threshold.pkl]")]
  node_api_main["API server<br/>FastAPI app<br/>[main.py]"]
  node_reco_factors[("Latent factors<br/>SVD artifacts<br/>[U.npy]")]
  node_reco_sigma[("Singular values<br/>SVD artifact<br/>[sigma.pkl]")]
  node_reco_catalog[("Service maps<br/>lookup artifacts<br/>[service_to_idx.pkl]")]
  node_reco_engine["Reco engine<br/>ranking logic<br/>[main.py]"]
end

subgraph group_frontend["Dashboard"]
  node_churn_form["Churn form<br/>React component<br/>[ChurnForm.js]"]
  node_sentiment_form["Sentiment form<br/>React component<br/>[SentimentForm.js]"]
  node_reco_form["Reco form<br/>React component<br/>[RecoForm.js]"]
  node_app_shell["Dashboard shell<br/>React app<br/>[App.js]"]
end

subgraph group_external["External services"]
  node_sentiment_service["Sentiment API<br/>hosted ML service"]
end

node_raw_data -->|"cleaned into"| node_clean_data
node_clean_data -->|"analyzed in"| node_notebooks_explore
node_clean_data -->|"trained from"| node_notebooks_churn
node_clean_data -->|"modeled in"| node_notebooks_reco
node_notebooks_churn -->|"exports"| node_churn_model
node_notebooks_churn -->|"exports"| node_churn_threshold
node_notebooks_reco -->|"exports"| node_reco_factors
node_notebooks_reco -->|"exports"| node_reco_sigma
node_notebooks_reco -->|"exports"| node_reco_catalog
node_churn_model -->|"loaded by"| node_api_main
node_churn_threshold -->|"loaded by"| node_api_main
node_reco_factors -->|"drives"| node_reco_engine
node_reco_sigma -->|"drives"| node_reco_engine
node_reco_catalog -->|"drives"| node_reco_engine
node_reco_engine -->|"exposed by"| node_api_main
node_app_shell -->|"assembles"| node_churn_form
node_app_shell -->|"assembles"| node_sentiment_form
node_app_shell -->|"assembles"| node_reco_form
node_churn_form -->|"calls"| node_api_main
node_reco_form -->|"calls"| node_api_main
node_sentiment_form -->|"calls"| node_sentiment_service

click node_raw_data "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Data/raw/Telco-Customer-Churn.csv"
click node_clean_data "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Data/processed/telco_clean.csv"
click node_notebooks_explore "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Notebooks/01_exploration.ipynb"
click node_notebooks_churn "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Notebooks/02_churn_model.ipynb"
click node_notebooks_sentiment "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Notebooks/03_nlp_distilbert.ipynb"
click node_notebooks_reco "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Notebooks/04_recommendation.ipynb"
click node_churn_model "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/churn_model.pkl"
click node_churn_threshold "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/best_threshold.pkl"
click node_api_main "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/main.py"
click node_reco_factors "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/recommandations/U.npy"
click node_reco_sigma "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/recommandations/sigma.pkl"
click node_reco_catalog "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/recommandations/service_to_idx.pkl"
click node_reco_engine "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/main.py"
click node_churn_form "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/frontend/src/components/ChurnForm.js"
click node_sentiment_form "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/frontend/src/components/SentimentForm.js"
click node_reco_form "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/frontend/src/components/RecoForm.js"
click node_app_shell "https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/frontend/src/App.js"

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_clean_data,node_notebooks_explore,node_notebooks_churn,node_notebooks_sentiment,node_notebooks_reco toneBlue
class node_churn_model,node_churn_threshold,node_api_main,node_reco_factors,node_reco_sigma,node_reco_catalog,node_reco_engine toneAmber
class node_churn_form,node_sentiment_form,node_reco_form,node_app_shell toneMint
class node_sentiment_service toneRose
```

## Components

### Offline development

Data preparation, notebooks, and training artifacts produced before deployment.

- [Raw data](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Data/raw/Telco-Customer-Churn.csv): dataset · Source telco churn CSV used for offline exploration and model development. · `Data/raw/Telco-Customer-Churn.csv`
- [Clean data](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Data/processed/telco_clean.csv): dataset · Processed dataset used by notebooks after cleaning and feature preparation. · `Data/processed/telco_clean.csv`
- [Exploration](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Notebooks/01_exploration.ipynb): notebook · Initial analysis and data understanding workflow. · `Notebooks/01_exploration.ipynb`
- [Churn model](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Notebooks/02_churn_model.ipynb): notebook · Tabular churn modeling, evaluation, and artifact creation. · `Notebooks/02_churn_model.ipynb`
- [Sentiment NLP](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Notebooks/03_nlp_distilbert.ipynb): notebook · Text sentiment modeling workflow based on a transformer model. · `Notebooks/03_nlp_distilbert.ipynb`
- [Recommender](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/Notebooks/04_recommendation.ipynb): notebook · Collaborative-filtering and recommendation modeling workflow. · `Notebooks/04_recommendation.ipynb`

### Online serving

Python inference services that load pretrained artifacts and answer requests.

- [Churn model](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/churn_model.pkl): pkl artifact · Serialized churn classifier loaded by the serving layer. · `api-render/models/churn_model.pkl`
- [Risk threshold](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/best_threshold.pkl): pkl artifact · Decision threshold used to convert churn probability into risk class. · `api-render/models/best_threshold.pkl`
- [API server](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/main.py): FastAPI app · Main runtime service for churn prediction and recommendation inference. · `api-render/main.py`
- [Latent factors](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/recommandations/U.npy): SVD artifacts · Matrix factorization outputs used to score service recommendations. · `api-render/models/recommandations/U.npy`
- [Singular values](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/recommandations/sigma.pkl): SVD artifact · Stored singular values for the recommendation model. · `api-render/models/recommandations/sigma.pkl`
- [Service maps](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/models/recommandations/service_to_idx.pkl): lookup artifacts · Service indices, lists, popularity, and rating matrices for recommendation ranking. · `api-render/models/recommandations/service_to_idx.pkl`
- [Reco engine](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/api-render/main.py): ranking logic · Collaborative-filtering runtime that turns latent factors and lookups into ranked offers. · `api-render/main.py`

### Dashboard

React UI that gathers user inputs and orchestrates calls to the backend services.

- [Churn form](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/frontend/src/components/ChurnForm.js): React component · Frontend form for customer attributes used for churn scoring. · `frontend/src/components/ChurnForm.js`
- [Sentiment form](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/frontend/src/components/SentimentForm.js): React component · Frontend form for review text sent to sentiment analysis. · `frontend/src/components/SentimentForm.js`
- [Reco form](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/frontend/src/components/RecoForm.js): React component · Frontend form that gathers inputs for recommendation generation. · `frontend/src/components/RecoForm.js`
- [Dashboard shell](https://github.com/yousra-khallou/ai-telecom-customer-retention-system/blob/main/frontend/src/App.js): React app · Top-level React composition that assembles the retention dashboard. · `frontend/src/App.js`

### External services

Documented runtime dependencies outside the repository boundary.

- **Sentiment API**: hosted ML service · Documented external HuggingFace sentiment inference service based on DistilBERT.

## Connections

- Raw data → Clean data: cleaned into · Raw CSV is transformed into the processed dataset used downstream.
- Clean data → Exploration: analyzed in · Processed data supports exploratory analysis.
- Clean data → Churn model: trained from · Churn notebook uses cleaned tabular data for feature engineering and model training.
- Clean data → Recommender: modeled in · Recommendation notebook uses prepared data for collaborative filtering.
- Churn model → Churn model: exports · Offline churn training produces the serialized model artifact.
- Churn model → Risk threshold: exports · Offline training also produces the operating threshold artifact.
- Recommender → Latent factors: exports · Recommendation training materializes factor matrices.
- Recommender → Singular values: exports · Recommendation training materializes singular values.
- Recommender → Service maps: exports · Recommendation training materializes lookup and ranking assets.
- Churn model → API server: loaded by · Serving layer loads the churn classifier at startup.
- Risk threshold → API server: loaded by · Serving layer uses the threshold when classifying risk.
- Latent factors → Reco engine: drives · Latent factors are used by the ranking logic.
- Singular values → Reco engine: drives · Singular values are part of the scoring pipeline.
- Service maps → Reco engine: drives · Catalog and lookup artifacts support ranking and decoding outputs.
- Reco engine → API server: exposed by · Recommendation logic is served through the main API.
- Dashboard shell → Churn form: assembles · Dashboard shell composes the churn input form.
- Dashboard shell → Sentiment form: assembles · Dashboard shell composes the sentiment form.
- Dashboard shell → Reco form: assembles · Dashboard shell composes the recommendation form.
- Churn form → API server: calls · Frontend sends customer attributes to the churn API.
- Reco form → API server: calls · Frontend requests recommendations from the runtime API.
- Sentiment form → Sentiment API: calls · Frontend sends review text to the hosted sentiment service.
