# wallabyjs/console-ninja architecture

> Architecture diagram of the GitHub repository wallabyjs/console-ninja, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wallabyjs/console-ninja
- Repository: https://github.com/wallabyjs/console-ninja

## Overview

##### Project type and purpose
- Console Ninja is a VS Code extension (a “plugin” for the VS Code editor).
- Its purpose is to capture and display runtime `console.*` output and errors from browser or Node applications directly in your editor, plus provide advanced features (logpoints, tracepoints, MCP server for AI integration, etc.).

##### File structure
- Top-level folders:
- .github – issue templates and config for GitHub
- LICENSE.md, README.md – licensing and documentation
- (No `src` folder shown here, but in a real checkout you would see:)
- src/extension – VS Code extension entry point and commands
- src/client – UI components (hover tooltips, tree-view log viewer)
- src/server – local WebSocket server / MCP server implementation
- src/instrumentation – helpers that patch build-tool modules
- package.json, tsconfig.json, webpack/vite configs – build and deploy scripts

##### README for additional insights
- Architecture hints:
- Integrates with build tools by patching node_modules
- Runs a local WebSocket server on `localhost` for editor <-> app communication
- Provides an MCP server for AI tools (Copilot, Cursor, etc.)
- Two main runtimes: browser and NodeJS

##### Main components
a. VS Code Editor UI
– Inline decorators next to source lines
– Hover tooltips
– Log Viewer panel (tree view)
b. VS Code Extension Host
– Activates on project open
– Registers commands (Start, Pause, Show Output, Add Logpoint, etc.)
– Hosts the WebSocket client and MCP server client
c. Local WebSocket Server
– Listens on `ws://localhost:<port>`
– Bridges instrumented app runtime and extension host
d. Instrumentation Layer (build-tool plugins/patches)
– Intercepts module loading in supported tools (Vite, Webpack, Next.js, Jest, etc.)
– Injects WebSocket client and code wrappers around `console.*`, errors, tracepoints, etc.
e. Application Runtime(s)
– Browser (dev server)
– Node (custom apps, test runners)
– Each communicates to the local WebSocket server
f. External Services
– GitHub Copilot / MCP clients connecting to the built-in MCP server
– (Optional) Firewall/VPN—affects WebSocket connectivity

##### Relationships and interactions
- Developer starts VS Code → activates Console Ninja extension
- Extension spawns/ensures the local WebSocket server is running
- Build tool (e.g. Vite, Webpack) loads patched modules from instrumentation layer
- Instrumented code (in browser or Node) opens a WebSocket connection to localhost
- Runtime `console.log`, errors, tracepoints → sent over WebSocket → Extension Host
- Extension Host updates the Editor UI: inline log tiles, hover tooltips, tree-view log viewer
- User commands in VS Code (e.g. add logpoint, manage license) → sent back via WebSocket or extension API to control instrumentation or MCP server
- MCP server listens on a different port/protocol → AI clients (Copilot, Cursor, etc.) request context (logs, code)

##### Architectural patterns and design principles
- Event-driven, message-based communication (WebSocket events)
- Plugin architecture for build-tool integration (patching modules rather than forking tools)
- Separation of concerns:
- Instrumentation lives in your node_modules patches
- Protocol (WebSocket/MCP) is a thin transport layer
- Editor UI is pure VS Code extension code
- Pluggable MCP server following the Model Context Protocol

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Documentation
    subgraph "Documentation"
        README["README.md"]:::docs
        LICENSE["LICENSE.md"]:::docs
        ISSUE[".github/ISSUE_TEMPLATE"]:::docs
    end

    %% Editor Side
    subgraph "Editor Side"
        direction TB
        EXT_HOST["VS Code Extension Host"]:::frontend
        subgraph "VS Code Editor UI"
            direction TB
            DECORATORS["Inline Decorators"]:::frontend
            TOOLTIPS["Hover Tooltips"]:::frontend
            LOGVIEW["Log Viewer Panel"]:::frontend
        end
        MCP["MCP Server"]:::transport
    end

    %% Runtime Side
    subgraph "Runtime Side"
        direction TB
        BUILD["Build Tools (Vite/Webpack/Next/Jest)"]:::runtime
        INSTR["Instrumentation Layer"]:::runtime
        WS["Local WebSocket Server"]:::transport
        subgraph "Application Runtimes"
            direction TB
            BROWSER["Browser Runtime"]:::runtime
            NODE["Node Runtime"]:::runtime
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        COPILOT["GitHub Copilot / Cursor"]:::external
    end

    %% Relationships
    README -->|references| EXT_HOST
    LICENSE --> EXT_HOST
    ISSUE --> EXT_HOST

    EXT_HOST -->|"registers commands"| DECORATORS
    EXT_HOST -->|updates| LOGVIEW
    EXT_HOST -->|updates| TOOLTIPS
    EXT_HOST -->|"hosts client"| WS
    EXT_HOST -->|"hosts"| MCP

    BUILD -->|"patch modules"| INSTR
    INSTR -->|"injects WebSocket client"| BROWSER
    INSTR -->|"injects WebSocket client"| NODE

    BROWSER -->|"socket.emit(log)"| WS
    NODE -->|"socket.emit(log)"| WS
    WS -->|"messages"| EXT_HOST

    DECORATORS -->|commands| WS
    LOGVIEW -->|commands| WS

    COPILOT -->|"MCP request"| MCP
    MCP -->|"context"| EXT_HOST

    %% Click Events
    click README "https://github.com/wallabyjs/console-ninja/blob/main/README.md"
    click LICENSE "https://github.com/wallabyjs/console-ninja/blob/main/LICENSE.md"
    click ISSUE "https://github.com/wallabyjs/console-ninja/tree/main/.github/ISSUE_TEMPLATE"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#2196f3
    classDef runtime fill:#c8e6c9,stroke:#4caf50
    classDef transport fill:#eeeeee,stroke:#9e9e9e
    classDef external fill:#ffe0b2,stroke:#ff9800
    classDef docs fill:#e0f7fa,stroke:#006064
```
