# chili-epfl/jupyter-analytics-telemetry architecture

> Architecture diagram of the GitHub repository chili-epfl/jupyter-analytics-telemetry, 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-telemetry
- Repository: https://github.com/chili-epfl/jupyter-analytics-telemetry

## Overview

##### Project type and purpose
- This is a hybrid JupyterLab extension combining a TypeScript‐based frontend plugin and a Python‐based server extension.
- Its purpose is to capture user interaction events in JupyterLab (e.g., cell execution, focus changes, notebook alterations) and forward them to a remote analytics backend.

##### File structure
- Top-level language divisions:
- Python server extension:
– setup.py, pyproject.toml, jupyterlab_unianalytics_telemetry/handlers.py (HTTP handlers), schema/ (JSON schemas for endpoints and settings)
– tests via pytest (conftest.py, jupyterlab_unianalytics_telemetry/tests)
- TypeScript frontend extension:
– src/ (PanelManager.ts, dataCollectionPlugin.ts, handler.ts, api.ts, trackers/, websocket/)
– tsconfig.json, babel.config.js, jest.config.js (build and test configurations)
- CI/DevOps:
– .github/workflows, binder/, ui-tests/ (Playwright/Galata integration tests)
- Architectural patterns: JupyterLab plugin API for frontend; event‐driven “disposable” trackers; a server‐side HTTP API; WebSocket support for chat or streaming; schema‐driven validation of payloads.

##### README for additional insights
- Confirms the dual (frontend + server) extension model.
- Lists dependencies (JupyterLab ≥3.1.0, Node.js, Python, yarn/jlpm).
- Describes testing: Jest for frontend, pytest for server, Playwright/Galata for integration.

a. Main components:
– JupyterLab Notebook UI (host application)
– Frontend Telemetry Plugin
- Trackers (AlterationDisposable, ExecutionDisposable, FocusDisposable, etc.)
- DataCollectionPlugin orchestrator
- API module & WebsocketManager
– Jupyter Server Extension
- HTTP/WebSocket handlers (handlers.py)
- JSON schemas (schema/*.json) for request validation
– Remote Analytics Backend (external service)
– CI/CD and Testing (GitHub Actions, Binder, Playwright)
b. Relationships & interactions:
1. User interacts with Notebook UI → Frontend Trackers emit events
2. DataCollectionPlugin batches/forms events → handler.ts
3. handler.ts calls api.ts (HTTP POST to server extension endpoints) or WebsocketManager (long‐lived channel)
4. Server extension handlers validate against schema and forward payload to Remote Analytics Backend
5. CI/CD pipelines validate build, tests, integration tests
c. Architectural patterns & principles:
– Plugin modularity: clear separation of trackers, data collection, transport
– Event‐driven flow with disposables to manage lifecycle
– Schema‐driven validation for robustness
– Dual‐language split: frontend vs. server responsibility
d. Key technologies:
– TypeScript, JupyterLab Plugin API, WebSocket, Jest
– Python, Jupyter Server Extension API, FastAPI‐style handlers (pytest testing)
– JSON Schema, Playwright/Galata for UI tests, GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Telemetry Plugin"
        classDef frontend fill:#DDEEFF,stroke:#99CCFF;
        Notebook["JupyterLab Notebook UI"]:::frontend
        PanelMgr["PanelManager"]:::frontend
        subgraph "Trackers"
            ADisp["AlterationDisposable"]:::frontend
            CMD["CellMappingDisposable"]:::frontend
            EDisp["ExecutionDisposable"]:::frontend
            FDisp["FocusDisposable"]:::frontend
        end
        DataPlugin["DataCollectionPlugin"]:::frontend
        HandlerTS["handler.ts"]:::frontend
        API["api.ts (HTTP)"]:::frontend
        subgraph "WebSocket Support"
            WSManager["WebsocketManager"]:::frontend
            ChatExt["ChatExtension"]:::frontend
        end
        Icons["Icons & Styles"]:::frontend
    end

    %% Server Layer
    subgraph "Jupyter Server Extension"
        classDef server fill:#EEFFDD,stroke:#99CC66;
        HandlersPy["handlers.py"]:::server
        subgraph "JSON Schemas"
            EndpointSchema["endpoint.json"]:::server
            DialogSchema["dialogShownSettings.json"]:::server
            SettingsSchema["settings.json"]:::server
        end
    end

    %% External Backend
    subgraph "Remote Analytics Backend"
        classDef external fill:#FFEEDD,stroke:#FFCC99;
        Analytics["Analytics Service"]:::external
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Tests"
        classDef ci fill:#F0F0F0,stroke:#CCCCCC;
        subgraph "GitHub Actions Workflows"
            BuildWF["build.yml"]:::ci
            CheckRelWF["check-release.yml"]:::ci
            PublishRelWF["publish-release.yml"]:::ci
            PrepRelWF["prep-release.yml"]:::ci
            UpdateIntWF["update-integration-tests.yml"]:::ci
            BinderWF["binder-on-pr.yml"]:::ci
            LabelWF["enforce-label.yml"]:::ci
        end
        FrontendTests["Jest Tests"]:::ci
        PythonTests["pytest Tests"]:::ci
        IntegrationTests["Playwright/Galata Tests"]:::ci
    end

    %% Connections - Frontend
    Notebook -->|emits events| ADisp
    Notebook -->|emits events| CMD
    Notebook -->|emits events| EDisp
    Notebook -->|emits events| FDisp
    ADisp --> DataPlugin
    CMD --> DataPlugin
    EDisp --> DataPlugin
    FDisp --> DataPlugin
    DataPlugin --> HandlerTS
    HandlerTS -->|POST events| API
    HandlerTS -->|open WS| WSManager
    WSManager --> ChatExt

    %% Frontend to Server
    API -->|"HTTP API"| HandlersPy
    WSManager -->|"WebSocket"| HandlersPy

    %% Server to External
    HandlersPy -->|"validate & forward"| Analytics
    EndpointSchema --> HandlersPy
    DialogSchema --> HandlersPy
    SettingsSchema --> HandlersPy

    %% CI/CD flows
    BuildWF --> FrontendTests
    BuildWF --> PythonTests
    BuildWF --> IntegrationTests
    CheckRelWF --> BuildWF
    PublishRelWF --> CheckRelWF
    PrepRelWF --> PublishRelWF
    UpdateIntWF --> IntegrationTests
    BinderWF --> IntegrationTests
    LabelWF --> BuildWF

    %% Click Events - Frontend
    click PanelMgr "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/PanelManager.ts"
    click ADisp "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/trackers/AlterationDisposable.ts"
    click CMD "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/trackers/CellMappingDisposable.ts"
    click EDisp "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/trackers/ExecutionDisposable.ts"
    click FDisp "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/trackers/FocusDisposable.ts"
    click DataPlugin "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/dataCollectionPlugin.ts"
    click HandlerTS "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/handler.ts"
    click API "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/api.ts"
    click WSManager "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/websocket/WebsocketManager.ts"
    click ChatExt "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/websocket/ChatExtension.ts"
    click Icons "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/icons/index.ts"
    click Icons "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/style/base.css"
    click Icons "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/style/index.css"
    click Icons "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/style/index.js"
    click Notebook "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/index.ts"
    click FrontendTests "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/jest.config.js"
    click FrontendTests "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/src/__tests__/jupyterlab_unianalytics_telemetry.spec.ts"

    %% Click Events - Server
    click HandlersPy "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/jupyterlab_unianalytics_telemetry/handlers.py"
    click PythonTests "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/conftest.py"
    click PythonTests "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/jupyterlab_unianalytics_telemetry/tests/test_handlers.py"
    click EndpointSchema "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/schema/endpoint.json"
    click DialogSchema "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/schema/dialogShownSettings.json"
    click SettingsSchema "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/schema/settings.json"

    %% Click Events - Build & Config
    click BuildWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/.github/workflows/build.yml"
    click CheckRelWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/.github/workflows/check-release.yml"
    click PublishRelWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/.github/workflows/publish-release.yml"
    click PrepRelWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/.github/workflows/prep-release.yml"
    click UpdateIntWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/.github/workflows/update-integration-tests.yml"
    click BinderWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/.github/workflows/binder-on-pr.yml"
    click LabelWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/.github/workflows/enforce-label.yml"
    click BuildWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/tsconfig.json"
    click BuildWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/tsconfig.test.json"
    click BuildWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/babel.config.js"
    click BuildWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/pyproject.toml"
    click BuildWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/setup.py"
    click BuildWF "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/package.json"
    click IntegrationTests "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/ui-tests/playwright.config.js"
    click IntegrationTests "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/ui-tests/tests/jupyterlab_unianalytics_telemetry.spec.ts"
    click IntegrationTests "https://github.com/chili-epfl/jupyter-analytics-telemetry/blob/main/ui-tests/jupyter_server_test_config.py"

    %% Styles
    class Notebook,PanelMgr,ADisp,CMD,EDisp,FDisp,DataPlugin,HandlerTS,API,WSManager,ChatExt,Icons frontend
    class HandlersPy,EndpointSchema,DialogSchema,SettingsSchema server
    class Analytics external
    class BuildWF,CheckRelWF,PublishRelWF,PrepRelWF,UpdateIntWF,BinderWF,LabelWF,FrontendTests,PythonTests,IntegrationTests ci
```
