# akshatsinghnayal/customer-churn-prediction architecture

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

- Interactive diagram: https://gitdiagram.com/akshatsinghnayal/customer-churn-prediction
- Repository: https://github.com/akshatsinghnayal/customer-churn-prediction

## Overview

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: [`backend/artifacts`](https://github.com/akshatsinghnayal/customer-churn-prediction/tree/main/backend/artifacts) (Artifacts), [`backend/main.py`](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/main.py) (API server), [`backend/pipeline/train.py`](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/pipeline/train.py) (Train models), [`src/app/App.tsx`](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_backend["Backend"]
  node_n_main["API server<br/>FastAPI app<br/>[main.py]"]
  node_n_data_service["Data service<br/>[data_service.py]"]
  node_n_model_service["Model service<br/>[model_service.py]"]
  node_n_alert_service["Alert service<br/>[alert_service.py]"]
  node_n_preprocess["Preprocess<br/>ml pipeline<br/>[preprocess.py]"]
  node_n_train["Train models<br/>ml pipeline<br/>[train.py]"]
  node_n_utils["Pipeline utils<br/>helpers<br/>[utils.py]"]
  node_n_artifacts[("Artifacts<br/>model registry")]
  node_n_models_bundle[("Model bundle<br/>serialized models<br/>[models.pkl]")]
end

subgraph group_grp_frontend["Frontend"]
  node_n_front_app["App shell<br/>React app<br/>[App.tsx]"]
  node_n_routes["Routes<br/>navigation<br/>[routes.ts]"]
  node_n_layout["Layout<br/>shell<br/>[AppLayout.tsx]"]
  node_n_theme["Theme<br/>context<br/>[ThemeContext.tsx]"]
  node_n_api_client["API client<br/>http client<br/>[api.ts]"]
  node_n_pages["Dashboard pages<br/>views<br/>[Dashboard.tsx]"]
  node_n_ui["UI kit<br/>components<br/>[button.tsx]"]
end

subgraph group_grp_shared["Shared assets"]
  node_n_csv[("Telco data<br/>dataset")]
  node_n_styles["Theme styles<br/>css<br/>[theme.css]"]
end

node_n_main -->|"uses"| node_n_data_service
node_n_main -->|"uses"| node_n_model_service
node_n_main -->|"uses"| node_n_alert_service
node_n_data_service -->|"reads"| node_n_artifacts
node_n_model_service -->|"reads"| node_n_artifacts
node_n_model_service -->|"loads"| node_n_models_bundle
node_n_alert_service -->|"reads"| node_n_artifacts
node_n_preprocess -->|"ingests"| node_n_csv
node_n_train -->|"depends on"| node_n_preprocess
node_n_train -->|"uses"| node_n_utils
node_n_train -->|"writes"| node_n_artifacts
node_n_preprocess -->|"writes"| node_n_artifacts
node_n_front_app -->|"uses"| node_n_routes
node_n_front_app -->|"uses"| node_n_layout
node_n_front_app -->|"uses"| node_n_theme
node_n_pages -->|"calls"| node_n_api_client
node_n_pages -->|"composes"| node_n_ui
node_n_layout -->|"composes"| node_n_ui
node_n_theme -->|"applies"| node_n_styles
node_n_api_client -->|"requests"| node_n_main

click node_n_main "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/main.py"
click node_n_data_service "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/services/data_service.py"
click node_n_model_service "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/services/model_service.py"
click node_n_alert_service "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/services/alert_service.py"
click node_n_preprocess "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/pipeline/preprocess.py"
click node_n_train "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/pipeline/train.py"
click node_n_utils "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/pipeline/utils.py"
click node_n_artifacts "https://github.com/akshatsinghnayal/customer-churn-prediction/tree/main/backend/artifacts"
click node_n_models_bundle "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/artifacts/models.pkl"
click node_n_front_app "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/App.tsx"
click node_n_routes "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/routes.ts"
click node_n_layout "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/components/layout/AppLayout.tsx"
click node_n_theme "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/context/ThemeContext.tsx"
click node_n_api_client "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/services/api.ts"
click node_n_pages "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/pages/Dashboard.tsx"
click node_n_ui "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/components/ui/button.tsx"
click node_n_csv "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/WA_Fn-UseC_-Telco-Customer-Churn.csv"
click node_n_styles "https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/styles/theme.css"

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_n_main,node_n_data_service,node_n_model_service,node_n_alert_service,node_n_preprocess,node_n_train,node_n_utils,node_n_artifacts,node_n_models_bundle toneBlue
class node_n_front_app,node_n_routes,node_n_layout,node_n_theme,node_n_api_client,node_n_pages,node_n_ui toneAmber
class node_n_csv,node_n_styles toneMint
```

## Components

### Backend

FastAPI runtime plus offline ML pipeline and persisted artifacts.

- [API server](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/main.py): FastAPI app · Entry point for the online backend runtime. · `backend/main.py`
- [Data service](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/services/data_service.py): service · Aggregates customer and dataset-derived views for the API. · `backend/services/data_service.py`
- [Model service](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/services/model_service.py): service · Loads trained models, scaler, features, and thresholds for churn scoring. · `backend/services/model_service.py`
- [Alert service](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/services/alert_service.py): service · Applies business rules to model outputs to produce churn alerts. · `backend/services/alert_service.py`
- [Preprocess](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/pipeline/preprocess.py): ml pipeline · Cleans data, engineers features, encodes categories, and scales inputs. · `backend/pipeline/preprocess.py`
- [Train models](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/pipeline/train.py): ml pipeline · Trains, tunes, thresholds, and ensembles churn models. · `backend/pipeline/train.py`
- [Pipeline utils](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/pipeline/utils.py): helpers · Shared training and preprocessing utilities. · `backend/pipeline/utils.py`
- [Artifacts](https://github.com/akshatsinghnayal/customer-churn-prediction/tree/main/backend/artifacts): model registry · Serialized models, scalers, splits, metrics, predictions, and alerts consumed by runtime code. · `backend/artifacts`
- [Model bundle](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/backend/artifacts/models.pkl): serialized models · 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](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/App.tsx): React app · Client application bootstrap and top-level composition. · `src/app/App.tsx`
- [Routes](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/routes.ts): navigation · Maps the dashboard screens and auth pages. · `src/app/routes.ts`
- [Layout](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/components/layout/AppLayout.tsx): shell · Primary UI frame with sidebar and top navigation. · `src/app/components/layout/AppLayout.tsx`
- [Theme](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/context/ThemeContext.tsx): context · Controls appearance and accent selection. · `src/app/context/ThemeContext.tsx`
- [API client](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/services/api.ts): http client · Frontend boundary for calling the FastAPI backend. · `src/app/services/api.ts`
- [Dashboard pages](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/pages/Dashboard.tsx): views · Operational screens for overview, analytics, customers, predictions, models, alerts, profile, settings, and auth. · `src/app/pages/Dashboard.tsx`
- [UI kit](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/app/components/ui/button.tsx): components · 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](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/WA_Fn-UseC_-Telco-Customer-Churn.csv): dataset · Source churn dataset used by the offline pipeline. · `WA_Fn-UseC_-Telco-Customer-Churn.csv`
- [Theme styles](https://github.com/akshatsinghnayal/customer-churn-prediction/blob/main/src/styles/theme.css): css · Global and theme styling for the frontend. · `src/styles/theme.css`

## Connections

- 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.