# chandraprakash-tripathi/ai_learning_companion architecture

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

- Interactive diagram: https://gitdiagram.com/chandraprakash-tripathi/ai_learning_companion
- Repository: https://github.com/chandraprakash-tripathi/ai_learning_companion

## Overview

##### Project type and purpose
- This is a full-stack, educational “ML playground” web application called **AI Learning Companion**, which uses Streamlit for the UI (frontend) and Flask for the ML-computation engine (backend).
- Its goal is to let users interactively explore gradient descent, activation functions, hyperparameters, and model comparisons via real-time visualizations.

##### File structure
- Top-level directories:
- **backend/** – Flask app entry point (`app.py`), core ML logic (`ml_models.py`), helper utilities (`utils.py`), and plotting functions (`visualizations.py`).
- **frontend/** – Streamlit UI files (`0_Home.py`), organized into `components/` (reusable UI modules) and `pages/` (each ML topic as a separate Streamlit page).
- **tests/** – unit tests for the ML logic (`test_ml_models.py`).
- Config files: `requirements.txt` lists Python dependencies; no DB or external microservices are present.

##### README for architecture clues
- Confirms a **two-tier architecture**:
Streamlit UI ↔ REST API ↔ ML engine
- Tech stack: Flask for the API, scikit-learn/NumPy/Pandas for ML, Matplotlib/Altair for charts.

##### Main components and their relationships
a. **Streamlit Frontend**
- Entry point: `frontend/0_Home.py`
- UI Components: sliders, controls, math panels, sidebar (`frontend/components/...`).
- Pages for each feature (gradient descent, activation functions, etc.)
b. **Flask Backend API**
- Single Flask service in `backend/app.py` exposing endpoints (e.g., `/gradient_descent`, `/activation`).
- Receives JSON payloads containing user-adjusted parameters.
c. **ML Engine & Visualization Modules**
- **ml_models.py**: implements core algorithms (gradient descent, model training).
- **utils.py**: shared helpers (data generation, normalization).
- **visualizations.py**: wraps Matplotlib/Altair logic to produce plots or data arrays.
d. **External Libraries**
- scikit-learn, NumPy, Pandas for data and model computations.
- Matplotlib/Altair for chart generation.

Data Flow:
User → Streamlit UI (HTTP POST/GET) → Flask API → ML Engine (ml_models + utils) → Visualization module → Flask returns data/images → Streamlit renders plots

##### Architectural patterns & design principles
- **Separation of concerns**: UI logic is fully decoupled from computation logic.
- **RESTful API**: simple JSON-over-HTTP interface between frontend and backend.
- **Modular code**: backend ML logic split into cohesive modules; frontend UI split into components and pages.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User (Browser)"]:::user

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Streamlit["Streamlit Server"]:::frontend
        Home["Home (0_Home.py)"]:::frontend
        subgraph "UI Components"
            direction TB
            Activations["activations.py"]:::frontend
            BackendClient["backend_client.py"]:::frontend
            Constants["constants.py"]:::frontend
            MathPanels["math_panels.py"]:::frontend
            SessionState["session_state.py"]:::frontend
            UIControls["ui_controls.py"]:::frontend
            UISidebar["ui_sidebar.py"]:::frontend
            VizWrappers["viz.py"]:::frontend
        end
        subgraph "Pages"
            direction TB
            GDPage["1_gradient_descent.py"]:::frontend
            AFPage["2_activation_functions.py"]:::frontend
            HTPPage["3_HYPERPARAMETER_TUNING.py"]:::frontend
            CMPPage["4_COMPARE_MODEL.py"]:::frontend
        end
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        FlaskAPI["Flask API (app.py)"]:::backend
        MLModels["ML Models (ml_models.py)"]:::ml
        Utils["Utils (utils.py)"]:::ml
        Visualizations["Visualizations (visualizations.py)"]:::ml
    end

    %% Tests
    Tests["Unit Tests (test_ml_models.py)"]:::test

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        SKlearn["scikit-learn"]:::external
        NumPy["NumPy"]:::external
        Pandas["Pandas"]:::external
        Matplotlib["Matplotlib"]:::external
        Altair["Altair"]:::external
    end

    %% Connections
    User -->|"interacts via Streamlit UI"| Streamlit
    Streamlit -->|loads| Home
    Home -->|uses| Activations
    Home -->|uses| BackendClient
    Home -->|uses| Constants
    Home -->|uses| MathPanels
    Home -->|uses| SessionState
    Home -->|uses| UIControls
    Home -->|uses| UISidebar
    Home -->|uses| VizWrappers

    Streamlit -->|navigates to| GDPage
    Streamlit -->|navigates to| AFPage
    Streamlit -->|navigates to| HTPPage
    Streamlit -->|navigates to| CMPPage

    BackendClient -->|"HTTP JSON"| FlaskAPI
    FlaskAPI -->|"calls"| MLModels
    FlaskAPI -->|"calls"| Utils
    FlaskAPI -->|"calls"| Visualizations

    MLModels -->|uses| SKlearn
    Utils -->|uses| Pandas
    Utils -->|uses| NumPy
    Visualizations -->|renders| Matplotlib
    Visualizations -->|renders| Altair

    FlaskAPI -->|"returns JSON/plots"| BackendClient
    BackendClient -->|passes data| Streamlit
    Streamlit -->|renders plots| VizWrappers

    MLModels -->|tested by| Tests

    %% Click Events
    click Home "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/0_Home.py"
    click Activations "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/components/activations.py"
    click BackendClient "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/components/backend_client.py"
    click Constants "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/components/constants.py"
    click MathPanels "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/components/math_panels.py"
    click SessionState "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/components/session_state.py"
    click UIControls "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/components/ui_controls.py"
    click UISidebar "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/components/ui_sidebar.py"
    click VizWrappers "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/components/viz.py"
    click GDPage "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/pages/1_gradient_descent.py"
    click AFPage "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/pages/2_activation_functions.py"
    click HTPPage "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/pages/3_HYPERPARAMETER_TUNING.py"
    click CMPPage "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/frontend/pages/4_COMPARE_MODEL.py"
    click FlaskAPI "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/backend/app.py"
    click MLModels "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/backend/ml_models.py"
    click Utils "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/backend/utils.py"
    click Visualizations "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/backend/visualizations.py"
    click Tests "https://github.com/chandraprakash-tripathi/ai_learning_companion/blob/master1/tests/test_ml_models.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#FFA500,stroke:#000,stroke-width:1px
    classDef ml fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFFACD,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
    classDef user fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef test fill:#FFB6C1,stroke:#000,stroke-width:1px
    %% Legend
    subgraph "Legend"
        direction LR
        A["Frontend Components"]:::frontend
        B["Backend/API"]:::backend
        C["ML Modules"]:::ml
        D["External Libraries"]:::external
        E["User"]:::user
        F["Tests"]:::test
    end
```
