# kotlin/kotlin-lsp architecture

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

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

## Overview

##### Project Type and Purpose
- This is a language-server implementation for Kotlin (kotlin-lsp) plus a VS Code extension (kotlin-vscode) and related modules (API definitions, feature plugins, project import).
- It implements the Language Server Protocol (LSP) to provide diagnostics, completion, navigation, code actions, etc., and ships both a standalone LSP server and a VS Code client.

##### High-Level Module Structure
- api.core: Core LSP API interfaces (LSServer, LSWorkspace, LSDocuments, utilities).
- api.features: Definitions of language-server features (completion, hover, diagnostics, symbols, commands).
- features-impl: Concrete implementations of those features in two flavors:
- common: generic implementations (syntax errors, quick-fixes, basic completion, hover).
- kotlin: Kotlin-specific implementations (compiler diagnostics, Kotlin AST-based completion, organize imports, semantic tokens).
- workspace-import: Project-import subsystem (Gradle importers, JSON importer, services).
- kotlin-lsp: The actual server binary wiring: starts LSP over stdio or sockets, hooks into IntelliJ platform.
- kotlin-vscode: VS Code extension (TypeScript) acting as LSP client.
- scripts: Launch wrappers for other editors (neovim, Emacs, Zed).

##### Core Components and Interactions
- LSP Client (VS Code extension / any editor)
↕ JSON-RPC over stdio or sockets
- LSP Server (kotlin-lsp module)
- Uses engine wiring to load modules: api.core + api.features + features-impl/common + features-impl/kotlin + workspace-import
- Receives initialize/file events, dispatches to API interfaces -> feature providers -> implementation.
- Project Import Subsystem
- Called at initialization: workspace-import chooses appropriate importer (Gradle, JSON, JPS) to build an in-memory model.
- Provides project model for diagnostics, completion, symbols.
- IntelliJ Platform & Kotlin Plugin
- Underlying engine for parsing, type-checking, analysis.
- Invoked indirectly by feature-impl/kotlin for deep analysis.

##### Architectural Patterns & Principles
- Plugin Architecture: clear separation between API definitions (api.core, api.features) and implementations (features-impl).
- Dependency Injection / Service Locator: implementations are discovered via META-INF XML descriptors.
- Modular Build with Bazel: each module has its own BUILD.bazel and strict dependencies.
- Layered Design:
- Transport Layer (JSON-RPC, stdio)
- Protocol Layer (api.core)
- Feature Layer (api.features + implementations)
- Language Engine Layer (IntelliJ + Kotlin compiler internals)
- Project Model Layer (workspace-import)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Editor Clients"
        direction TB
        subgraph "VS Code Extension"
            direction TB
            ExtensionTS["extension.ts"]:::client
            LspClientTS["lspClient.ts"]:::client
        end
        subgraph "Other Clients (Scripts)"
            direction TB
            ShellScript["kotlin-lsp.sh"]:::client
            EmacsScript["lsp-kotlin-emacs.el"]:::client
            NeovimDoc["neovim.md"]:::client
            ZedSettings["zed-settings.json"]:::client
        end
    end

    subgraph "Transport Layer (JSON-RPC)"
        direction TB
        ClientKt["Client.kt"]:::transport
        Requests["requests/"]:::transport
    end

    KotlinLspServer["KotlinLspServer"]:::transport

    subgraph "Protocol & API"
        direction TB
        APICore["api.core"]:::api
        APIFeatures["api.features"]:::api
    end

    subgraph "Feature Implementations"
        direction TB
        ImplCommon["features-impl/common"]:::impl
        ImplKotlin["features-impl/kotlin"]:::impl
    end

    WorkspaceImport["workspace-import"]:::impl

    Engine["IntelliJ Engine / Kotlin Compiler"]:::engine

    %% Flows
    ExtensionTS -->|"JSON-RPC init/textDocument"| ClientKt
    LspClientTS -->|"JSON-RPC requests"| ClientKt
    ShellScript --> ClientKt
    EmacsScript --> ClientKt
    NeovimDoc --> ClientKt
    ZedSettings --> ClientKt

    ClientKt -->|"JSON-RPC"| KotlinLspServer
    Requests -->|"JSON-RPC"| KotlinLspServer

    KotlinLspServer --> APICore
    APICore --> APIFeatures
    APIFeatures --> ImplCommon
    APIFeatures --> ImplKotlin

    KotlinLspServer -->|"initialize"| WorkspaceImport
    WorkspaceImport -->|"project model"| KotlinLspServer

    ImplCommon -->|"analysis calls"| Engine
    ImplKotlin -->|"analysis calls"| Engine

    KotlinLspServer -->|"LSP responses"| ClientKt
    ClientKt -->|"responses"| ExtensionTS

    %% Click Events
    click APICore "https://github.com/kotlin/kotlin-lsp/tree/main/api.core/src/com/jetbrains/ls/api/core"
    click APIFeatures "https://github.com/kotlin/kotlin-lsp/tree/main/api.features/src/com/jetbrains/ls/api/features"
    click ImplCommon "https://github.com/kotlin/kotlin-lsp/tree/main/features-impl/common/src/com/jetbrains/ls/api/features/impl/common"
    click ImplKotlin "https://github.com/kotlin/kotlin-lsp/tree/main/features-impl/kotlin/src/com/jetbrains/ls/api/features/impl/common/kotlin"
    click WorkspaceImport "https://github.com/kotlin/kotlin-lsp/tree/main/workspace-import/src/com/jetbrains/ls/imports"
    click KotlinLspServer "https://github.com/kotlin/kotlin-lsp/blob/main/kotlin-lsp/src/com/jetbrains/ls/kotlinLsp/KotlinLspServer.kt"
    click ClientKt "https://github.com/kotlin/kotlin-lsp/blob/main/kotlin-lsp/src/com/jetbrains/ls/kotlinLsp/connection/Client.kt"
    click Requests "https://github.com/kotlin/kotlin-lsp/tree/main/kotlin-lsp/src/com/jetbrains/ls/kotlinLsp/requests"
    click ExtensionTS "https://github.com/kotlin/kotlin-lsp/blob/main/kotlin-vscode/client/src/extension.ts"
    click LspClientTS "https://github.com/kotlin/kotlin-lsp/blob/main/kotlin-vscode/client/src/lspClient.ts"
    click ShellScript "https://github.com/kotlin/kotlin-lsp/blob/main/scripts/kotlin-lsp.sh"
    click EmacsScript "https://github.com/kotlin/kotlin-lsp/blob/main/scripts/lsp-kotlin-emacs.el"
    click NeovimDoc "https://github.com/kotlin/kotlin-lsp/blob/main/scripts/neovim.md"
    click ZedSettings "https://github.com/kotlin/kotlin-lsp/blob/main/scripts/zed-settings.json"

    %% Styles
    classDef client fill:#E0BBE4,stroke:#333,stroke-width:1px
    classDef transport fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef api fill:#A0C4FF,stroke:#333,stroke-width:1px
    classDef impl fill:#C1E1C1,stroke:#333,stroke-width:1px
    classDef engine fill:#FFD8B1,stroke:#333,stroke-width:1px
```
