How anesriad/telco-customer-churn-ml works
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