# jamleston/telecom-project architecture

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

- Interactive diagram: https://gitdiagram.com/jamleston/telecom-project
- Repository: https://github.com/jamleston/telecom-project

## Overview

##### Project Type and Purpose
- This is an applied machine learning project built for predicting customer churn in a telecom company.
- It combines data analysis (via Jupyter notebooks for EDA and preprocessing), model development (with experiments in various ML approaches – logistic regression, decision tree, random forest, and gradient boosting), and deployment (via a Dockerized Streamlit web application).
- The README and file structure clearly indicate that the goal is to create an end-to-end predictive solution with a web interface for customer churn simulation.

##### Analysis of the File Structure
- Top-Level Files/Directories:
- Files like Dockerfile, docker-compose.yml, and requirements.txt indicate containerized deployment.
- app.py represents the Streamlit web application for interactive prediction.
- CSV files (internet_service_churn.csv, preprocessed_dataset.csv) are used for data input.
- Notebooks in the analysis/ and models/ directories denote stages of exploratory data analysis, data preprocessing, and model training.
- The presence of a serialized model file (gradient_boosting_model.pkl) shows that the best-performing model is saved for use in the deployed app.
- Architectural Implications:
- The directory structure suggests separation between data analysis (EDA), preprocessing, model training, and deployment.
- There is a clear data flow from source data → preprocessing → model training/evaluation → deployment.

a. Main Components:
- Data Sources: The raw dataset file (internet_service_churn.csv) and the preprocessed dataset (preprocessed_dataset.csv).
- Data Processing and EDA: Notebooks under the analysis/ directory and preprocessing.ipynb, which prepare data and derive insights.
- Model Development: Jupyter notebooks in the models/ directory and model_GB.ipynb for training, with the resulting gradient boosting model saved as gradient_boosting_model.pkl.
- Web Application: The app.py file that runs the Streamlit web app where user inputs get processed and predictions are made.
- Deployment Infrastructure: Dockerfile and docker-compose.yml that containerize the entire application for reproducibility and easy deployment.

b. Relationships and Data Flow:
- The preprocessed data flows into the model training components where multiple ML models are experimented with and finally the gradient boosting model is chosen and saved.
- At runtime, the Streamlit application loads the serialized model. It accepts user data via a form, processes the input, and makes churn predictions using the model.
- The entire system is containerized using Docker, ensuring that dependencies and environments are consistent.

c. Architectural Patterns and Key Technologies:
- Clear separation of concerns: Data ingestion/preprocessing, model training, and user interface are distinct modules.
- Use of containerization (Docker) to isolate and deploy the entire system.
- Emphasis on interactive data visualization and rapid prototyping using Jupyter Notebooks.
- Application built using Python with core libraries like Pandas, NumPy for data manipulation; Matplotlib, Seaborn for visualization; Scikit-learn for model training; and Streamlit for the web interface.

2. Processing/Modeling Layer: Indicate EDA, data preprocessing, model experimentation (using multiple algorithms) and final model selection – highlight the gradient boosting model as the core component.
3. Presentation/Deployment Layer: Show the Streamlit web application acting as the user interface, along with the Docker container that encapsulates the entire application stack.

##### Final Advice
- Encourage the principal software engineer to be as detailed as possible, capturing every module and its interactions. Even seemingly ancillary components such as EDA notebooks are part of understanding the full data pipeline.
- Remember that while simplification is important, capturing these essential architectural elements ensures clarity and aids in maintenance and potential scaling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        DS1["\"internet_service_churn.csv\""]:::data
        DS2["\"preprocessed_dataset.csv\""]:::data
    end

    %% Data Processing & EDA Layer
    subgraph "Data Processing & EDA"
        PN["\"preprocessing.ipynb\""]:::notebook
        A1["\"analisis_K.ipynb\""]:::notebook
        A2["\"analysis_artem.ipynb\""]:::notebook
        A3["\"analysis_yuli.ipynb\""]:::notebook
    end

    %% Model Training & Selection Layer
    subgraph "Model Training"
        LR["\"Logistic Regression Notebook\""]:::notebook
        DT["\"Decision Tree Notebook\""]:::notebook
        RF["\"Random Forest Notebook\""]:::notebook
        GB["\"Gradient Boosting Notebook\""]:::notebook
        GBModel["\"gradient_boosting_model.pkl\""]:::model
    end

    %% Presentation/Deployment Layer
    subgraph "Deployment Infrastructure"
        D1["\"Dockerfile\""]:::deployment
        D2["\"docker-compose.yml\""]:::deployment
        D3["\"requirements.txt\""]:::deployment
        DC["\"Docker Container\""]:::container
    end

    SWA["\"Streamlit Web App\""]:::webapp

    %% Data Flow Connections
    DS1 -->|"processes"| PN
    PN -->|"produces"| DS2
    DS1 -->|"analyzes"| A1
    DS1 -->|"analyzes"| A2
    DS1 -->|"analyzes"| A3

    DS2 -->|"trains"| LR
    DS2 -->|"trains"| DT
    DS2 -->|"trains"| RF
    DS2 -->|"trains"| GB
    GB -->|"selects"| GBModel

    GBModel -->|"serves to"| SWA

    D1 --> DC
    D2 --> DC
    D3 --> DC
    DC -->|"runs"| SWA

    %% Click Events
    click DS1 "https://github.com/jamleston/telecom-project/blob/main/internet_service_churn.csv"
    click DS2 "https://github.com/jamleston/telecom-project/blob/main/preprocessed_dataset.csv"
    click PN "https://github.com/jamleston/telecom-project/blob/main/preprocessing.ipynb"
    click A1 "https://github.com/jamleston/telecom-project/blob/main/analysis/analisis_K.ipynb"
    click A2 "https://github.com/jamleston/telecom-project/blob/main/analysis/analysis_artem.ipynb"
    click A3 "https://github.com/jamleston/telecom-project/blob/main/analysis/analysis_yuli.ipynb"
    click LR "https://github.com/jamleston/telecom-project/blob/main/models/model_logistic_regression.ipynb"
    click DT "https://github.com/jamleston/telecom-project/blob/main/models/model_decision_tree.ipynb"
    click RF "https://github.com/jamleston/telecom-project/blob/main/models/model_RF.ipynb"
    click GB "https://github.com/jamleston/telecom-project/blob/main/model_GB.ipynb"
    click GBModel "https://github.com/jamleston/telecom-project/blob/main/gradient_boosting_model.pkl"
    click SWA "https://github.com/jamleston/telecom-project/blob/main/app.py"
    click D1 "https://github.com/jamleston/telecom-project/tree/main/Dockerfile"
    click D2 "https://github.com/jamleston/telecom-project/blob/main/docker-compose.yml"
    click D3 "https://github.com/jamleston/telecom-project/blob/main/requirements.txt"

    %% Styles
    classDef data fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef notebook fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef model fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef deployment fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef webapp fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef container fill:#ccf5ff,stroke:#17a2b8,stroke-width:2px;
```
