# microsoft/vscode-mock-debug architecture

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

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

## Overview

##### Main Components
- VS Code Extension Framework: The core of the project is a VS Code extension (files like extension.ts, web-extension.ts) that integrates the debug adapter.
- Debug Adapter Subsystem: This includes the core files (debugAdapter.ts, mockDebug.ts, mockRuntime.ts, activateMockDebug.ts) that simulate debugger behavior (stepping, breakpoints, exceptions, variable access).
- Testing and Sample Workspace: The project includes a test suite (under src/tests) and a sampleWorkspace directory, which provides a sample environment in VS Code.
- Configuration and Build Infrastructure: There are build scripts (in the build folder) and CI/CD workflows (.github/workflows/ci.yml), along with TypeScript configuration (tsconfig.json) that indicate the build and deployment aspects.

##### Relationships and Data Flow
- The extension entry point (extension.ts) registers the debug adapter with VS Code.
- When a user initiates a debug session in VS Code, the extension interacts with the debug adapter (debugAdapter.ts and associated modules) which then simulates debugging functionalities such as stepping and handling exceptions.
- The mock runtime (mockRuntime.ts) and supporting modules (mockDebug.ts, activateMockDebug.ts) provide the actual logic for simulating these debugging actions.
- Testing modules under src/tests validate the behavior of the debug adapter and runtime, ensuring reliability.
- The sampleWorkspace demonstrates the extension's usage in a live VS Code environment.
- Build and CI configurations ensure every update to these components is properly built, tested, and deployed.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is modularized into clear layers—extension activation, debug adapter logic, runtime simulation, and testing.
- Integration with External Systems: It leverages the VS Code Debug Adapter Protocol and VS Code Extension API to interact seamlessly with the host IDE.
- CI/CD and Automated Build: The existence of GitHub workflows and build scripts emphasizes automated testing and deployment processes.

##### Important Technologies, Frameworks, and Libraries
- Visual Studio Code API / Debug Adapter Protocol for integration with VS Code.
- TypeScript as the language for implementing the extension.
- Standard project configuration files (package.json, tsconfig.json) for dependency management and build configuration.
- GitHub Actions for CI/CD as seen in the .github/workflows directory.

##### Conclusion
- Offer a high-level view as well as a zoomed-in look into the core debug adapter logic (from extension activation through runtime simulation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    UI("VS Code UI"):::external

    subgraph "Extension Layer"
        ext("VS Code Extension Entry"):::extension
        web("VS Code Web Extension"):::extension
    end

    subgraph "Debug Adapter Layer"
        da("Debug Adapter Logic"):::debug
        md("Mock Debug Simulation"):::debug
        mr("Mock Runtime"):::debug
        am("Activate Mock Debug"):::debug
    end

    subgraph "Testing & Sample Environment"
        tests("Test Suite"):::test
        sample("Sample Workspace"):::sample
    end

    subgraph "Build & Configuration"
        build("Build Scripts"):::build
        ci("CI Workflow"):::build
        pkg("Package Configuration"):::config
        ts("TypeScript Configuration"):::config
    end

    %% Data flows
    UI -->|"startDebugSession"| ext
    ext -->|"registerAdapter"| da
    da -->|"simulateDebug"| md
    da -->|"initDebug"| am
    md -->|"runtimeCalls"| mr
    da -->|"feedback"| UI

    tests -->|"validateAdapter"| da
    tests -->|"runSimulations"| md

    ext -->|"demonstrateUsage"| sample

    build -->|"triggerBuild"| ext
    ci -->|"runCI"| tests
    pkg -->|"dependency"| ext
    pkg -->|"dependency"| da
    ts -->|"compile"| ext
    ts -->|"compile"| da

    %% Click Events
    click ext "https://github.com/microsoft/vscode-mock-debug/blob/main/src/extension.ts"
    click web "https://github.com/microsoft/vscode-mock-debug/blob/main/src/web-extension.ts"
    click da "https://github.com/microsoft/vscode-mock-debug/blob/main/src/debugAdapter.ts"
    click md "https://github.com/microsoft/vscode-mock-debug/blob/main/src/mockDebug.ts"
    click mr "https://github.com/microsoft/vscode-mock-debug/blob/main/src/mockRuntime.ts"
    click am "https://github.com/microsoft/vscode-mock-debug/blob/main/src/activateMockDebug.ts"
    click tests "https://github.com/microsoft/vscode-mock-debug/tree/main/src/tests"
    click sample "https://github.com/microsoft/vscode-mock-debug/tree/main/sampleWorkspace"
    click build "https://github.com/microsoft/vscode-mock-debug/tree/main/build"
    click ci "https://github.com/microsoft/vscode-mock-debug/blob/main/.github/workflows/ci.yml"
    click pkg "https://github.com/microsoft/vscode-mock-debug/blob/main/package.json"
    click ts "https://github.com/microsoft/vscode-mock-debug/blob/main/tsconfig.json"

    %% Styles
    classDef external fill:#fd7,stroke:#333,stroke-width:2px;
    classDef extension fill:#f9f,stroke:#333,stroke-width:2px;
    classDef debug fill:#bbf,stroke:#333,stroke-width:2px;
    classDef test fill:#bfb,stroke:#333,stroke-width:2px;
    classDef sample fill:#ff9,stroke:#333,stroke-width:2px;
    classDef build fill:#fcf,stroke:#333,stroke-width:2px;
    classDef config fill:#cff,stroke:#333,stroke-width:2px;
```
