# shopify/ruby-lsp architecture

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

- Interactive diagram: https://gitdiagram.com/shopify/ruby-lsp
- Repository: https://github.com/shopify/ruby-lsp

## Overview

##### Project Type and Purpose
- This is a language server implementation for Ruby. It uses the language server protocol to allow editors—especially VS Code—to get features like code completion, definition lookup, diagnostics, formatting, and more.
- Its dual nature appears in both Ruby (core server logic, indexing, request handling) and TypeScript (VS Code extension that communicates with the Ruby process).

##### File Structure Insights
- The top-level directories (e.g., “lib”, “exe”, “bin”, “jekyll”, “vscode”, “sorbet”, “test”) indicate clearly separated concerns:
- “lib/ruby_lsp”: Contains the core server code, listeners for different requests (completion, definition, hover, etc.), response builders, and utilities.
- “lib/ruby_indexer”: Implements indexing functionality to enable fast code lookup, search, and integration with RBS (Ruby signatures).
- “vscode”: Contains the VS Code extension’s source code in TypeScript responsible for client-side integration.
- “jekyll” and “static_docs”: Provide documentation and a website (likely rendered via Jekyll).
- “test”: Contains comprehensive tests for all aspects of the LSP, including integration and functional tests.
- “sorbet”: Contains static type information and RBI files that may be used to ensure type safety.
- The existence of CI/CD workflows in “.github/workflows” and configuration files (like Gemfile, Rakefile, etc.) indicate rigorous build, test, and deployment processes.

a. Clients (Editors and Extensions):
- VS Code Extension (in the “vscode” directory, TypeScript) that communicates with the Ruby LSP.
- Other potential clients via the LSP (as indicated in the README with references to multiple editors).

b. Ruby LSP Server:
- Core Modules:
- Ruby LSP Core (lib/ruby_lsp) with the Base Server, listeners for each language feature (completion, definition, hover, etc.), and request handlers.
- Request modules (found within lib/ruby_lsp/requests) that define how incoming messages are processed.
- Response Builders (in lib/ruby_lsp/response_builders) to construct the final responses.
- Indexing and Analysis:
- “lib/ruby_indexer” for indexing Ruby code, handling declarations, locating references, and processing RBS.
- Integration with RuboCop and static analysis (as seen with the additional “lib/rubocop/cop/ruby_lsp” components).
- Ancillary Features:
- Scripts, configuration for Bundler, and Sandboxing (e.g., “exe/ruby-lsp”, “bin/tapioca”).
- Command-line scripts and report generation utilities.

c. Communication and Data Flow:
- The VS Code extension initiates a Language Server Protocol connection with the Ruby LSP server.
- The server receives requests (e.g., code completion, definition lookup) and delegates to the appropriate request handler or listener.
- Data (such as symbol declarations, diagnostic information, and code indexes) is gathered through the indexer and then packaged by the response builders to be sent back through the LSP connection to the client.

d. Supporting Infrastructure:
- CI/CD workflows configured in “.github/workflows” for testing, publishing, and version bumping.
- Configuration files (e.g., Gemfile, Rakefile) to manage dependencies and build tasks.
- Documentation websites via “jekyll” and static docs in “static_docs”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    A["Code Editors (VS Code & Other LSP Clients)"]:::client

    %% Client Connector (VS Code Extension)
    B["VS Code Extension (Client Connector)"]:::typescript
    click B "https://github.com/shopify/ruby-lsp/tree/main/vscode/"

    %% Communication between Client and Server
    A -->|"Initiates_LSP_Connection"| B

    %% Ruby LSP Server Subgraph
    subgraph "Ruby LSP Server"
        B1["Core Server (Base & Document Handling)"]:::ruby
        click B1 "https://github.com/shopify/ruby-lsp/tree/main/lib/ruby_lsp/"
        B2["Request & Listener Modules"]:::ruby
        click B2 "https://github.com/shopify/ruby-lsp/tree/main/lib/ruby_lsp/requests/"
        B3["Response Builders"]:::ruby
        click B3 "https://github.com/shopify/ruby-lsp/tree/main/lib/ruby_lsp/response_builders/"
        B4["Ruby Indexer"]:::ruby
        click B4 "https://github.com/shopify/ruby-lsp/tree/main/lib/ruby_indexer/"
        B5["RuboCop Integration"]:::ruby
        click B5 "https://github.com/shopify/ruby-lsp/tree/main/lib/rubocop/cop/ruby_lsp/"
    end

    %% Flow within the Ruby LSP Server
    B -->|"Sends_Request"| B1
    B1 -->|"Delegates_to"| B2
    B2 -->|"Interacts_with"| B4
    B4 -->|"Provides_Data_to"| B3
    B3 -->|"Constructs_Response"| B

    %% Supporting Infrastructure Subgraph
    subgraph "Supporting Infrastructure"
        SI1["Testing Framework"]:::infra
        click SI1 "https://github.com/shopify/ruby-lsp/tree/main/test/"
        SI2["Documentation (Jekyll & Static Docs)"]:::docs
        click SI2 "https://github.com/shopify/ruby-lsp/tree/main/jekyll/"
        SI3["CI/CD & Build Configurations"]:::infra
        click SI3 "https://github.com/shopify/ruby-lsp/tree/main/.github/workflows/"
    end

    %% Relationships with Supporting Infrastructure
    SI1 -->|"Validates"| B1
    SI3 -->|"Builds_&_Deploys"| B1
    SI2 -->|"Provides_Docs_for"| B1

    %% Styles
    classDef ruby fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef typescript fill:#e6f2ff,stroke:#0047b3,stroke-width:2px;
    classDef infra fill:#e6ffe6,stroke:#008000,stroke-width:2px;
    classDef docs fill:#fff0b3,stroke:#cc8400,stroke-width:2px;
    classDef client fill:#f0e6ff,stroke:#6600cc,stroke-width:2px;
```
