# microsoft/vscode-jupyter architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/vscode-jupyter
- Repository: https://github.com/microsoft/vscode-jupyter

## Overview

##### Project’s Primary Purpose and Components
- The README makes it clear that the extension’s role is to offer notebook functionality within VS Code. It bridges VS Code’s native notebook UI with backend kernel management (via Jupyter kernels) and supports associated features (like code execution, IPyWidgets, debugging, exporting, etc.).
- The file tree confirms a layered design structure with directories such as “src” (which contains core code for notebooks, kernels, commands, and interactive-window implementations) and “webviews” (responsible for the rich interactive UI components of the extension).

##### Key Components to Highlight
A. VS Code Host & Extension Environment
– Represent the VS Code workbench where the extension is installed.
– Show how VS Code’s API calls into extension entry points such as “src/extension.node.ts” and “src/extension.web.ts.”

B. Notebook UI and Interactive Window
– Include components for managing notebook sessions and interactive windows (found in directories like “src/notebooks” and “src/interactive-window”).
– Emphasize features such as cell editing, rendering (using built-in VS Code notebook support), and the diff tool for notebook comparisons.

C. Kernel Management and Communication
– Capture the various kernel-related components under “src/kernels”. This includes mechanisms for:
- Discovering and managing available kernels.
- Connecting to remote Jupyter servers and handling live sessions.
- Managing error conditions (see the “errors” parts) and auto-reconnect functionalities.

D. Webviews for Rendering & Enhanced Notebook Features
– The “src/webviews” directory holds the components for richer UIs like the data explorer, plot viewers, widget renderers, and variable panels.
– Represent these as a separate visual block that communicates with the core extension logic to render results in the browser-like panel.

E. Command, API, and Service Layers
– A number of modules (such as “src/commands.ts”, “src/api.*.d.ts”, “src/platform”, and “src/standalone”) implement the core APIs, commands, and service registries.
– Indicate that these act as the glue between the VS Code host environment, UI components, kernel communication, and even telemetry/logging systems.

F. Build, Configuration, and Dev Environments
– Although not part of the runtime architecture, directories like “build”, “devcontainer”, “.github”, etc., show a well-organized CI/CD, testing, and configuration strategy.

##### Relationships and Communication Flow
- Interaction between UI components (notebook cells, interactive window, webviews) and kernel management modules where code is executed.
- That “Commands and API services” mediate actions like kernel selection, cell execution, and debugging.
- Webview components (data viewers, plotting tools, and variable panels) to both the notebook environment and the rendering services.
- It’s also useful to include the telemetry/logging components as cross-cutting concerns that feed data back to Microsoft’s servers for analytics and debugging.

##### Architectural Patterns and Principles
- There is a clear separation of concerns—a layered architecture in which:
– The presentation layer (VS Code notebooks and webviews) is separated from the service layer (kernel management, command execution) and further from the development tooling (build, CI/CD).
- The modular design (with well-isolated directories for “kernels”, “notebooks”, “webviews”, etc.) implies that each module can be updated or extended independently.
- Robust error handling and auto-reconnect capabilities are evident in the multiple “errors” and “monitor” files under the kernels section.
- The use of dependency injection patterns in the “src/platform/ioc” suggests a design that promotes loose coupling among services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% VS Code Extension Host
    subgraph "VS Code Extension Host"
        extNode["Extension Node"]:::host
        extWeb["Extension Web"]:::host
    end

    %% Notebook UI
    subgraph "Notebook UI"
        nbNotebooks["Notebooks"]:::ui
        nbInteractive["Interactive Window"]:::ui
    end

    %% Commands, API, and Service Layers
    subgraph "Commands/API Services"
        cmdCommands["Commands"]:::api
        apiAPIs["APIs"]:::api
        platPlatform["Platform"]:::api
    end

    %% Kernel Management and Communication
    subgraph "Kernel Management"
        kmKernels["Kernels"]:::kernel
    end

    %% Webview Renderers
    subgraph "Webview Renderers"
        webWebviews["Webviews"]:::webview
    end

    %% Build, Configuration, and Dev Environments (Supporting)
    subgraph "Build & Config"
        buildBuild["Build"]:::build
        devContainer[".devcontainer"]:::build
        github[".github"]:::build
    end

    %% Relationships and Communication Flow
    extNode -->|"init_UI"| nbNotebooks
    extWeb  -->|"init_UI"| nbInteractive

    extNode -->|"command_call"| cmdCommands
    extWeb  -->|"command_call"| cmdCommands

    cmdCommands -->|"execute_cell"| kmKernels
    kmKernels -->|"kernel_response"| cmdCommands

    nbNotebooks -->|"cell_exec"| kmKernels
    kmKernels -->|"update_cell"| nbNotebooks

    cmdCommands -->|"render_result"| webWebviews
    kmKernels  -->|"update_view"| webWebviews
    nbInteractive -->|"widget_interact"| webWebviews

    %% Click Events
    click extNode "https://github.com/microsoft/vscode-jupyter/blob/main/src/extension.node.ts"
    click extWeb "https://github.com/microsoft/vscode-jupyter/blob/main/src/extension.web.ts"
    click nbNotebooks "https://github.com/microsoft/vscode-jupyter/tree/main/src/notebooks"
    click nbInteractive "https://github.com/microsoft/vscode-jupyter/tree/main/src/interactive-window"
    click cmdCommands "https://github.com/microsoft/vscode-jupyter/blob/main/src/commands.ts"
    click apiAPIs "https://github.com/microsoft/vscode-jupyter/blob/main/src/api.d.ts"
    click platPlatform "https://github.com/microsoft/vscode-jupyter/tree/main/src/platform"
    click kmKernels "https://github.com/microsoft/vscode-jupyter/tree/main/src/kernels"
    click webWebviews "https://github.com/microsoft/vscode-jupyter/tree/main/src/webviews"
    click buildBuild "https://github.com/microsoft/vscode-jupyter/tree/main/build"
    click devContainer "https://github.com/microsoft/vscode-jupyter/blob/main/.devcontainer"
    click github "https://github.com/microsoft/vscode-jupyter/blob/main/.github"

    %% Styles
    classDef host fill:#f8c471,stroke:#333,stroke-width:2px;
    classDef ui fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef api fill:#abebc6,stroke:#333,stroke-width:2px;
    classDef kernel fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef webview fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef build fill:#e8daef,stroke:#333,stroke-width:2px;
```
