# zaaachos/overfit-level-i architecture

> Architecture diagram of the GitHub repository zaaachos/overfit-level-i, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zaaachos/overfit-level-i
- Repository: https://github.com/zaaachos/overfit-level-i

## Overview

##### ML Development (notebook folder)
- The “notebook” folder contains the Jupyter notebook(s) used for extensive exploratory data analysis, feature engineering, and model training (as evidenced by the submission_notebook.ipynb and associated CSV data files).
- This part of the project examines the dataset, develops and tunes the machine learning model (using approaches like CatBoost, XGBoost, and LightGBM), and even incorporates further analysis (e.g., with SHAP).
- Essentially, this is your model development and validation layer.

##### Web Application Deployment (webapp folder)
- The “webapp” folder encapsulates the Flask application for deploying the predictive model.
- Key files include:
- app.py: The main Flask application entry point that defines routes such as /obesityRiskForm and /predict.
- Dockerfile and docker-compose.yml: These files define how the application container is built and orchestrated, enabling portability and deployment (e.g., to Docker Hub, HuggingFace Spaces, or other cloud platforms).
- models folder: Contains the serialized, production-ready machine learning model (model_best.pickle) used for making predictions.
- templates folder: Holds HTML templates for the application’s UI, ensuring the frontend part of the web interface is served properly.
- utils package: Provides supporting functionality (e.g., dataset loading, feature engineering, and model-specific routines) which abstracts the core prediction logic from the main app.

A. Identify the Main Components:
1. Data & Model Training Environment:
- Notebook/EDA Environment: Includes data files (train.csv, test.csv, sample_submission.csv) and the Jupyter Notebook containing the data analysis and modeling steps.
- Trained Model: The output of the notebook work – a model stored as model_best.pickle.
2. Web Application:
- Flask Application (app.py): Acts as the controller handling incoming HTTP requests.
- Utility Layer (webapp/utils): Contains helper modules for dataset operations, custom prediction logic, and feature engineering.
- Templates (webapp/templates): Provides the frontend interface for input (obesityRiskForm.html) and output (predict.html).
3. Containerization & Deployment:
- Docker Configuration: Includes Dockerfile and docker-compose.yml, responsible for containerizing the application.
- External Deployment Service: In this case, the project is deployed on platforms like HuggingFace Spaces as indicated in the README.

B. Determine the Relationships and Data Flow:
- Data Flow Start: The user interacts with the web interface (via the HTML forms served by Flask).
- Upon receiving input, app.py processes the request and calls necessary utility functions (from the utils module) which in turn load and use the pre-trained model (model_best.pickle) to compute predictions.
- The results are rendered back on a new template (predict.html) and shown to the user.
- While the notebook is not part of the runtime, it is intrinsic to the development lifecycle (model training and evaluation) and can be represented as a preparatory step in the overall architecture.
- The Docker setup encapsulates the entire web application, ensuring the environment is consistent and portable across deployments.

C. Highlight Architectural Patterns and Design Principles:
- Separation of Concerns: The project is split between the data science (model training in the notebook) and the application deployment (in the webapp folder). The Flask app clearly separates concerns by having dedicated templates, a utility layer, and a modular structure.
- Containerization: Docker is used to encapsulate the application, promoting consistency across environments.
- Modularity & Reusability: The use of modules in the “utils” directory indicates good practice in keeping reusable code separate from the application logic.

D. Include Relevant Technologies, Frameworks, and Tools:
- Flask for the backend web application.
- Docker (Dockerfile and docker-compose) for containerization.
- Python libraries: scikit-learn, CatBoost, XGBoost, LightGBM, and SHAP (as part of model training), evident from the README.
- HTML templates (for the user interface).
- Jupyter Notebook for model development and analysis.

1. Create distinct blocks for each major component:
- Notebook & Model Training (left side): Include blocks for the data files and the EDA/modeling notebook indicating “Data Exploration”, “Feature Engineering”, and “Model Training”.
- Web Application (center): A block for the Flask app (app.py) that routes to various web endpoints, blocks for the “Utils” (custom_model.py, dataset.py, feature_engineering.py), and blocks for the “Templates” (UI forms).
- Containerization & Deployment (right side): Clearly label blocks for Docker components (Dockerfile, docker-compose) and external deployment (e.g., HuggingFace Spaces cloud service).
- Backend/Logic (Flask and utilities)
- Frontend (HTML templates/UI)
- Model Development Components (Notebook and Data)
- Infrastructure (Docker components and deployment targets)
4. Detail by annotating any important middleware or orchestration logic (e.g., note that Docker is responsible for encapsulating the web application so that it runs the same locally as it does in production).

F. Final Advice:
- Emphasis on the architecture’s flow from data ingestion and model training to prediction serving, ensuring that each stage is clearly demarcated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Notebook & Model Training Section
    subgraph "Notebook & Model Training"
        N1["Jupyter Notebook (submission_notebook.ipynb)"]:::ml
        N2["Data Files (data folder)"]:::ml
        N3["Trained Model (output model)"]:::ml
    end

    %% Web Application Section
    subgraph "Web Application"
        F1["Flask App (app.py)"]:::controller
        subgraph "Utility Layer (Utils)"
            U1["custom_model.py"]:::utils
            U2["dataset.py"]:::utils
            U3["feature_engineering.py"]:::utils
        end
        subgraph "Templates (Frontend UI)"
            T1["obesityRiskForm.html"]:::frontend
            T2["predict.html"]:::frontend
        end
    end

    %% Containerization & Deployment Section
    subgraph "Containerization & Deployment"
        D1["Dockerfile"]:::container
        D2["docker-compose.yml"]:::container
        DEP["External Deployment (HuggingFace Spaces)"]:::cloud
    end

    %% User Interaction
    UB["User Browser"]:::user

    %% Data & Model Training Flow
    N2 -->|"provides data"| N1
    N1 -->|"produces"| N3

    %% Integration of Trained Model with Web Application
    N3 -->|"loaded by"| F1

    %% Web Application Prediction Flow
    UB -->|"accesses UI"| T1
    T1 -->|"submits data"| F1
    F1 -->|"calls prediction"| U1
    U1 -->|"loads model"| N3
    F1 -->|"renders output"| T2
    T2 -->|"displays result"| UB

    %% Containerization & Deployment Flow
    D1 -->|"builds container"| DEP
    D2 -->|"orchestrates container"| DEP
    DEP -->|"deploys service"| F1

    %% Click Events
    click N1 "https://github.com/zaaachos/overfit-level-i/blob/master/notebook/submission_notebook.ipynb"
    click N2 "https://github.com/zaaachos/overfit-level-i/tree/master/notebook/data"
    click N3 "https://github.com/zaaachos/overfit-level-i/blob/master/webapp/models/model_best.pickle"
    click F1 "https://github.com/zaaachos/overfit-level-i/blob/master/webapp/app.py"
    click U1 "https://github.com/zaaachos/overfit-level-i/blob/master/webapp/utils/custom_model.py"
    click U2 "https://github.com/zaaachos/overfit-level-i/blob/master/webapp/utils/dataset.py"
    click U3 "https://github.com/zaaachos/overfit-level-i/blob/master/webapp/utils/feature_engineering.py"
    click T1 "https://github.com/zaaachos/overfit-level-i/blob/master/webapp/templates/obesityRiskForm.html"
    click T2 "https://github.com/zaaachos/overfit-level-i/blob/master/webapp/templates/predict.html"
    click D1 "https://github.com/zaaachos/overfit-level-i/tree/master/webapp/Dockerfile"
    click D2 "https://github.com/zaaachos/overfit-level-i/blob/master/webapp/docker-compose.yml"

    %% Styling Classes
    classDef ml fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef controller fill:#fad7a0,stroke:#333,stroke-width:2px;
    classDef utils fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef frontend fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef container fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef cloud fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef user fill:#f7dc6f,stroke:#333,stroke-width:2px;
```
