# anesriad/telco-customer-churn-ml architecture

> Architecture diagram of the GitHub repository anesriad/telco-customer-churn-ml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anesriad/telco-customer-churn-ml
- Repository: https://github.com/anesriad/telco-customer-churn-ml

## Overview

##### Project Type & Purpose
- This is an end-to-end telco-churn machine-learning solution: data ingestion, feature engineering, model training/experiment tracking, REST inference + web UI, containerized, CI/CD-driven, deployed on AWS ECS & ALB.

##### File-Structure Analysis
- Top-level:
- notebooks/ – EDA
- scripts/ – pipeline orchestration & tests
- src/
– data/ (load_data.py, preprocess.py)
– features/ (build_features.py)
– models/ (train, tune, evaluate)
– app/ (FastAPI entrypoints)
– serving/ (inference logic + MLflow model artifacts)
– utils/ (helper modules)
- CI/CD:
- .github/workflows/ci.yml
- Container:
- dockerfile, .dockerignore, requirements.txt
- MLflow artifacts under src/serving/model/*

##### README Insights
- MLflow for experiment tracking & artifact storing.
- FastAPI exposes /predict and health check.
- Gradio UI mounted at /ui.
- Docker image built with uvicorn src.app.main:app on port 8000.
- GitHub Actions → Docker Hub → ECS Fargate → ALB → CloudWatch.

a. Main Components
- Data Layer: Raw data → EDA notebooks & preprocessing scripts
- Feature Engineering: src/features/build_features.py
- Modeling: src/models/train.py, tune.py, evaluate.py
- Experiment Tracking: MLflow server + mlruns directory
- Model Artifacts Storage: versioned model folders under src/serving/model/
- Inference Service: FastAPI app (src/app + src/serving/inference.py)
- Web UI: Gradio interface mounted at /ui
- Containerization: Docker image with uvicorn entrypoint
- CI/CD Pipeline: GitHub Actions workflow → Docker Hub
- Deployment Infra: AWS ECS Fargate task, Application Load Balancer (ALB), Security Groups
- Observability: CloudWatch logs & ECS events

b. Relationships & Interactions
– Preprocessing → Feature Engineering → Model Training
– Training logs to MLflow → produces model artifacts
– Container build includes inference code + frozen model artifacts
– CI/CD triggers container build → pushes to Docker Hub
– ECS pulls new image → spins up task behind ALB
– ALB health check (HTTP:80 → 8000) → routes traffic to FastAPI
– Clients: REST calls (/predict) or UI calls (/ui) → FastAPI
– FastAPI loads model artifacts from local path embedded in image
– Logs emitted to stdout/stderr → CloudWatch

c. Architectural Patterns & Principles
– Clear separation: Data ingestion, feature engineering, modeling, serving
– Experiment reproducibility: MLflow tracking server & artifact versioning
– Container-first design: consistent dev/prod environment
– Infrastructure as code: CI/CD via GitHub Actions, declarative ECS updates
– 12-factor app: config via environment, logs to stdout, backing services (MLflow) externalized

d. Key Technologies
– Python: pandas/sklearn/XGBoost
– MLflow: experiment tracking & model registry
– FastAPI + Uvicorn: inference API
– Gradio: web UI
– Docker: containerization
– GitHub Actions: CI/CD
– Docker Hub: image registry
– AWS ECS Fargate & ALB: container orchestration & load balancing
– CloudWatch: logging & monitoring

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data and Preprocessing
    subgraph "Data Layer" 
        direction TB
        N1["EDA Notebooks"]:::blue
        N2["Load Data"]:::blue
        N3["Preprocess"]:::blue
        N4["Pipeline Orchestration"]:::blue
    end

    %% Feature Engineering
    subgraph "Feature Engineering"
        direction TB
        FE["Build Features"]:::blue
    end

    %% Modeling
    subgraph "Modeling"
        direction TB
        MT["Train Model"]:::blue
        HT["Tune Hyperparameters"]:::blue
        ME["Evaluate Model"]:::blue
    end

    %% Experiment Tracking
    subgraph "Experiment Tracking" 
        direction TB
        MLflow["MLflow Server & mlruns"]:::external
        Artifacts["Model Artifacts"]:::external
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        U1["General Helpers"]:::blue
        U2["Data Validation"]:::blue
    end

    %% Serving & UI
    subgraph "Serving & UI"
        direction TB
        API["FastAPI Service"]:::green
        UI["Gradio UI"]:::green
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        direction TB
        GH["GitHub Actions"]:::orange
        DH["Docker Hub"]:::external
    end

    %% AWS Infrastructure
    subgraph "AWS Infra"
        direction TB
        ALB["ALB (80→8000)"]:::orange
        ECS["ECS Fargate Task"]:::orange
        CW["CloudWatch Logs"]:::orange
    end

    %% Data Flow
    N1 --> N2 --> N3 --> N4 --> FE --> MT --> HT --> ME --> MLflow --> Artifacts --> API
    UI --> API
    API -->|"loads model"| Artifacts
    API --> CW
    ALB -->|"HTTP health check"| API
    GH --> DH --> ECS
    ECS --> API

    %% Click Events
    click N1 "https://github.com/anesriad/telco-customer-churn-ml/blob/main/notebooks/EDA.ipynb"
    click N2 "https://github.com/anesriad/telco-customer-churn-ml/blob/main/src/data/load_data.py"
    click N3 "https://github.com/anesriad/telco-customer-churn-ml/blob/main/src/data/preprocess.py"
    click N4 "https://github.com/anesriad/telco-customer-churn-ml/blob/main/scripts/run_pipeline.py"
    click FE "https://github.com/anesriad/telco-customer-churn-ml/blob/main/src/features/build_features.py"
    click MT "https://github.com/anesriad/telco-customer-churn-ml/blob/main/src/models/train.py"
    click HT "https://github.com/anesriad/telco-customer-churn-ml/blob/main/src/models/tune.py"
    click ME "https://github.com/anesriad/telco-customer-churn-ml/blob/main/src/models/evaluate.py"
    click Artifacts "https://github.com/anesriad/telco-customer-churn-ml/tree/main/src/serving/model/"
    click API "https://github.com/anesriad/telco-customer-churn-ml/blob/main/src/app/main.py"
    click UI "https://github.com/anesriad/telco-customer-churn-ml/tree/main/.gradio/"
    click U1 "https://github.com/anesriad/telco-customer-churn-ml/blob/main/src/utils/utils.py"
    click U2 "https://github.com/anesriad/telco-customer-churn-ml/blob/main/src/utils/validate_data.py"
    click GH "https://github.com/anesriad/telco-customer-churn-ml/blob/main/.github/workflows/ci.yml"
    click DH "https://github.com/anesriad/telco-customer-churn-ml/tree/main/dockerfile"

    %% Styles
    classDef blue fill:#E0F7FA,stroke:#006064,color:#006064
    classDef green fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef orange fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef external stroke-dasharray: 5 5,fill:#F5F5F5,stroke:#424242,color:#424242
```
