How akshatsinghnayal/customer-churn-prediction works
1. What this repo is
- ChurnSight is a two-part system: an offline ML training pipeline and an online dashboard/API for customer churn risk scoring and analytics.
- The repo is organized around a clear split between model production (backend/pipeline, backend/artifacts) and model consumption (backend/main.py, backend/services, src/app).
2. Backend serving layer
- The backend is a FastAPI application started from backend/main.py.
- Its job is to expose prediction/analytics data to the frontend, while hiding the model details behind service modules.
- The backend is not just a generic API; it is acting as the runtime facade over trained ML assets stored on disk.
3. Backend service boundaries
- backend/services/data_service.py is the data-access/aggregation boundary for customer and dataset-derived information.
- backend/services/model_service.py is the model inference boundary: loading trained models, scalers, and feature metadata to score churn risk.
- backend/services/alert_service.py is the business-rule boundary for churn alerts, turning model outputs into actionable notifications.
4. ML pipeline boundary
- backend/pipeline/preprocess.py contains the feature engineering and cleaning logic used before training.
- backend/pipeline/train.py performs model training, hyperparameter tuning, threshold selection, and ensembling.
- This pipeline is separate from serving code, which is important architecturally: the runtime backend appears to consume precomputed artifacts rather than retraining on every request.
5. Feature engineering and preprocessing flow
- The pipeline works from the Telco churn dataset stored at the repo root.
- Preprocessing includes numeric cleaning (TotalCharges handling), categorical normalization, engineered risk features, binning, one-hot encoding, and scaling.
- These transformations are serialized so that the serving layer can apply the same schema consistently at inference time.
6. Model training and selection
- The training flow produces multiple candidate models: Logistic Regression, Random Forest, XGBoost, and a soft-voting ensemble.
- Models are tuned with cross-validated grid search and then threshold-optimized for F1 rather than using a fixed 0.5 cutoff.
- This means the serving layer needs to carry not just model weights, but also the chosen decision threshold for each model.
7. Artifact contract between training and serving
- backend/artifacts is the key integration boundary in the repo.
- It contains serialized models, scaler, train/test splits, feature names, metrics, predictions, alerts, and other derived files.
- The backend runtime likely reads these artifacts directly, so the filesystem here functions like a lightweight model registry and data cache.
8. Frontend application structure
- The frontend is a React + Vite + TypeScript app under src/app.
- src/app/routes.ts and the page files define a multi-screen dashboard experience: landing, dashboard, analytics, customers, predictions, models, alerts, profile, settings, login, register, and 404.
- The frontend is organized by route/page, not by a single monolithic dashboard screen.
9. Frontend data access
- src/app/services/api.ts is the main client-side boundary for talking to the FastAPI backend.
- UI pages should be treated as consumers of backend endpoints rather than as holders of business logic.
- That keeps the frontend focused on presentation, filtering, and navigation while the backend owns scoring and aggregation.
10. UI composition and shared layout
- AppLayout, Sidebar, and TopNav define the primary shell of the application.
- Shared UI primitives under src/app/components/ui indicate a component-library-driven design system, likely based on shadcn-style building blocks.
- ThemeContext.tsx plus accent/appearance switchers show that theming is a first-class frontend concern.
11. Presentation/data boundary
- The dashboard pages likely render backend-derived tables, charts, and alerts rather than raw ML internals.
- The separation is: backend computes and stores predictions/metrics, frontend presents them as operational views.
- Pages like Customers, Predictions, Models, and Alerts map cleanly to the backend’s data/model/alert services.
12. Operational view of the system
- In production terms, the repo represents a single-user-facing analytics application with an ML inference backend and a browser UI.
- The machine-learning lifecycle is offline and file-based; the operational lifecycle is request/response through FastAPI.
- There is no sign of a separate database or message broker; the main persistence layer is the artifact directory plus the source dataset.
13. Tooling and build stack
- Backend runtime: Python + FastAPI, with model training support from common ML libraries implied by the README.
- Frontend runtime: React, TypeScript, Vite, Tailwind/PostCSS, and a custom theme CSS layer.
- The architecture is therefore a classic Python ML backend + modern React dashboard split, connected through a thin API surface.
Main entry points: artifacts Artifacts · main.py API server · train.py Train models · App.tsx App shell
Components 18
Backend
FastAPI runtime plus offline ML pipeline and persisted artifacts.
- API server · Entry point for the online backend runtime.
backend/main.py - Data service · Aggregates customer and dataset-derived views for the API.
backend/services/data_service.py - Model service · Loads trained models, scaler, features, and thresholds for churn scoring.
backend/services/model_service.py - Alert service · Applies business rules to model outputs to produce churn alerts.
backend/services/alert_service.py - Preprocess · Cleans data, engineers features, encodes categories, and scales inputs.
backend/pipeline/preprocess.py - Train models · Trains, tunes, thresholds, and ensembles churn models.
backend/pipeline/train.py - Pipeline utils · Shared training and preprocessing utilities.
backend/pipeline/utils.py - Artifacts · Serialized models, scalers, splits, metrics, predictions, and alerts consumed by runtime code.
backend/artifacts - Model bundle · Saved candidate estimators including logistic regression, random forest, XGBoost, and voting ensemble.
backend/artifacts/models.pkl
Frontend
React dashboard shell, pages, and API client.
- App shell · Client application bootstrap and top-level composition.
src/app/App.tsx - Routes · Maps the dashboard screens and auth pages.
src/app/routes.ts - Layout · Primary UI frame with sidebar and top navigation.
src/app/components/layout/AppLayout.tsx - Theme · Controls appearance and accent selection.
src/app/context/ThemeContext.tsx - API client · Frontend boundary for calling the FastAPI backend.
src/app/services/api.ts - Dashboard pages · Operational screens for overview, analytics, customers, predictions, models, alerts, profile, settings, and auth.
src/app/pages/Dashboard.tsx - UI kit · Shared component library used across pages and shell.
src/app/components/ui/button.tsx
Shared assets
Repository-level data and theme/style resources used across the app.
- Telco data · Source churn dataset used by the offline pipeline.
WA_Fn-UseC_-Telco-Customer-Churn.csv - Theme styles · Global and theme styling for the frontend.
src/styles/theme.css
Connections 20
- API server → Data service: uses · API routes delegate customer and analytics queries.
- API server → Model service: uses · API routes invoke scoring and model metadata access.
- API server → Alert service: uses · API routes expose alert generation and alert views.
- Data service → Artifacts: reads · Loads derived customer, prediction, and metric artifacts.
- Model service → Artifacts: reads · Consumes trained model assets, scaler, features, and thresholds.
- Model service → Model bundle: loads · Retrieves the serialized candidate models.
- Alert service → Artifacts: reads · Uses persisted alert and prediction outputs.
- Preprocess → Telco data: ingests · Builds the training dataset from the raw Telco CSV.
- Train models → Preprocess: depends on · Training uses the preprocessing and feature engineering contract.
- Train models → Pipeline utils: uses · Shares helper logic for training and evaluation.
- Train models → Artifacts: writes · Produces models, metrics, splits, predictions, and alerts.
- Preprocess → Artifacts: writes · Persists preprocessed data and feature metadata for serving.
- App shell → Routes: uses · App composition is driven by route definitions.
- App shell → Layout: uses · Renders the shared application shell.
- App shell → Theme: uses · Wraps the UI in theming context.
- Dashboard pages → API client: calls · Dashboard screens fetch backend data through the client boundary.
- Dashboard pages → UI kit: composes · Screens are built from shared UI primitives.
- Layout → UI kit: composes · Sidebar, top nav, and shell rely on shared primitives.
- Theme → Theme styles: applies · Theme context works with the global style layer.
- API client → API server: requests · Frontend communicates with the FastAPI backend.