# glaucojrcarvalho/customer-churn-saas architecture

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

- Interactive diagram: https://gitdiagram.com/glaucojrcarvalho/customer-churn-saas
- Repository: https://github.com/glaucojrcarvalho/customer-churn-saas

## Overview

This repository is a FastAPI customer-churn prediction service. Customers submit records as JSON or upload a CSV; the corresponding route validates or normalizes the input, runs the saved classifier pipeline, and returns churn probabilities with labels. A separate training workflow reads labeled data, prepares features, fits the pipeline, and saves the model artifact used by both routes. The graph follows the sampled route and training code plus README-documented capabilities; unsampled implementation details are not inferred.

Main entry points: [`app/routers/predict.py`](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/routers/predict.py) (JSON prediction), [`app/routers/upload.py`](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/routers/upload.py) (CSV upload), [`app/services/train_model.py`](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/services/train_model.py) (Pipeline training), [`app/main.py`](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_app["FastAPI app<br/>[main.py]"]
  node_json_route["JSON prediction<br/>[predict.py]"]
  node_csv_route["CSV upload<br/>[upload.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
end

subgraph group_inference["Prediction"]
  node_normalizer["Feature normalization<br/>[preprocessing.py]"]
  node_pipeline["Saved model pipeline<br/>[churn_pipeline.pkl]"]
end

subgraph group_training["Model training"]
  node_trainer["Pipeline training<br/>[train_model.py]"]
  node_training_data["Training dataset<br/>[train.csv]"]
end

node_customer(("Customer"))

node_customer -->|"submits request"| node_app
node_app -->|"routes /predict"| node_json_route
node_app -->|"routes /upload"| node_csv_route
node_json_route -->|"validates and formats"| node_schemas
node_csv_route -->|"formats results"| node_schemas
node_json_route -->|"normalizes records"| node_normalizer
node_csv_route -->|"normalizes rows"| node_normalizer
node_json_route -->|"loads and predicts"| node_pipeline
node_csv_route -->|"loads and predicts"| node_pipeline
node_trainer -->|"reads labeled data"| node_training_data
node_trainer -->|"uses feature preparation"| node_normalizer
node_trainer -->|"saves fitted pipeline"| node_pipeline

click node_app "https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/main.py"
click node_json_route "https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/routers/predict.py"
click node_csv_route "https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/routers/upload.py"
click node_schemas "https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/utils/schemas.py"
click node_normalizer "https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/services/preprocessing.py"
click node_pipeline "https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/models/churn_pipeline.pkl"
click node_trainer "https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/services/train_model.py"
click node_training_data "https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/data/train.csv"

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_app,node_json_route,node_csv_route,node_schemas toneBlue
class node_normalizer,node_pipeline toneAmber
class node_trainer,node_training_data toneMint
class node_customer toneIndigo
```

## Components

### API

- [FastAPI app](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/main.py): `app/main.py`
- [JSON prediction](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/routers/predict.py): `app/routers/predict.py`
- [CSV upload](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/routers/upload.py): `app/routers/upload.py`
- [Request and response schemas](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/utils/schemas.py): `app/utils/schemas.py`

### Prediction

- [Feature normalization](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/services/preprocessing.py): `app/services/preprocessing.py`
- [Saved model pipeline](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/models/churn_pipeline.pkl): `app/models/churn_pipeline.pkl`

### Model training

- [Pipeline training](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/app/services/train_model.py): `app/services/train_model.py`
- [Training dataset](https://github.com/glaucojrcarvalho/customer-churn-saas/blob/main/data/train.csv): `data/train.csv`

### Other components

- **Customer**

## Connections

- Customer → FastAPI app: submits request (evidence: `README.md`)
- FastAPI app → JSON prediction: routes /predict (evidence: `app/main.py`)
- FastAPI app → CSV upload: routes /upload (evidence: `app/main.py`)
- JSON prediction → Request and response schemas: validates and formats (evidence: `app/routers/predict.py`)
- CSV upload → Request and response schemas: formats results (evidence: `app/routers/upload.py`)
- JSON prediction → Feature normalization: normalizes records (evidence: `app/routers/predict.py`)
- CSV upload → Feature normalization: normalizes rows (evidence: `app/routers/upload.py`)
- JSON prediction → Saved model pipeline: loads and predicts (evidence: `app/routers/predict.py`)
- CSV upload → Saved model pipeline: loads and predicts (evidence: `app/routers/upload.py`)
- Pipeline training → Training dataset: reads labeled data (evidence: `README.md`)
- Pipeline training → Feature normalization: uses feature preparation (evidence: `app/services/train_model.py`)
- Pipeline training → Saved model pipeline: saves fitted pipeline (evidence: `README.md`)
