# chili-epfl/jupyter-analytics-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/chili-epfl/jupyter-analytics-dashboard
- Repository: https://github.com/chili-epfl/jupyter-analytics-dashboard

## Overview

##### Project type and purpose
- This is a **JupyterLab extension** (full-stack plugin) that provides real-time visualizations of learning analytics collected from users’ interactions in notebooks.
- It comprises a **Python server extension** (handlers, REST/WebSocket endpoints) and a **TypeScript/React frontend extension** (UI components, Redux store).

##### File structure
Top-level split:
- **jupyterlab_unianalytics_dashboard/** – Python package providing server-side handlers.
- **schema/** – JSON schemas for plugin and endpoint definitions.
- **ui-tests/** + **conftest.py**, **tests/** – integration and unit tests for server, frontend, and end-to-end.
- Config & build files: `setup.py`, `pyproject.toml`, `package.json`, `babel.config.js`, `jest.config.js`, `tsconfig.json`, GitHub workflows, Binder environment.

##### Readme insights
- Talks about communication with an external **Backend** (Jupyter Analytics backend service) and real-time telemetry from the Telemetry component.
- Emphasizes frontend (JupyterLab) & server extension (Python) pairing.
- Testing via Pytest (server), Jest (frontend), Playwright/Galata (integration).

##### Main components
a. **JupyterLab Host** – the environment that loads extensions.
b. **Frontend Extension** (in `src/…`)
– React/TSX components: side-dashboard, toc-dashboard, chat-dashboard, playback widgets, panel manager
– **Redux store** (actions, reducers)
– **WebSocketManager** for real-time updates
– **Plugins** (`plugins/*.ts[x]`): register commands, API routes, notebook upload, login, push updates
– **Widget extensions**: buttons that hook into notebook toolbar
c. **Jupyter Server Extension** (in `jupyterlab_unianalytics_dashboard/handlers.py`)
– Exposes HTTP endpoints and WebSocket endpoints to the frontend
– Serves the built JS/CSS assets
d. **External Backend Service** (outside this repo)
– Receives telemetry data (from Telemetry component)
– Provides persisted analytics via REST or WebSocket
– Stores data in a database
e. **Telemetry Collector** (from Telemetry project)
– Embedded in the notebook kernel or frontend
– Streams user-event data to the backend

##### Relationships & data flows
- **Frontend ↔ Server Extension**
– Static asset loading (extension install)
– API calls (fetch dashboards, metadata)
– WebSocket for live updates
- **Server Extension ↔ External Backend**
– Proxies or authenticates requests
– Pushes telemetry events
– Retrieves analytics in real time
- **Telemetry Collector → External Backend**
– Direct event ingestion pipeline
- **User Interactions → Telemetry → Dashboard**
– User edits/runs cells → Telemetry data sent → Backend processes → Frontend dashboard updates via WebSocket

##### Architectural patterns & design principles
- **Plugin-based architecture**: both server and client are Jupyter extensions with clear registration points.
- **Separation of concerns**: React UI vs. server handlers vs. external service.
- **Flux/Redux** for predictable state management in UI.
- **Asynchronous streams** (WebSocket) for real-time updates.
- **Schema-driven** API (JSON schemas under `schema/`).
- **Test layering**: unit, integration, end-to-end (Pytest, Jest, Playwright/Galata).

##### Technologies & frameworks to annotate
- Frontend: TypeScript, React, Redux, Jest, Galata, Playwright
- Build/tools: jlpm/Yarn, Webpack (via JupyterLab), Babel, tsconfig
- Server: Python 3, pytest, Tornado (Jupyter Server)
- CI/CD: GitHub Actions, Binder
- Packaging: setuptools (`setup.py`), pip installable, JupyterLab extension commands

##### Final checklist
- All major components labeled clearly.
- Call out key directories (e.g., `src/side-dashboard`, `jupyterlab_unianalytics_dashboard/handlers.py`, `schema/endpoint.json`).
- Build/deploy flow: development mode (jlpm watch, jupyter lab), CI (GitHub Actions), release (pip package).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layers
    JLab["JupyterLab Host"]:::host

    subgraph "Frontend Extension" 
        direction TB
        FE_Index["Entry Point\nsrc/index.ts"]:::frontend
        subgraph "UI Components" 
            direction TB
            SD["Side Dashboard\nsrc/side-dashboard/"]:::frontend
            TD["TOC Dashboard\nsrc/toc-dashboard/"]:::frontend
            CD["Chat Dashboard\nsrc/chat-dashboard/"]:::frontend
        end
        subgraph "Widgets & Real-time" 
            direction TB
            DW["Dashboard Widgets\nsrc/dashboard-widgets/"]:::frontend
            WS["WebSocketManager\nsrc/dashboard-widgets/WebsocketManager.ts"]:::frontend
        end
        subgraph "Widget Extensions" 
            direction TB
            WE["Notebook Toolbar Buttons\nsrc/widget-extensions/"]:::frontend
        end
        subgraph "State Management" 
            direction TB
            RS["Redux Store\nsrc/redux/store.ts"]:::frontend
            RR["Reducers\nsrc/redux/reducers/"]:::frontend
        end
        subgraph "Plugins" 
            direction TB
            PL["src/plugins/"]:::frontend
        end
    end

    subgraph "Server Extension" 
        direction TB
        SE_Init["Package Init\njupyterlab_unianalytics_dashboard/__init__.py"]:::server
        SE_Handlers["Handlers\njupyterlab_unianalytics_dashboard/handlers.py"]:::server
        SE_Tests["Server Tests\njupyterlab_unianalytics_dashboard/tests/test_handlers.py"]:::server
    end

    EXB["External Backend Service"]:::external
    TC["Telemetry Collector"]:::external
    DB["Analytics DB"]:::external
    SC["JSON Schemas\nschema/"]:::config
    CFG["Config & Packaging"]:::config
    TESTS["Integration & UI Tests\nui-tests/, conftest.py"]:::config

    %% Data Flows
    JLab -->|"loads extension"| FE_Index
    FE_Index -->|"registers plugins"| PL
    FE_Index -->|"renders UI"| SD
    FE_Index -->|"renders UI"| TD
    FE_Index -->|"renders UI"| CD
    SD -->|"updates via"| WS
    TD -->|"updates via"| WS
    CD -->|"updates via"| WS
    WS -->|"WS Stream"| SE_Handlers
    FE_Index -->|"REST API calls"| SE_Handlers
    SE_Handlers -->|"proxies HTTP/WS"| EXB
    TC -->|"events stream"| EXB
    EXB -->|"stores data"| DB
    EXB -->|"provides analytics"| SE_Handlers
    SC -->|"defines API schemas"| SE_Handlers
    SC -->|"defines plugin schemas"| FE_Index
    CFG -.->|"build/deploy"| FE_Index
    CFG -.->|"packaging"| SE_Init
    TESTS -.->|"tests coverage"| FE_Index
    TESTS -.->|"tests coverage"| SE_Handlers

    %% Click Events
    click FE_Index "https://github.com/chili-epfl/jupyter-analytics-dashboard/blob/main/src/index.ts"
    click SD "https://github.com/chili-epfl/jupyter-analytics-dashboard/tree/main/src/side-dashboard/"
    click TD "https://github.com/chili-epfl/jupyter-analytics-dashboard/tree/main/src/toc-dashboard/"
    click CD "https://github.com/chili-epfl/jupyter-analytics-dashboard/tree/main/src/chat-dashboard/"
    click DW "https://github.com/chili-epfl/jupyter-analytics-dashboard/tree/main/src/dashboard-widgets/"
    click WS "https://github.com/chili-epfl/jupyter-analytics-dashboard/blob/main/src/dashboard-widgets/WebsocketManager.ts"
    click WE "https://github.com/chili-epfl/jupyter-analytics-dashboard/tree/main/src/widget-extensions/"
    click RS "https://github.com/chili-epfl/jupyter-analytics-dashboard/blob/main/src/redux/store.ts"
    click RR "https://github.com/chili-epfl/jupyter-analytics-dashboard/tree/main/src/redux/reducers/"
    click PL "https://github.com/chili-epfl/jupyter-analytics-dashboard/tree/main/src/plugins/"
    click SE_Init "https://github.com/chili-epfl/jupyter-analytics-dashboard/blob/main/jupyterlab_unianalytics_dashboard/__init__.py"
    click SE_Handlers "https://github.com/chili-epfl/jupyter-analytics-dashboard/blob/main/jupyterlab_unianalytics_dashboard/handlers.py"
    click SE_Tests "https://github.com/chili-epfl/jupyter-analytics-dashboard/blob/main/jupyterlab_unianalytics_dashboard/tests/test_handlers.py"
    click SC "https://github.com/chili-epfl/jupyter-analytics-dashboard/tree/main/schema/"
    click CFG "https://github.com/chili-epfl/jupyter-analytics-dashboard/blob/main/package.json"
    click TESTS "https://github.com/chili-epfl/jupyter-analytics-dashboard/tree/main/ui-tests/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
    classDef server fill:#E6FFDA,stroke:#2C662D,stroke-width:2px
    classDef external fill:#FFE8B3,stroke:#B36B00,stroke-width:2px
    classDef config fill:#F0F0F0,stroke:#666666,stroke-width:1px
    classDef host fill:#CCCCCC,stroke:#333333,stroke-width:2px,stroke-dasharray: 5 5
```
