How yousra-khallou/ai-telecom-customer-retention-system works
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: main.py API server · telco_clean.csv Clean data · 04_recommendation.ipynb Recommender · App.js Dashboard shell
Components 18
Offline development
Data preparation, notebooks, and training artifacts produced before deployment.
- Raw data · Source telco churn CSV used for offline exploration and model development.
Data/raw/Telco-Customer-Churn.csv - Clean data · Processed dataset used by notebooks after cleaning and feature preparation.
Data/processed/telco_clean.csv - Exploration · Initial analysis and data understanding workflow.
Notebooks/01_exploration.ipynb - Churn model · Tabular churn modeling, evaluation, and artifact creation.
Notebooks/02_churn_model.ipynb - Sentiment NLP · Text sentiment modeling workflow based on a transformer model.
Notebooks/03_nlp_distilbert.ipynb - Recommender · Collaborative-filtering and recommendation modeling workflow.
Notebooks/04_recommendation.ipynb
Online serving
Python inference services that load pretrained artifacts and answer requests.
- Churn model · Serialized churn classifier loaded by the serving layer.
api-render/models/churn_model.pkl - Risk threshold · Decision threshold used to convert churn probability into risk class.
api-render/models/best_threshold.pkl - API server · Main runtime service for churn prediction and recommendation inference.
api-render/main.py - Latent factors · Matrix factorization outputs used to score service recommendations.
api-render/models/recommandations/U.npy - Singular values · Stored singular values for the recommendation model.
api-render/models/recommandations/sigma.pkl - Service maps · Service indices, lists, popularity, and rating matrices for recommendation ranking.
api-render/models/recommandations/service_to_idx.pkl - Reco engine · 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 · Frontend form for customer attributes used for churn scoring.
frontend/src/components/ChurnForm.js - Sentiment form · Frontend form for review text sent to sentiment analysis.
frontend/src/components/SentimentForm.js - Reco form · Frontend form that gathers inputs for recommendation generation.
frontend/src/components/RecoForm.js - Dashboard shell · Top-level React composition that assembles the retention dashboard.
frontend/src/App.js
External services
Documented runtime dependencies outside the repository boundary.
- Sentiment API · Documented external HuggingFace sentiment inference service based on DistilBERT.
Connections 21
- 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.