# elorie-bernard-lacroix/smartstudy architecture

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

- Interactive diagram: https://gitdiagram.com/elorie-bernard-lacroix/smartstudy
- Repository: https://github.com/elorie-bernard-lacroix/smartstudy

## Overview

##### Main Components
- Data Layer: This includes the “data” directory, which is divided into raw, interim, and processed data. It also appears that CSV files are the primary data format.
- Data Processing & Exploration: The “notebooks” directory demonstrates the steps in data preprocessing, exploratory data analysis, baseline modeling, and more. This layer shows the progression from raw data to cleaned/processed datasets.
- Model Building: The “models” directory contains standalone scripts (e.g., random-forest.py, xgboost.py) which signal experimentation or prototype code. In addition, the “smartstudy/modeling” submodule includes “train.py” and “predict.py” to encapsulate the model training and inference functions.
- Application Logic & Utilities: The “smartstudy” package (with files like config.py, dataset.py, features.py, and plots.py) contains the building blocks for configuring experiments, handling datasets, generating features, and creating visualizations. This utility layer ties the data and modeling components together.
- Documentation & Reporting: With directories like “docs”, “reports”, and “references”, which house both user/documentation content and figures, there is a clear separation for user guidance and project reporting.
- Additional Resources: There are also process documents (in process-documentation) that outline the proposal and brainstorming details, which inform overall design decisions.

##### Relationships & Interactions
- The raw data enters the pipeline through the Data Layer (data/raw) and is subsequently processed (data/interim) to create processed datasets stored in both “data/processed” and within the notebooks.
- The processed data is used by the application modules in the smartstudy package (specifically dataset.py and features.py) to prepare inputs for modeling.
- The modeling layer then uses these features to train models (via train.py) and generate predictions (via predict.py). The scripts in the “models” directory provide specific implementations.
- Notebooks act as a bridge by documenting each stage (from preprocessing, EDA, training, evaluation, to specialized experiments like GPT text generation).
- Reports and visualizations are generated via plots.py and are further compiled into final reports in the “reports” folder.
- Configuration and settings are managed by config.py and the project-level configuration files (pyproject.toml, requirements.txt, setup.cfg, Makefile) which help in project setup and reproducibility.

##### Architectural Patterns & Design Principles
- This project follows a modular design: distinct directories are used for data, model code, and notebooks. This separation enhances clarity and maintainability.
- There is a clear implementation of a data-driven pipeline where data is ingested, cleaned, transformed, and then fed to machine learning models.
- Experimentation is encouraged through the extensive use of Jupyter notebooks, allowing interactive and iterative development.
- The use of a configuration file (config.py) indicates an effort to decouple code logic from parameters, a good design practice.

- Do not oversimplify—ensure every critical step is represented: raw data entry, preprocessing pipelines, model training/inference, evaluation, and reporting are all essential.
- Avoid too few components: even if some modules are simple utility scripts, include them as they contribute to the overall architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        RD["Raw Data (CSV)"] 
        ID["Interim Data"]
        PD["Processed Data"]
    end

    %% Data Processing & Exploration
    subgraph "Data Processing & Exploration"
        NB["Notebooks"]
    end

    %% Model Building
    subgraph "Model Building"
        subgraph "Experimental Models"
            RF["RandomForest"]
            XGB["XGBoost"]
        end
        subgraph "Production Modeling"
            Train["Train Module"]
            Predict["Predict Module"]
        end
    end

    %% Application Logic & Utilities
    subgraph "Application Logic & Utilities"
        Config["Config"]
        DS["Dataset"]
        Feat["Features"]
        Plots["Plots"]
    end

    %% Documentation & Reporting
    subgraph "Documentation & Reporting"
        Docs["Documentation"]
        Reports["Reporting"]
    end

    %% Additional Resources
    ProcessDoc["Process Documentation"]

    %% Data Flow
    RD --> ID
    ID --> PD
    PD --> NB
    PD --> DS
    PD --> Feat
    Config --> DS
    Config --> Feat
    DS --> Train
    Feat --> Train
    Train --> Predict
    Predict --> Plots
    Plots --> Reports
    NB --> Plots
    PD --> RF
    PD --> XGB
    NB --> RF
    NB --> XGB

    %% Click Events
    click RD "https://github.com/elorie-bernard-lacroix/smartstudy/tree/main/SmartStudy/data/raw"
    click ID "https://github.com/elorie-bernard-lacroix/smartstudy/tree/main/SmartStudy/data/interim"
    click PD "https://github.com/elorie-bernard-lacroix/smartstudy/tree/main/SmartStudy/data/processed"
    click NB "https://github.com/elorie-bernard-lacroix/smartstudy/tree/main/SmartStudy/notebooks"
    click RF "https://github.com/elorie-bernard-lacroix/smartstudy/blob/main/SmartStudy/models/random-forest.py"
    click XGB "https://github.com/elorie-bernard-lacroix/smartstudy/blob/main/SmartStudy/models/xgboost.py"
    click Train "https://github.com/elorie-bernard-lacroix/smartstudy/blob/main/SmartStudy/smartstudy/modeling/train.py"
    click Predict "https://github.com/elorie-bernard-lacroix/smartstudy/blob/main/SmartStudy/smartstudy/modeling/predict.py"
    click Config "https://github.com/elorie-bernard-lacroix/smartstudy/blob/main/SmartStudy/smartstudy/config.py"
    click DS "https://github.com/elorie-bernard-lacroix/smartstudy/blob/main/SmartStudy/smartstudy/dataset.py"
    click Feat "https://github.com/elorie-bernard-lacroix/smartstudy/blob/main/SmartStudy/smartstudy/features.py"
    click Plots "https://github.com/elorie-bernard-lacroix/smartstudy/blob/main/SmartStudy/smartstudy/plots.py"
    click Docs "https://github.com/elorie-bernard-lacroix/smartstudy/tree/main/SmartStudy/docs"
    click Reports "https://github.com/elorie-bernard-lacroix/smartstudy/tree/main/SmartStudy/reports"
    click ProcessDoc "https://github.com/elorie-bernard-lacroix/smartstudy/tree/main/process-documentation"

    %% Styles
    classDef dataLayer fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef notebooks fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef expModel fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef prodModel fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef appLogic fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef docs fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef processDoc fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;

    class RD,ID,PD dataLayer;
    class NB notebooks;
    class RF,XGB expModel;
    class Train,Predict prodModel;
    class Config,DS,Feat,Plots appLogic;
    class Docs,Reports docs;
    class ProcessDoc processDoc;
```
