# stonky-boi/dream11-interiit-practice architecture

> Architecture diagram of the GitHub repository stonky-boi/dream11-interiit-practice, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stonky-boi/dream11-interiit-practice
- Repository: https://github.com/stonky-boi/dream11-interiit-practice

## Overview

##### Project type and purpose
- This is a full-stack AI/ML application for generating fantasy cricket team recommendations.
- It implements a data pipeline (download → feature engineering), model training (baseline + ensemble), model storage, and two user interfaces (Streamlit-based UI and a standalone React/TypeScript frontend).

##### File structure
- Top-level “data_processing” folder contains scripts to download raw Cricsheet data and engineer features (no leakage).
- “model” folder contains training (train_model.py) and inference (predict_model.py) logic.
- “model_artifacts” holds serialized model files, weights, and metadata.
- “UI” folder holds Streamlit apps: product_ui.py (team builder) and model_ui.py (evaluation).
- “frontend” folder is a React/Vite/TypeScript application with components, hooks, styles and configuration.
- “data/raw” and “data/processed” directories store CSV/JSON data, while “docs” stores generated plots.
- main_app.py is the Streamlit entry point tying the ML inference and UI together.

##### Extract architectural insights from README
- The system is logically divided into layers:
– Data Layer (Cricsheet integration)
– Data Processing Pipeline (download + feature engineering)
– Machine Learning Layer (temporal train/val/test split, ensemble training, inference)
– Application Layer (Streamlit UIs + React frontend)
– Visualization Layer (auto-generated analytical plots)
- Technologies include Python (pandas, scikit-learn, XGBoost, LightGBM, CatBoost, Streamlit), React/TypeScript, Vite, Tailwind CSS, cricketstats library.

##### Main components
- External Data Source: Cricsheet (ball-by-ball JSON)
- Data Ingestion Service: data_download.py → raw CSV files in data/raw
- Feature Engineering Service: feature_engineering.py → processed dataset in data/processed
- Model Training Service: train_model.py → serialized models + visualization outputs in model_artifacts & docs
- Inference Service: predict_model.py (exposed via main_app.py)
- Streamlit UI: product_ui.py + model_ui.py (invoked by main_app.py)
- React Frontend: static hosting of built assets (index.html + src components)
- Storage: local file system or object store for raw data, processed data, model artifacts, and docs

##### Architectural patterns and design principles
- Layered architecture separating data, ML, and presentation concerns
- Pipeline pattern for sequential data download → feature engineering → model training
- Temporal validation strategy enforced in train_model.py to prevent data leakage
- Modular code organization: each folder encapsulates a distinct responsibility
- Reproducibility: deterministic pipeline with date‐based splits and saved metadata

##### Technologies, frameworks, and libraries
- Python services: pandas, scikit-learn, XGBoost, LightGBM, CatBoost, cricketstats, Streamlit
- React frontend: Vite, TypeScript, Tailwind CSS, custom UI components
- Storage: local file system (data/, model_artifacts/, docs/)
- Build & deployment: Node/npm for frontend, pip/venv for Python, Streamlit server

##### Elements
- Clear labels for each service/component (e.g., “Feature Engineering Service”).
– Blue rectangles for processing services,
– Orange rectangles for UI components,
- An optional note or callout showing the enforced date cutoff at the training stage.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Cricsheet["Cricsheet (External Data)"]:::external
        DataIngestion["Data Ingestion Service"]:::service
        RawStorage["Raw Data Storage\ndata/raw/"]:::storage
        FeatureEng["Feature Engineering Service"]:::service
        ProcessedStorage["Processed Data Storage\ndata/processed/"]:::storage
    end

    %% ML Layer
    subgraph "Machine Learning Layer"
        direction TB
        ModelTraining["Model Training Service"]:::service
        DateCutoffNote["Note: Temporal date cutoff enforced"]:::note
        ModelArtifacts["Model Artifacts Storage\nmodel_artifacts/"]:::storage
        Inference["Inference Service"]:::service
        Orchestrator["Orchestrator\n(main_app.py)"]:::service
    end

    %% UI Layer
    subgraph "Application Layer"
        direction TB
        StreamlitUI["Streamlit UI\nproduct_ui.py & model_ui.py"]:::ui
        ReactFE["React Frontend\n(static assets)"]:::ui
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        direction TB
        Docs["Docs Storage\ndocs/"]:::doc
    end

    %% Connections
    Cricsheet -->|"download"| DataIngestion
    DataIngestion -->|"store raw data"| RawStorage
    RawStorage -->|"load raw data"| FeatureEng
    FeatureEng -->|"store processed data"| ProcessedStorage
    ProcessedStorage -->|"training input"| ModelTraining
    ModelTraining --> DateCutoffNote
    ModelTraining -->|"store models & metadata"| ModelArtifacts
    ModelArtifacts -->|"load model"| Inference
    Inference -->|"serve predictions"| Orchestrator
    Orchestrator -->|"serves UI"| StreamlitUI
    Orchestrator -->|"serves UI"| ReactFE
    Inference <-->|"API calls"| StreamlitUI
    Inference <-->|"API calls"| ReactFE
    ModelTraining -->|"generate plots"| Docs

    %% Click Events
    click DataIngestion "https://github.com/stonky-boi/dream11-interiit-practice/blob/main/data_processing/data_download.py"
    click FeatureEng "https://github.com/stonky-boi/dream11-interiit-practice/blob/main/data_processing/feature_engineering.py"
    click ModelTraining "https://github.com/stonky-boi/dream11-interiit-practice/blob/main/model/train_model.py"
    click Inference "https://github.com/stonky-boi/dream11-interiit-practice/blob/main/model/predict_model.py"
    click Orchestrator "https://github.com/stonky-boi/dream11-interiit-practice/blob/main/main_app.py"
    click StreamlitUI "https://github.com/stonky-boi/dream11-interiit-practice/blob/main/UI/product_ui.py"
    click StreamlitUI "https://github.com/stonky-boi/dream11-interiit-practice/blob/main/UI/model_ui.py"
    click ReactFE "https://github.com/stonky-boi/dream11-interiit-practice/blob/main/frontend/index.html"
    click RawStorage "https://github.com/stonky-boi/dream11-interiit-practice/tree/main/data/raw/"
    click ProcessedStorage "https://github.com/stonky-boi/dream11-interiit-practice/tree/main/data/processed/"
    click ModelArtifacts "https://github.com/stonky-boi/dream11-interiit-practice/tree/main/model_artifacts/"
    click Docs "https://github.com/stonky-boi/dream11-interiit-practice/tree/main/docs/"

    %% Styles
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px;
    classDef service fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef doc fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef note fill:#FFFFFF,stroke:#888,stroke-dasharray: 2 2;
```
