# javithnaseem-j/churnshield architecture

> Architecture diagram of the GitHub repository javithnaseem-j/churnshield, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/javithnaseem-j/churnshield
- Repository: https://github.com/javithnaseem-j/churnshield

## Overview

##### Project Type & Purpose
- This is an MLOps pipeline for binary classification (“Churn” vs. “No Churn”) with:
- Modular stages: data ingestion → validation → transformation → training → evaluation
- A real-time FastAPI prediction service with HTML UI
- Containerization (Docker) and CI/CD (GitHub Actions → AWS ECR/ECS)

##### Main Components & Boundaries
- Data Sources
- Raw CSV (e.g., `artifacts/data_ingestion/Tele_Comm.csv`)
- Pipeline Orchestrator
- `main.py` CLI driving stages defined under `src/mlproject/pipeline/`
- Pipeline Building Blocks
- Components:
– Data Ingestion (`data_ingestion.py`)
– Data Validation (`data_validation.py`)
– Data Transformation (`data_transformation.py`)
– Model Training (`data_modeltraining.py`)
– Model Evaluation (`data_modelevaluation.py`)
- Entities & Config:
– Config loader (`src/mlproject/config/config.py`) + `config/config.yaml` + `params.yaml`
– Schema for validation (`schema.yaml`)
– Output artifacts: encoders, preprocessors, models, metrics in `artifacts/`
- Experimentation Layer (optional)
- Jupyter notebooks in `exp/` for EDA and experimentation
- Inference Service
- FastAPI app (`app.py`) serving endpoints
- HTML templates (`templates/index.html`, `results.html`)
- DevOps & Infrastructure
- Dockerfile → container image
- GitHub Actions workflow (`.github/workflows/cicd.yaml`)
- AWS ECR/ECS deployment

##### Data Flow & Interactions
1. Raw Data → Data Ingestion
2. Ingested Data → Data Validation
3. Validated Data → Data Transformation → produces preprocessed arrays + artifacts
4. Transformed Data → Model Training → produces `model.joblib`
5. Trained Model + Test Data → Model Evaluation → metrics (`metrics.json`)
6. Final Model → Saved to artifacts → Packaged in Docker image
7. User/API Request → FastAPI → loads model + preprocessors → returns prediction
8. CI/CD Pipeline triggers on push → runs tests/lint → builds Docker image → pushes to AWS → deploys

##### Architectural Patterns & Principles
- Modular, single-responsibility components for each pipeline stage
- Configuration-as-code for parameters & schema
- Clear separation between offline batch pipeline (training) and online inference service
- Immutable artifact storage (`artifacts/`) for reproducibility
- Infrastructure-as-code for CI/CD

##### Essential Elements
- Data Sources
- Pipeline Stages (ingestion, validation, transformation, training, evaluation)
- Artifacts Store
- Inference API + UI
- DevOps (Docker, GitHub Actions, AWS)
- Blue for data processing
- Green for model artifacts
- Orange for services/infrastructure
- Grey for config

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        DS["Raw CSV Data"]:::processing
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        PI["Data Ingestion"]:::processing
        PV["Data Validation"]:::processing
        PT["Data Transformation"]:::processing
        MT["Model Training"]:::processing
        ME["Model Evaluation"]:::processing

        DS -->|ingest| PI
        PI -->|validate| PV
        PV -->|transform| PT
        PT -->|train| MT
        MT -->|evaluate| ME
    end

    %% Configs & Entities
    subgraph "Configuration"
        direction TB
        CFG["config/config.yaml"]:::config
        PARAM["params.yaml"]:::config
        SCHEMA["schema.yaml"]:::config
        CL["Config Loader (config.py)"]:::config
        ENT["Entities (config_entity.py)"]:::config

        CFG --> CL
        PARAM --> CL
        SCHEMA --> PV
        CL --> PI
    end

    %% Artifacts Store
    subgraph "Artifacts Store"
        direction TB
        A1(("Ingestion Outputs")):::artifacts
        A2(("Validation Status")):::artifacts
        A3(("Transformation Outputs")):::artifacts
        A4(("Trained Model")):::artifacts
        A5(("Evaluation Metrics")):::artifacts

        PI --> A1
        PV --> A2
        PT --> A3
        MT --> A4
        ME --> A5
    end

    %% Inference API Layer
    subgraph "Inference Service"
        direction TB
        UI["User Browser"]:::external
        API["FastAPI App"]:::service
        T1["index.html"]:::service
        T2["results.html"]:::service

        UI -->|HTTP Request| API
        API --> A4
        API --> A3
        API -->|serves| T1
        API -->|serves| T2
        API -->|response| UI
    end

    %% DevOps & Infrastructure
    subgraph "Deployment Infrastructure"
        direction TB
        DOCKER["Dockerfile"]:::infra
        CICD["GitHub Actions"]:::infra
        AWS["AWS ECR/ECS"]:::infra

        CICD -->|build image| DOCKER
        DOCKER -->|push image| AWS
        AWS -->|deploy| API
    end

    %% Orchestrator
    MP["main.py (CLI)"]:::processing
    MP --> PI

    %% Experimentation Layer
    subgraph "Experiments (exp/)"
        direction TB
        NB1["01_data_ingestion.ipynb"]:::external
        NB2["02_data_validation.ipynb"]:::external
        NB3["03_data_transformation.ipynb"]:::external
        NB4["04_model_training.ipynb"]:::external
        NB5["05_model_evalution.ipynb"]:::external
        NB6["EDA.ipynb"]:::external
    end

    %% Pipeline Scripts
    subgraph "Pipeline Scripts"
        direction TB
        S1["stage1_data_ingestion.py"]:::processing
        S2["stage2_data_validation.py"]:::processing
        S3["stage3_data_transformation.py"]:::processing
        S4["stage4_modeltraining.py"]:::processing
        S5["stage5_data_evalution.py"]:::processing
        PP["pipelineprediction.py"]:::processing

        MP --> S1 --> PI
        MP --> S2 --> PV
        MP --> S3 --> PT
        MP --> S4 --> MT
        MP --> S5 --> ME
        PP --> API
    end

    %% Utility
    UTIL["common.py"]:::config
    UTIL --> MP

    %% Click Events
    click DS "https://github.com/javithnaseem-j/churnshield/blob/main/artifacts/data_ingestion/Tele_Comm.csv"
    click MP "https://github.com/javithnaseem-j/churnshield/blob/main/main.py"
    click PI "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/components/data_ingestion.py"
    click PV "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/components/data_validation.py"
    click PT "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/components/data_transformation.py"
    click MT "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/components/data_modeltraining.py"
    click ME "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/components/data_modelevaluation.py"
    click S1 "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/pipeline/stage1_data_ingestion.py"
    click S2 "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/pipeline/stage2_data_validation.py"
    click S3 "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/pipeline/stage3_data_transformation.py"
    click S4 "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/pipeline/stage4_modeltraining.py"
    click S5 "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/pipeline/stage5_data_evalution.py"
    click PP "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/pipeline/pipelineprediction.py"
    click CL "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/config/config.py"
    click CFG "https://github.com/javithnaseem-j/churnshield/blob/main/config/config.yaml"
    click PARAM "https://github.com/javithnaseem-j/churnshield/blob/main/params.yaml"
    click SCHEMA "https://github.com/javithnaseem-j/churnshield/blob/main/schema.yaml"
    click ENT "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/entities/config_entity.py"
    click UTIL "https://github.com/javithnaseem-j/churnshield/blob/main/src/mlproject/utils/common.py"
    click NB1 "https://github.com/javithnaseem-j/churnshield/blob/main/exp/01_data_ingestion.ipynb"
    click NB2 "https://github.com/javithnaseem-j/churnshield/blob/main/exp/02_data_validation.ipynb"
    click NB3 "https://github.com/javithnaseem-j/churnshield/blob/main/exp/03_data_transformation.ipynb"
    click NB4 "https://github.com/javithnaseem-j/churnshield/blob/main/exp/04_model_training.ipynb"
    click NB5 "https://github.com/javithnaseem-j/churnshield/blob/main/exp/05_model_evalution.ipynb"
    click NB6 "https://github.com/javithnaseem-j/churnshield/blob/main/exp/EDA.ipynb"
    click API "https://github.com/javithnaseem-j/churnshield/blob/main/app.py"
    click T1 "https://github.com/javithnaseem-j/churnshield/blob/main/templates/index.html"
    click T2 "https://github.com/javithnaseem-j/churnshield/blob/main/templates/results.html"
    click A1 "https://github.com/javithnaseem-j/churnshield/tree/main/artifacts/data_ingestion/"
    click A2 "https://github.com/javithnaseem-j/churnshield/blob/main/artifacts/data_validation/status.txt"
    click A3 "https://github.com/javithnaseem-j/churnshield/tree/main/artifacts/data_transformation/"
    click A4 "https://github.com/javithnaseem-j/churnshield/blob/main/artifacts/model_trainer/model.joblib"
    click A5 "https://github.com/javithnaseem-j/churnshield/blob/main/artifacts/model_evaluation/metrics.json"
    click DOCKER "https://github.com/javithnaseem-j/churnshield/tree/main/Dockerfile"
    click CICD "https://github.com/javithnaseem-j/churnshield/blob/main/.github/workflows/cicd.yaml"

    %% Styles
    classDef processing fill:#d0e1f9,stroke:#000,stroke-width:1px
    classDef artifacts fill:#c9eac9,stroke:#000,stroke-width:1px
    classDef service fill:#f9ddd0,stroke:#000,stroke-width:1px
    classDef config fill:#e0e0e0,stroke:#000,stroke-width:1px
    classDef infra fill:#f0e6f7,stroke:#000,stroke-width:1px
    classDef external fill:#ffffff,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
