How chili-epfl/jupyter-analytics-dashboard works
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).