# yioneko/vtsls architecture

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

- Interactive diagram: https://gitdiagram.com/yioneko/vtsls
- Repository: https://github.com/yioneko/vtsls

## Overview

##### Project type and purpose
- vtsls is an open-source Language Server Protocol (LSP) wrapper around the TypeScript language features extension shipped with VSCode.
- Its goal is to provide nearly identical TS editing features (completion, diagnostics, code actions, etc.) via a standalone language server while applying minimal patches to stay in sync with upstream updates effortlessly.

##### File structure
Top-level:
- `.github/` & CI/CD files – workflows for testing, publishing, schema updates.
- `package.json`, `pnpm-workspace.yaml` – monorepo managed by pnpm.
- `packages/` – three sub-packages:
– `server/` – the CLI and LSP server bootstrap (bin/vtsls.js, build scripts, `src/`).
– `service/` – core LSP implementation that loads the VSCode extension, applies patches, and delegates LSP requests. Contains:
- `patches/` – diff files to alter upstream extension behavior.
- `scripts/` – build helpers & patch runner.
- `src/service/` – logic mapping LSP methods (completion, inlay hints, code actions) to extension APIs.
- `src/shims/` – wrappers over VSCode extension APIs to surface them in a language-server context.
- `src/share/` & `src/utils/` – shared converters and utilities.
- `tests/` – integration tests against a sample workspace.
– `vscode-fuzzy/` – standalone fuzzy matching utility reused by the service for server-side completion filtering.

##### README for additional insights
- Describes LSP features supported, patching strategy, configuration schema, CLI usage (`vtsls --stdio`), and integration points (e.g., `typescript.selectTypeScriptVersion`).
- Emphasizes minimal patches and near-upstream parity.

##### Main components & their interactions
a. Components
1. LSP Client (editor or other LSP-aware tool)
2. CLI Entrypoint (`vtsls --stdio`)
3. Language Server Core (packages/server)
4. Service Layer (packages/service)
- Patch Manager (applies `patches/*.patch` to the bundled VSCode TS extension)
- Shim Layer (`src/shims/*`)
- Service Handlers (`src/service/*.ts`)
- Shared Converters & Utilities (`src/share`, `src/utils`)
5. Bundled VSCode TypeScript Extension (external code module)
6. TypeScript Server Process (tsserver) – either bundled or workspace version
7. Fuzzy Filtering Library (`vscode-fuzzy`)
8. Configuration Schema (`configuration.schema.json`)
b. Relationships & Data Flow
- The LSP Client ↔️ JSON-RPC over stdio ↔️ CLI Entrypoint
- CLI loads Language Server Core → initializes Service Layer
- Service Layer loads & patches the VSCode extension code, then spins up or communicates with tsserver
- Service Handlers convert incoming LSP requests → calls into shim APIs → underlying extension/tsserver → results back through shim → LSP response
- Completion requests optionally pass candidates through `vscode-fuzzy` for server-side filtering
- Configuration settings (from client) are validated against `configuration.schema.json` and drive behavior (e.g. patch toggles, memory limits)
c. Architectural patterns & principles
- Monorepo with clear package boundaries (server vs service vs utility)
- Adapter/Shim pattern to expose VSCode extension APIs in an LSP context
- Patch/Extension point model to apply minimal diffs to upstream code
- Separation of concerns: CLI vs server runtime vs core service logic vs utilities
d. Key technologies
- Node.js for runtime
- pnpm workspace (monorepo)
- TypeScript for all packages
- Vitest for tests
- JSON-RPC & vscode-language-server libraries
- Upstream VSCode TypeScript extension as a submodule

##### Elements
– Blue for vtsls-owned code (server, service, shims)
– Green for utilities (vscode-fuzzy, utils)
– Grey for external modules (VSCode extension, tsserver, editors)
– Rectangles for runtime components

##### Final advice
- Be very detailed: break the Service Layer into Patch Manager, Shim, Handler, and Utility subsystems.
- Configuration flow: client settings → schema validator → runtime toggles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Client"
        Client["LSP Client (Editor)"]:::external
    end

    Client -->|"JSON-RPC stdio"| CLI["vtsls --stdio"]:::server
    click CLI "https://github.com/yioneko/vtsls/blob/main/packages/server/bin/vtsls.js"

    subgraph "Language Server Core"
        CoreIndex["index.ts"]:::server
        CoreCap["capabilities.ts"]:::server
        CoreBuild["build.js"]:::server
    end
    click CoreIndex "https://github.com/yioneko/vtsls/blob/main/packages/server/src/index.ts"
    click CoreCap "https://github.com/yioneko/vtsls/blob/main/packages/server/src/capabilities.ts"
    click CoreBuild "https://github.com/yioneko/vtsls/blob/main/packages/server/build.js"

    CLI --> CoreIndex

    subgraph "Service Layer"
        direction TB
        subgraph "Patch Manager"
            Patches["*.patch"]:::artifact
            PatchScript["patch.js"]:::service
        end
        subgraph "Shim Layer"
            ShimsDir["src/shims"]:::service
            ShimScript["cjs_shims.js"]:::service
        end
        subgraph "Service Handlers"
            Main["main.ts"]:::service
            Completion["completion.ts"]:::service
            CodeAction["codeAction.ts"]:::service
            Inlay["inlayHint.ts"]:::service
            Delegate["delegate.ts"]:::service
            Protocol["protocol.ts"]:::service
            Types["types.ts"]:::service
            PkgJson["pkgJson.ts"]:::service
        end
        subgraph "Shared Converters & Utilities"
            Share["src/share"]:::util
            Utils["src/utils"]:::util
        end
        Schema["configuration.schema.json"]:::artifact
        Tests["tests"]:::test
    end

    click Patches "https://github.com/yioneko/vtsls/blob/main/packages/service/patches/*.patch"
    click PatchScript "https://github.com/yioneko/vtsls/blob/main/packages/service/scripts/patch.js"
    click ShimsDir "https://github.com/yioneko/vtsls/tree/main/packages/service/src/shims/"
    click ShimScript "https://github.com/yioneko/vtsls/blob/main/packages/service/scripts/cjs_shims.js"
    click Main "https://github.com/yioneko/vtsls/blob/main/packages/service/src/service/main.ts"
    click Completion "https://github.com/yioneko/vtsls/blob/main/packages/service/src/service/completion.ts"
    click CodeAction "https://github.com/yioneko/vtsls/blob/main/packages/service/src/service/codeAction.ts"
    click Inlay "https://github.com/yioneko/vtsls/blob/main/packages/service/src/service/inlayHint.ts"
    click Delegate "https://github.com/yioneko/vtsls/blob/main/packages/service/src/service/delegate.ts"
    click Protocol "https://github.com/yioneko/vtsls/blob/main/packages/service/src/service/protocol.ts"
    click Types "https://github.com/yioneko/vtsls/blob/main/packages/service/src/service/types.ts"
    click PkgJson "https://github.com/yioneko/vtsls/blob/main/packages/service/src/service/pkgJson.ts"
    click Share "https://github.com/yioneko/vtsls/tree/main/packages/service/src/share/"
    click Utils "https://github.com/yioneko/vtsls/tree/main/packages/service/src/utils/"
    click Schema "https://github.com/yioneko/vtsls/blob/main/packages/service/configuration.schema.json"
    click Tests "https://github.com/yioneko/vtsls/tree/main/packages/service/tests/"

    CoreIndex --> PatchScript
    CoreIndex --> ShimsDir
    CoreIndex --> Main

    Patches --> PatchScript --> ShimsDir
    ShimsDir --> Main
    Main --> Completion
    Main --> CodeAction
    Main --> Inlay
    Main --> Delegate
    Main --> Protocol
    Main --> Types
    Main --> PkgJson
    Main --> Share
    Main --> Utils

    Completion -->|"calls fuzzy"| Fuzzy["vscode-fuzzy"]:::util
    click Fuzzy "https://github.com/yioneko/vtsls/tree/main/packages/vscode-fuzzy/"

    Schema -->|"validate settings"| Main
    Tests --> CoreIndex

    subgraph "External Modules"
        ExtExt["VSCode TS Extension"]:::external
        TsServer["TypeScript Server"]:::external
    end

    PatchScript --> ExtExt
    ShimsDir --> ExtExt
    ExtExt --> TsServer
    Main --> TsServer
    Completion --> TsServer

    TsServer --> ShimsDir
    ShimsDir --> CoreIndex
    CoreIndex --> Client

    classDef server fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef service fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef util fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef artifact fill:#f8d7da,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef test fill:#fff3cd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
