# zenml-io/vscode-zenml architecture

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

- Interactive diagram: https://gitdiagram.com/zenml-io/vscode-zenml
- Repository: https://github.com/zenml-io/vscode-zenml

## Overview

##### Project type and purpose
- This is a Visual Studio Code extension that integrates with the ZenML Python library to provide an in-IDE MLOps experience.
- It ships both TypeScript code (the VSCode “client” extension) and a bundled Python LSP server that communicates over JSON-RPC/stdin-stdout.

##### File structure
- Top level:
– src/ – all TypeScript sources for commands, views, services, common utilities, and the extension entry point
– bundled/tool/ – Python LSP server implementation and ZenML wrappers
– resources/ – static assets (CSS/JS) used in Webviews (DAG viewer, forms)
– scripts/, .github/, configuration files – build, lint, CI/CD pipeline definitions
- src/commands & src/views: implement the UI and command handlers in VSCode’s extension host
- src/services: event bus, LSP client wrapper, and the central “ZenExtension” orchestrator
- bundled/tool: LSP server uses ZenML Python SDK and watchdog to reflect real-time state

##### README for additional insights
- Uses the Language Server Protocol to synchronize with ZenML in the user’s Python environment
- Watches the file system for configuration changes (watchdog)
- Renders DAGs in a VSCode Webview and provides Activity Bar tree views for servers, projects, stacks, pipelines, models

##### Main components and their relationships
a. VSCode Extension Host (TypeScript)
– UI layer: Activity Bar views, Webview panels, Status Bar entries
– Command handlers: user actions mapped to commands in src/commands
– Services: EventBus, LSClient (the JSON-RPC client), ZenExtension orchestrator
b. Python LSP Server (bundled/tool)
– Exposes JSON-RPC endpoints for listing servers, stacks, pipelines, models, and for rendering DAGs
– Uses ZenML SDK to query and modify the user’s ZenML environment
– Uses watchdog to watch ZenML config files and sends notifications to the client on change
c. ZenML Core (external dependency)
– The Python library providing the actual MLOps functionality
d. File System Watcher (watchdog)
– Notifies the LSP server of changes in ZenML config, triggering JSON-RPC notifications
e. VSCode API
– Commands, tree data providers, Webview panels, status bar items

[User Click] → VSCode Command Handler → EventBus → LSClient → Python LSP Server
Python LSP Server → (ZoenML SDK) → ZenML Core → returns data
Python LSP Server → JSON-RPC Notification → LSClient → EventBus → UI Update
DAG Render: Command handler → LSClient → LSP server → returns graph data → Webview panel in VSCode

##### Architectural patterns and design principles
- Separation of concerns: UI (commands/views) vs. orchestration (services) vs. data source (LSP server)
- Event-driven communication within the extension (EventBus)
- JSON-RPC client–server pattern for cross-process comms
- Plugin–host model: VSCode extension host (client) + external Python process (LSP server)
- Micro-frontends in Webviews (DAG view, forms) loaded from resources/

##### Elements
- Labels for each component/module (e.g., EventBus, LSClient, Webview panel, LSP server)
– Core services (EventBus, LSClient) in another
– Python server and SDK in a third

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% VSCode Extension Host Process
    subgraph "VSCode Extension Host" 
        direction TB

        %% UI Layer
        subgraph "UI Layer" 
            direction TB
            User["User Interaction"]:::external
            Commands["Command Handlers"]:::ui
            Views["Activity Bar & StatusBar & Webviews"]:::ui
        end

        %% Services Layer
        subgraph "Core Services" 
            direction TB
            EventBus["EventBus"]:::services
            LSClient["LSClient (JSON-RPC)"]:::services
            ZenExtension["ZenExtension Orchestrator"]:::services
        end

        %% Common Utilities
        subgraph "Common Utilities & API" 
            direction TB
            APIAdapter["vscodeapi.ts & utils"]:::services
        end

    end

    %% Python LSP Server Process
    subgraph "Python LSP Server (Child Process)" 
        direction TB
        Runner["lsp_runner.py"]:::python
        ServerCore["lsp_server.py"]:::python
        JSONRPC["lsp_jsonrpc.py & lsp_utils.py"]:::python
        ZenHandlers["lsp_zenml.py"]:::python
        ZenClient["zenml_client.py"]:::python
        ZenWrappers["zenml_wrappers.py"]:::python
        ZenSerializers["zenml_serializers.py"]:::python
        ZenGrapher["zenml_grapher.py"]:::python
        Watcher["zen_watcher.py"]:::python
        Helpers["constants.py, lazy_import.py, type_hints.py"]:::python
    end

    %% External Dependencies
    ZenMLCore["ZenML Core\n(Python Library)"]:::external
    FileSystem["File System\n(Config files)"]:::external

    %% Data Flows
    User -->|"invoke command"| Commands
    Commands --> EventBus
    EventBus --> LSClient
    LSClient -->|"JSON-RPC"| Runner
    Runner --> ServerCore
    ServerCore --> JSONRPC
    JSONRPC --> ZenHandlers
    ZenHandlers --> ZenClient
    ZenClient --> ZenWrappers
    ZenWrappers --> ZenSerializers
    ZenSerializers --> ZenGrapher
    ZenGrapher --> ZenMLCore
    Watcher --> ServerCore
    FileSystem --> Watcher
    ServerCore -->|"SDK calls"| ZenMLCore
    ServerCore -->|"notifications"| LSClient
    LSClient --> EventBus
    EventBus --> Views

    %% Click Events for VSCode Extension
    click User "https://github.com/zenml-io/vscode-zenml/blob/develop/src/extension.ts"
    click Commands "https://github.com/zenml-io/vscode-zenml/tree/develop/src/commands"
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/activityBar"
    click EventBus "https://github.com/zenml-io/vscode-zenml/blob/develop/src/services/EventBus.ts"
    click LSClient "https://github.com/zenml-io/vscode-zenml/blob/develop/src/services/LSClient.ts"
    click ZenExtension "https://github.com/zenml-io/vscode-zenml/blob/develop/src/services/ZenExtension.ts"
    click APIAdapter "https://github.com/zenml-io/vscode-zenml/blob/develop/src/common/vscodeapi.ts"

    %% Click Events for Commands
    click Commands "https://github.com/zenml-io/vscode-zenml/tree/develop/src/commands/components"
    click Commands "https://github.com/zenml-io/vscode-zenml/tree/develop/src/commands/environment"
    click Commands "https://github.com/zenml-io/vscode-zenml/tree/develop/src/commands/models"
    click Commands "https://github.com/zenml-io/vscode-zenml/tree/develop/src/commands/pipelines"
    click Commands "https://github.com/zenml-io/vscode-zenml/tree/develop/src/commands/projects"
    click Commands "https://github.com/zenml-io/vscode-zenml/tree/develop/src/commands/server"
    click Commands "https://github.com/zenml-io/vscode-zenml/tree/develop/src/commands/stack"

    %% Click Events for Views
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/activityBar/componentView"
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/activityBar/environmentView"
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/activityBar/modelView"
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/activityBar/pipelineView"
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/activityBar/projectView"
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/activityBar/serverView"
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/activityBar/stackView"
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/activityBar/common"
    click Views "https://github.com/zenml-io/vscode-zenml/tree/develop/src/views/panel/panelView"
    click Views "https://github.com/zenml-io/vscode-zenml/blob/develop/src/common/WebviewBase.ts"
    click Views "https://github.com/zenml-io/vscode-zenml/blob/develop/src/views/statusBar/index.ts"

    %% Click Events for Python LSP Server
    click Runner "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/lsp_runner.py"
    click ServerCore "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/lsp_server.py"
    click JSONRPC "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/lsp_jsonrpc.py"
    click JSONRPC "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/lsp_utils.py"
    click ZenHandlers "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/lsp_zenml.py"
    click ZenClient "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/zenml_client.py"
    click ZenWrappers "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/zenml_wrappers.py"
    click ZenSerializers "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/zenml_serializers.py"
    click ZenGrapher "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/zenml_grapher.py"
    click Watcher "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/zen_watcher.py"
    click Helpers "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/constants.py"
    click Helpers "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/lazy_import.py"
    click Helpers "https://github.com/zenml-io/vscode-zenml/blob/develop/bundled/tool/type_hints.py"

    %% Styles
    classDef ui fill:#FFD966,stroke:#333,stroke-width:1px
    classDef services fill:#9FC5E8,stroke:#333,stroke-width:1px
    classDef python fill:#B6D7A8,stroke:#333,stroke-width:1px
    classDef external fill:#D9D2E9,stroke:#333,stroke-width:1px
```
