# aashnology/churn-gauge architecture

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

- Interactive diagram: https://gitdiagram.com/aashnology/churn-gauge
- Repository: https://github.com/aashnology/churn-gauge

## Overview

Churn Gauge is a SaaS churn-risk predictor and action recommender. Its principal workflow is user selection in the adaptive Streamlit launcher, account selection from sample data, model scoring, risk-driver identification, and recommended actions. A separate model-development path generates synthetic datasets, engineers features for v3, trains logistic-regression and XGBoost models, and produces interpretation artifacts including SHAP rankings and partial-dependence results. The README also describes adaptive host recommendations and future CSV uploads behind a quality gate. Some source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`apps/adaptive_launcher.py`](https://github.com/aashnology/churn-gauge/blob/main/apps/adaptive_launcher.py) (Adaptive launcher), [`data/synthetic`](https://github.com/aashnology/churn-gauge/tree/main/data/synthetic) (Synthetic datasets), [`models`](https://github.com/aashnology/churn-gauge/tree/main/models) (Model artifacts), [`data/processed/churn_gauge_v3_engineered.csv`](https://github.com/aashnology/churn-gauge/blob/main/data/processed/churn_gauge_v3_engineered.csv) (Engineered dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Prediction experience"]
  node_launcher["Adaptive launcher"]
  node_sample["Sample account data"]
  node_scoremodel["Scoring model"]
  node_hostchoice["Host recommendation"]
end

subgraph group_data["Data preparation"]
  node_v1gen["Clean data generator"]
  node_v2gen["Medium data generator"]
  node_v3gen["Messy data generator"]
  node_datasets["Synthetic datasets"]
  node_engineering["Feature engineering<br/>[engineer.py]"]
  node_engineered["Engineered dataset"]
end

subgraph group_models["Risk modeling"]
  node_trainlr["Logistic training<br/>[train_logreg_v2.py]"]
  node_trainxgb["XGBoost and SHAP training"]
  node_trainengineered["Engineered model comparison"]
  node_artifacts["Model artifacts"]
end

subgraph group_interpret["Interpretation and actions"]
  node_drivers["Risk drivers"]
  node_recommender["Action recommender<br/>[recommender.py]"]
  node_actions["Recommended actions<br/>[recommender.py]"]
  node_pdp["Partial dependence analysis"]
  node_pdpdata["PDP results<br/>[pdp_values.json]"]
  node_actioncatalogue["Action catalogue"]
end

node_user(("SaaS user"))

node_user -->|"uses"| node_launcher
node_launcher -->|"recommends host"| node_hostchoice
node_launcher -->|"loads sample"| node_sample
node_launcher -->|"loads model"| node_scoremodel
node_launcher -->|"derives drivers"| node_drivers
node_launcher -->|"requests actions"| node_recommender
node_recommender -->|"returns actions"| node_actions
node_v1gen -->|"generates clean"| node_datasets
node_v2gen -->|"generates medium"| node_datasets
node_v3gen -->|"generates messy"| node_datasets
node_datasets -->|"engineers v3"| node_engineering
node_engineering -->|"writes features"| node_engineered
node_datasets -->|"trains on v2"| node_trainlr
node_datasets -->|"trains on v2"| node_trainxgb
node_engineered -->|"trains and compares"| node_trainengineered
node_trainlr -->|"saves model"| node_artifacts
node_trainxgb -->|"saves model and SHAP"| node_artifacts
node_trainengineered -->|"saves models"| node_artifacts
node_artifacts -->|"includes scoring model"| node_scoremodel
node_engineered -->|"supplies analysis data"| node_pdp
node_artifacts -->|"supplies model"| node_pdp
node_pdp -->|"writes PDP values"| node_pdpdata

click node_launcher "https://github.com/aashnology/churn-gauge/blob/main/apps/adaptive_launcher.py"
click node_sample "https://github.com/aashnology/churn-gauge/blob/main/data/synthetic/churn_gauge_v2_medium_9000.csv"
click node_scoremodel "https://github.com/aashnology/churn-gauge/blob/main/models/xgb_shap_v2_medium.joblib"
click node_hostchoice "https://github.com/aashnology/churn-gauge/blob/main/apps/adaptive_launcher.py"
click node_v1gen "https://github.com/aashnology/churn-gauge/blob/main/src/data/generate_synthetic_v1.py"
click node_v2gen "https://github.com/aashnology/churn-gauge/blob/main/src/data/generate_synthetic_v2.py"
click node_v3gen "https://github.com/aashnology/churn-gauge/blob/main/src/data/generate_synthetic_v3.py"
click node_datasets "https://github.com/aashnology/churn-gauge/tree/main/data/synthetic"
click node_engineering "https://github.com/aashnology/churn-gauge/blob/main/src/features/engineer.py"
click node_engineered "https://github.com/aashnology/churn-gauge/blob/main/data/processed/churn_gauge_v3_engineered.csv"
click node_trainlr "https://github.com/aashnology/churn-gauge/blob/main/src/models/train_logreg_v2.py"
click node_trainxgb "https://github.com/aashnology/churn-gauge/blob/main/src/models/train_xgb_shap_v2.py"
click node_trainengineered "https://github.com/aashnology/churn-gauge/blob/main/src/models/train_engineered_v3.py"
click node_artifacts "https://github.com/aashnology/churn-gauge/tree/main/models"
click node_drivers "https://github.com/aashnology/churn-gauge/blob/main/apps/adaptive_launcher.py"
click node_recommender "https://github.com/aashnology/churn-gauge/blob/main/src/actions/recommender.py"
click node_actions "https://github.com/aashnology/churn-gauge/blob/main/src/actions/recommender.py"
click node_pdp "https://github.com/aashnology/churn-gauge/blob/main/evaluation/partial_dependence.py"
click node_pdpdata "https://github.com/aashnology/churn-gauge/blob/main/evaluation/pdp/pdp_values.json"
click node_actioncatalogue "https://github.com/aashnology/churn-gauge/blob/main/docs/ACTION_CATALOGUE.md"

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_launcher,node_sample,node_scoremodel,node_hostchoice,node_user toneBlue
class node_v1gen,node_v2gen,node_v3gen,node_datasets,node_engineering,node_engineered toneAmber
class node_trainlr,node_trainxgb,node_trainengineered,node_artifacts toneMint
class node_drivers,node_recommender,node_actions,node_pdp,node_pdpdata,node_actioncatalogue toneRose
```

## Components

### Prediction experience

- [Adaptive launcher](https://github.com/aashnology/churn-gauge/blob/main/apps/adaptive_launcher.py): `apps/adaptive_launcher.py`
- [Sample account data](https://github.com/aashnology/churn-gauge/blob/main/data/synthetic/churn_gauge_v2_medium_9000.csv): `data/synthetic/churn_gauge_v2_medium_9000.csv`
- [Scoring model](https://github.com/aashnology/churn-gauge/blob/main/models/xgb_shap_v2_medium.joblib): `models/xgb_shap_v2_medium.joblib`
- [Host recommendation](https://github.com/aashnology/churn-gauge/blob/main/apps/adaptive_launcher.py): `apps/adaptive_launcher.py`

### Data preparation

- [Clean data generator](https://github.com/aashnology/churn-gauge/blob/main/src/data/generate_synthetic_v1.py): `src/data/generate_synthetic_v1.py`
- [Medium data generator](https://github.com/aashnology/churn-gauge/blob/main/src/data/generate_synthetic_v2.py): `src/data/generate_synthetic_v2.py`
- [Messy data generator](https://github.com/aashnology/churn-gauge/blob/main/src/data/generate_synthetic_v3.py): `src/data/generate_synthetic_v3.py`
- [Synthetic datasets](https://github.com/aashnology/churn-gauge/tree/main/data/synthetic): `data/synthetic`
- [Feature engineering](https://github.com/aashnology/churn-gauge/blob/main/src/features/engineer.py): `src/features/engineer.py`
- [Engineered dataset](https://github.com/aashnology/churn-gauge/blob/main/data/processed/churn_gauge_v3_engineered.csv): `data/processed/churn_gauge_v3_engineered.csv`

### Risk modeling

- [Logistic training](https://github.com/aashnology/churn-gauge/blob/main/src/models/train_logreg_v2.py): `src/models/train_logreg_v2.py`
- [XGBoost and SHAP training](https://github.com/aashnology/churn-gauge/blob/main/src/models/train_xgb_shap_v2.py): `src/models/train_xgb_shap_v2.py`
- [Engineered model comparison](https://github.com/aashnology/churn-gauge/blob/main/src/models/train_engineered_v3.py): `src/models/train_engineered_v3.py`
- [Model artifacts](https://github.com/aashnology/churn-gauge/tree/main/models): `models`

### Interpretation and actions

- [Risk drivers](https://github.com/aashnology/churn-gauge/blob/main/apps/adaptive_launcher.py): `apps/adaptive_launcher.py`
- [Action recommender](https://github.com/aashnology/churn-gauge/blob/main/src/actions/recommender.py): `src/actions/recommender.py`
- [Recommended actions](https://github.com/aashnology/churn-gauge/blob/main/src/actions/recommender.py): `src/actions/recommender.py`
- [Partial dependence analysis](https://github.com/aashnology/churn-gauge/blob/main/evaluation/partial_dependence.py): `evaluation/partial_dependence.py`
- [PDP results](https://github.com/aashnology/churn-gauge/blob/main/evaluation/pdp/pdp_values.json): `evaluation/pdp/pdp_values.json`
- [Action catalogue](https://github.com/aashnology/churn-gauge/blob/main/docs/ACTION_CATALOGUE.md): `docs/ACTION_CATALOGUE.md`

### Other components

- **SaaS user**

## Connections

- SaaS user → Adaptive launcher: uses
- Adaptive launcher → Host recommendation: recommends host
- Adaptive launcher → Sample account data: loads sample
- Adaptive launcher → Scoring model: loads model
- Adaptive launcher → Risk drivers: derives drivers
- Adaptive launcher → Action recommender: requests actions
- Action recommender → Recommended actions: returns actions
- Clean data generator → Synthetic datasets: generates clean
- Medium data generator → Synthetic datasets: generates medium
- Messy data generator → Synthetic datasets: generates messy
- Synthetic datasets → Feature engineering: engineers v3
- Feature engineering → Engineered dataset: writes features
- Synthetic datasets → Logistic training: trains on v2
- Synthetic datasets → XGBoost and SHAP training: trains on v2
- Engineered dataset → Engineered model comparison: trains and compares
- Logistic training → Model artifacts: saves model
- XGBoost and SHAP training → Model artifacts: saves model and SHAP
- Engineered model comparison → Model artifacts: saves models
- Model artifacts → Scoring model: includes scoring model
- Engineered dataset → Partial dependence analysis: supplies analysis data
- Model artifacts → Partial dependence analysis: supplies model
- Partial dependence analysis → PDP results: writes PDP values