# muhammadahmadsaaim/learnlytics architecture

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

- Interactive diagram: https://gitdiagram.com/muhammadahmadsaaim/learnlytics
- Repository: https://github.com/muhammadahmadsaaim/learnlytics

## Overview

##### Project Type and Purpose
- This is a full-stack, web-based student grade prediction system.
- The core use case is: take academic and behavioral inputs via a React frontend → send them to a Python backend → run a trained ML model → return a grade prediction.

##### File Structure
Top-Level
- `backend/` – REST API server & model-serving logic.
- `frontend/` – React single-page application.
- `data/` – Dataset (CSV) and data-creation script.
- `LearnLytics.ipynb` – Jupyter notebook for EDA, preprocessing, training, evaluation.
Backend Subtree
- `app.py` – Flask (or FastAPI) server entrypoint.
- `model/student_grade_predictor.zip` – packaged trained model.
- `requirements.txt` – Python dependencies.
Frontend Subtree
- `src/` – React components (`App.js`, `LearnLyticsForm.jsx`).
- `public/` – Static assets (`index.html`, `manifest.json`).
- `package.json` & `tailwind.config.js` – JS dependencies & styling config.

##### README for Additional Insights
- Backend serves on `localhost:8000`, optionally exposed via ngrok.
- Frontend is configured to call that backend URL.
- The notebook drives all data science work but is not part of the runtime system.

##### Main Components & Their Relationships
a. Data Layer
- Student CSV & data.py → used offline in the notebook.
- Trained model artifacts stored under `backend/model/`.
b. Model-Serving Layer
- Python API (Flask/FastAPI) in `backend/app.py` loads the unzipped model and exposes prediction endpoints.
c. Web Layer
- React app in `frontend/src` collects user inputs (academic + behavioral) and calls the backend’s REST endpoint.
d. External/Tooling
- ngrok (optional) – exposes backend to the internet.
- Jupyter Notebook – development artifact for EDA and retraining.

Data Flow
1. User enters features in the browser.
2. Frontend issues HTTP POST to `/predict` on the backend.
3. Backend loads model → returns JSON with predicted grade.
4. Frontend displays the result.

##### Architectural Patterns & Design Principles
- Layered separation: Presentation (React), Application (Flask/FastAPI), Data/Model (persisted ML artifact).
- API-driven communication over HTTP/JSON.
- Single responsibility: backend only serves ML predictions; frontend only handles UI/UX.
- Configurability: backend URL is injected at build/time into the React app (environment variable or hard-coded).

## Diagram (Mermaid)

```mermaid
flowchart TB
    title["LearnLytics System Architecture"]

    %% Offline/Data Science
    subgraph "Offline/Data Science"
        direction TB
        Notebook["Jupyter Notebook: LearnLytics.ipynb"]:::offline
        DataScript["data.py"]:::offline
        Dataset["student_dataset.csv"]:::offline
    end

    %% Production Environment
    subgraph "Production"
        direction TB

        subgraph "Web Layer"
            direction TB
            ReactApp["React SPA"]:::ui
        end

        subgraph "Model-Serving Layer"
            direction TB
            API["Python REST API"]:::api
            ModelArtifact["ML Model Artifact"]:::data
        end

        Ngrok["ngrok Tunnel"]:::external
    end

    %% Interactions
    User["End User"]:::external
    User -->|"Input Features"| ReactApp
    ReactApp -->|"HTTP POST /predict"| API
    API -->|"Loads & Infers"| ModelArtifact
    API -->|"HTTP 200 JSON"| ReactApp
    API -.->|"Optional Tunnel"| Ngrok

    %% Legend
    subgraph Legend
        direction LR
        A["UI Components"]:::ui
        B["API Components"]:::api
        C["Data/Model Artifacts"]:::data
        D["Offline/Development"]:::offline
        E["External/Cloud"]:::external
    end

    %% Click Events
    click Notebook "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/LearnLytics.ipynb"
    click DataScript "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/data/data.py"
    click Dataset "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/data/student_dataset.csv"
    click ModelArtifact "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/backend/model/student_grade_predictor.zip"
    click API "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/backend/app.py"
    click ReactApp "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/frontend/src/App.js"
    click ReactApp "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/frontend/src/LearnLyticsForm.jsx"
    click ReactApp "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/frontend/src/index.js"
    click ReactApp "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/frontend/public/index.html"
    click ReactApp "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/frontend/public/manifest.json"
    click ReactApp "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/frontend/tailwind.config.js"
    click ReactApp "https://github.com/muhammadahmadsaaim/learnlytics/blob/main/frontend/package.json"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef api fill:#FFE5B4,stroke:#d18b00,stroke-width:1px
    classDef data fill:#E2F0D9,stroke:#2e7d32,stroke-width:1px
    classDef offline fill:#F1F1F1,stroke:#999999,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#E8EAF6,stroke:#5c6bc0,stroke-width:1px,stroke-dasharray: 2 2
```
