# naveedqadir/smartedu_classifier architecture

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

- Interactive diagram: https://gitdiagram.com/naveedqadir/smartedu_classifier
- Repository: https://github.com/naveedqadir/smartedu_classifier

## Overview

##### Project Type & Purpose
- This is an end-to-end machine-learning pipeline for classifying student performance into three categories.
- Key stages: synthetic data generation → preprocessing → exploratory data analysis (EDA) → model training & evaluation → model selection → deployment via CLI.

##### File-Structure Analysis
- Top level:
- data/ – raw CSVs
- notebooks/ – Jupyter analysis & EDA
- src/ – Python scripts for dataset generation, training, prediction, utilities
- models/ – saved model artifacts (joblib)
- outputs/ – evaluation plots & reports
- Config/build files: requirements.txt, .gitignore
- No microservices or web/frontend—just a batch-/CLI-based ML pipeline written in Python.

##### README Insights
- Emphasizes CLI for inference and notebook for interactive EDA.

##### Main Components & Interactions
A. Data Layer
- Synthetic Dataset Generator (src/generate_dataset.py)
- data/students.csv
B. Preprocessing
- utils.py: SimpleImputer, StandardScaler, LabelEncoder
C. EDA & Visualization
- notebooks/student_performance.ipynb (inline plots)
- outputs/*.png
D. Model Training
- src/train.py
- Models: LogisticRegression, DecisionTree, RandomForest, KNN, SVC, optional XGBoost
- 5-fold CV + optional GridSearch (--tune)
E. Model Registry
- models/best_model.joblib
- models/preprocessor.joblib
F. Evaluation Outputs
- outputs/model_metrics.csv, confusion_matrix.png, roc_curves.png, etc.
G. Inference (CLI)
- src/predict.py → outputs/predictions.csv or console output

1. Generator → raw CSV
2. CSV → Preprocessor → cleaned data
3. Cleaned data → EDA & Model Training
4. Training → Model Registry + Evaluation Outputs
5. Registry & Preprocessor → CLI Inference → Predictions

##### Architectural Patterns & Principles
- Linear pipeline (ETL → train → deploy)
- Clear separation of concerns: data generation, preprocessing, training, inference
- Reusable utilities (utils.py)
- Pluggable model registry (joblib-based)
- Command-line interface built with argparse
- Notebook mirrors script logic for transparency

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        GEN["Synthetic Dataset Generator"]:::processing
        CSV["students.csv"]:::data
    end

    GEN -->|"students.csv"| CSV

    click GEN "https://github.com/naveedqadir/smartedu_classifier/blob/main/src/generate_dataset.py"
    click CSV "https://github.com/naveedqadir/smartedu_classifier/blob/main/data/students.csv"

    %% Modeling Layer
    subgraph "Modeling"
        PRE["Preprocessor\n(utils: Imputer, Scaler, Encoder)"]:::processing
        EDA["EDA Notebook"]:::processing
        TRAIN["Trainer\n(5-fold CV + tuning)"]:::processing
        REG["Model Registry\n(best_model.joblib,\npreprocessor.joblib)"]:::data
        EVAL["Evaluation Outputs\n(metrics.csv,\nconfusion_matrix.png,\nroc_curves.png)"]:::output
    end

    CSV -->|"raw CSV"| PRE
    PRE -->|"cleaned data"| EDA
    PRE -->|"cleaned data"| TRAIN
    TRAIN -->|"best_model.joblib"| REG
    TRAIN -->|"evaluation artifacts"| EVAL

    click PRE "https://github.com/naveedqadir/smartedu_classifier/blob/main/src/utils.py"
    click EDA "https://github.com/naveedqadir/smartedu_classifier/blob/main/notebooks/student_performance.ipynb"
    click TRAIN "https://github.com/naveedqadir/smartedu_classifier/blob/main/src/train.py"

    %% Deployment Layer
    subgraph "Deployment"
        CLI["CLI Predictor\n(src/predict.py)"]:::cli
        PRED["predictions.csv / console"]:::output
    end

    REG -->|"model + preprocessor"| CLI
    PRE -->|"preprocessor"| CLI
    CLI -->|"predictions"| PRED

    click CLI "https://github.com/naveedqadir/smartedu_classifier/blob/main/src/predict.py"

    %% Project Files
    subgraph "Project Files"
        RD["README.md"]:::external
        REQ["requirements.txt"]:::external
    end

    click RD "https://github.com/naveedqadir/smartedu_classifier/blob/main/README.md"
    click REQ "https://github.com/naveedqadir/smartedu_classifier/blob/main/requirements.txt"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#333,stroke-width:1px
    classDef output fill:#FFA500,stroke:#333,stroke-width:1px
    classDef cli fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
