# med00amine/customer-churn-api architecture

> Architecture diagram of the GitHub repository med00amine/customer-churn-api, 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/med00amine/customer-churn-api
- Repository: https://github.com/med00amine/customer-churn-api

## Overview

This is a customer-churn prediction API with a separate exploration and model-training workflow. A client submits customer data to FastAPI, which validates it and calls the prediction function; that function maps fields, requests a churn prediction and probability, then derives a risk level and recommendation. The README also describes a preprocessing pipeline and Random Forest model. Source sampling shows training saves a model, but the serving code assigns a path string rather than loading an estimator, so artifact-to-inference wiring is not established here.

Main entry points: [`app/main.py`](https://github.com/med00amine/customer-churn-api/blob/main/app/main.py) (FastAPI app), [`training/preprocess.py`](https://github.com/med00amine/customer-churn-api/blob/main/training/preprocess.py) (Preprocessing), [`app/predict.py`](https://github.com/med00amine/customer-churn-api/blob/main/app/predict.py) (Prediction function), [`training/train.py`](https://github.com/med00amine/customer-churn-api/blob/main/training/train.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis_training["Data and training"]
  node_explore["Data exploration<br/>[explore.py]"]
  node_preprocess["Preprocessing<br/>[preprocess.py]"]
  node_train["Model training<br/>[train.py]"]
  node_preprocessor_artifact["Preprocessor artifact"]
  node_trained_model["Trained model"]
end

subgraph group_api_serving["API serving"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_request_schema["Request validation<br/>[schemas.py]"]
end

subgraph group_prediction["Prediction logic"]
  node_predict["Prediction function<br/>[predict.py]"]
  node_prediction_result["Churn and risk result"]
end

subgraph group_runtime_support["Runtime support"]
  node_config["API configuration<br/>[config.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

node_client(("API client"))
node_dataset["Telco churn data"]

node_explore -->|"reads"| node_dataset
node_preprocess -->|"reads"| node_dataset
node_train -->|"imports pipeline"| node_preprocess
node_preprocess -->|"writes preprocessor"| node_preprocessor_artifact
node_train -->|"writes model"| node_trained_model
node_client -->|"sends request"| node_fastapi
node_fastapi -->|"validates input"| node_request_schema
node_fastapi -->|"calls"| node_predict
node_predict -->|"returns"| node_prediction_result
node_config -->|"provides settings"| node_fastapi
node_fastapi -->|"logs startup"| node_logger
node_predict -->|"logs prediction"| node_logger

click node_dataset "https://github.com/med00amine/customer-churn-api/blob/main/data/Telco_customer_churn.xlsx"
click node_explore "https://github.com/med00amine/customer-churn-api/blob/main/training/explore.py"
click node_preprocess "https://github.com/med00amine/customer-churn-api/blob/main/training/preprocess.py"
click node_train "https://github.com/med00amine/customer-churn-api/blob/main/training/train.py"
click node_preprocessor_artifact "https://github.com/med00amine/customer-churn-api/tree/main/models"
click node_trained_model "https://github.com/med00amine/customer-churn-api/tree/main/models"
click node_fastapi "https://github.com/med00amine/customer-churn-api/blob/main/app/main.py"
click node_request_schema "https://github.com/med00amine/customer-churn-api/blob/main/app/schemas.py"
click node_config "https://github.com/med00amine/customer-churn-api/blob/main/app/config.py"
click node_logger "https://github.com/med00amine/customer-churn-api/blob/main/app/logger.py"
click node_predict "https://github.com/med00amine/customer-churn-api/blob/main/app/predict.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_explore,node_preprocess,node_train,node_preprocessor_artifact,node_trained_model,node_client toneBlue
class node_fastapi,node_request_schema toneAmber
class node_predict,node_prediction_result toneMint
class node_config,node_logger toneRose
class node_dataset toneTeal
```

## Components

### Data and training

- [Data exploration](https://github.com/med00amine/customer-churn-api/blob/main/training/explore.py): `training/explore.py`
- [Preprocessing](https://github.com/med00amine/customer-churn-api/blob/main/training/preprocess.py): `training/preprocess.py`
- [Model training](https://github.com/med00amine/customer-churn-api/blob/main/training/train.py): `training/train.py`
- [Preprocessor artifact](https://github.com/med00amine/customer-churn-api/tree/main/models): `models`
- [Trained model](https://github.com/med00amine/customer-churn-api/tree/main/models): `models`

### API serving

- [FastAPI app](https://github.com/med00amine/customer-churn-api/blob/main/app/main.py): `app/main.py`
- [Request validation](https://github.com/med00amine/customer-churn-api/blob/main/app/schemas.py): `app/schemas.py`

### Prediction logic

- [Prediction function](https://github.com/med00amine/customer-churn-api/blob/main/app/predict.py): `app/predict.py`
- **Churn and risk result**

### Runtime support

- [API configuration](https://github.com/med00amine/customer-churn-api/blob/main/app/config.py): `app/config.py`
- [Logging](https://github.com/med00amine/customer-churn-api/blob/main/app/logger.py): `app/logger.py`

### Other components

- **API client**
- [Telco churn data](https://github.com/med00amine/customer-churn-api/blob/main/data/Telco_customer_churn.xlsx): `data/Telco_customer_churn.xlsx`

## Connections

- Data exploration → Telco churn data: reads
- Preprocessing → Telco churn data: reads
- Model training → Preprocessing: imports pipeline
- Preprocessing → Preprocessor artifact: writes preprocessor
- Model training → Trained model: writes model
- API client → FastAPI app: sends request
- FastAPI app → Request validation: validates input
- FastAPI app → Prediction function: calls
- Prediction function → Churn and risk result: returns
- API configuration → FastAPI app: provides settings
- FastAPI app → Logging: logs startup
- Prediction function → Logging: logs prediction