# arpitjain-coder/churnai architecture

> Architecture diagram of the GitHub repository arpitjain-coder/churnai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arpitjain-coder/churnai
- Repository: https://github.com/arpitjain-coder/churnai

## Overview

This is a telecom customer-churn prediction application, with both a Streamlit interface and a FastAPI service. Users provide customer and account details; the application encodes the inputs, scales numeric fields, and returns a churn prediction and probability. The API also exposes prediction history, aggregate statistics, and model feature impacts, and logs predictions to Supabase when configured or local SQLite otherwise. Training scripts create the model artifacts from the supplied dataset. The README is empty; the API excerpt omits some initialization and frontend code, so no browser-to-API wiring is asserted.

Main entry points: [`api/index.py`](https://github.com/arpitjain-coder/churnai/blob/main/api/index.py) (FastAPI Service), [`churn_model.pkl`](https://github.com/arpitjain-coder/churnai/blob/main/churn_model.pkl) (Churn Model), [`app.py`](https://github.com/arpitjain-coder/churnai/blob/main/app.py) (Streamlit App), [`train_better_model.py`](https://github.com/arpitjain-coder/churnai/blob/main/train_better_model.py) (Model Training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_streamlit["Streamlit App<br/>[app.py]"]
  node_api["FastAPI Service<br/>[index.py]"]
  node_frontend["Served Frontend<br/>[index.html]"]
end

subgraph group_inference["Prediction Runtime"]
  node_model["Churn Model<br/>[churn_model.pkl]"]
  node_scaler["Feature Scaler<br/>[scaler &#40;1&#41;.pkl]"]
end

subgraph group_insights["History And Insights"]
  node_history["Prediction History<br/>[index.py]"]
  node_statistics["Usage Statistics<br/>[index.py]"]
  node_feature_impacts["Feature Impacts<br/>[index.py]"]
  node_supabase[("Supabase")]
  node_sqlite[("Local SQLite<br/>[index.py]")]
end

subgraph group_modeling["Model Training"]
  node_dataset["Churn Dataset"]
  node_trainer["Model Training"]
end

node_customer(("Customer"))

node_customer -->|"enters details"| node_streamlit
node_streamlit -->|"loads and applies"| node_scaler
node_streamlit -->|"loads and predicts"| node_model
node_customer -.->|"submits details"| node_api
node_api -->|"serves HTML"| node_frontend
node_api -->|"scales features"| node_scaler
node_api -->|"predicts churn"| node_model
node_api -->|"logs predictions"| node_supabase
node_api -->|"logs predictions"| node_sqlite
node_history -->|"reads history"| node_supabase
node_history -->|"reads history"| node_sqlite
node_statistics -->|"reads records"| node_supabase
node_statistics -->|"reads records"| node_sqlite
node_feature_impacts -->|"reads importances"| node_model
node_dataset -->|"trains from"| node_trainer
node_trainer -->|"saves model"| node_model
node_trainer -->|"saves scaler"| node_scaler

click node_streamlit "https://github.com/arpitjain-coder/churnai/blob/main/app.py"
click node_api "https://github.com/arpitjain-coder/churnai/blob/main/api/index.py"
click node_frontend "https://github.com/arpitjain-coder/churnai/blob/main/index.html"
click node_model "https://github.com/arpitjain-coder/churnai/blob/main/churn_model.pkl"
click node_scaler "https://github.com/arpitjain-coder/churnai/blob/main/scaler%20(1).pkl"
click node_history "https://github.com/arpitjain-coder/churnai/blob/main/api/index.py"
click node_statistics "https://github.com/arpitjain-coder/churnai/blob/main/api/index.py"
click node_feature_impacts "https://github.com/arpitjain-coder/churnai/blob/main/api/index.py"
click node_sqlite "https://github.com/arpitjain-coder/churnai/blob/main/api/index.py"
click node_dataset "https://github.com/arpitjain-coder/churnai/blob/main/WA_Fn-UseC_-Telco-Customer-Churn.csv"
click node_trainer "https://github.com/arpitjain-coder/churnai/blob/main/train_better_model.py"

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_streamlit,node_api,node_frontend toneBlue
class node_model,node_scaler toneAmber
class node_history,node_statistics,node_feature_impacts,node_supabase,node_sqlite toneMint
class node_dataset,node_trainer toneRose
class node_customer toneIndigo
```

## Components

### User Interfaces

- [Streamlit App](https://github.com/arpitjain-coder/churnai/blob/main/app.py): `app.py`
- [FastAPI Service](https://github.com/arpitjain-coder/churnai/blob/main/api/index.py): `api/index.py`
- [Served Frontend](https://github.com/arpitjain-coder/churnai/blob/main/index.html): `index.html`

### Prediction Runtime

- [Churn Model](https://github.com/arpitjain-coder/churnai/blob/main/churn_model.pkl): `churn_model.pkl`
- [Feature Scaler](https://github.com/arpitjain-coder/churnai/blob/main/scaler%20(1).pkl): `scaler (1).pkl`

### History And Insights

- [Prediction History](https://github.com/arpitjain-coder/churnai/blob/main/api/index.py): `api/index.py`
- [Usage Statistics](https://github.com/arpitjain-coder/churnai/blob/main/api/index.py): `api/index.py`
- [Feature Impacts](https://github.com/arpitjain-coder/churnai/blob/main/api/index.py): `api/index.py`
- **Supabase**
- [Local SQLite](https://github.com/arpitjain-coder/churnai/blob/main/api/index.py): `api/index.py`

### Model Training

- [Churn Dataset](https://github.com/arpitjain-coder/churnai/blob/main/WA_Fn-UseC_-Telco-Customer-Churn.csv): `WA_Fn-UseC_-Telco-Customer-Churn.csv`
- [Model Training](https://github.com/arpitjain-coder/churnai/blob/main/train_better_model.py): `train_better_model.py`

### Other components

- **Customer**

## Connections

- Customer → Streamlit App: enters details (evidence: `app.py`)
- Streamlit App → Feature Scaler: loads and applies (evidence: `app.py`)
- Streamlit App → Churn Model: loads and predicts (evidence: `app.py`)
- Customer → FastAPI Service: submits details
- FastAPI Service → Served Frontend: serves HTML (evidence: `api/index.py`)
- FastAPI Service → Feature Scaler: scales features (evidence: `api/index.py`)
- FastAPI Service → Churn Model: predicts churn (evidence: `api/index.py`)
- FastAPI Service → Supabase: logs predictions (evidence: `api/index.py`)
- FastAPI Service → Local SQLite: logs predictions (evidence: `api/index.py`)
- Prediction History → Supabase: reads history (evidence: `api/index.py`)
- Prediction History → Local SQLite: reads history (evidence: `api/index.py`)
- Usage Statistics → Supabase: reads records (evidence: `api/index.py`)
- Usage Statistics → Local SQLite: reads records (evidence: `api/index.py`)
- Feature Impacts → Churn Model: reads importances (evidence: `api/index.py`)
- Churn Dataset → Model Training: trains from (evidence: `train_better_model.py`)
- Model Training → Churn Model: saves model (evidence: `train_better_model.py`)
- Model Training → Feature Scaler: saves scaler (evidence: `train_better_model.py`)
