# emacs-lsp/lsp-mode architecture

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

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

## Overview

##### Main Components
- Core Emacs Integration: At the heart are the lsp-mode files (like lsp-mode.el, lsp-protocol.el, lsp-diagnostics.el, lsp-completion.el, etc.) that integrate with Emacs and interact with packages such as company, flycheck, imenu, and others.
- LSP Communication Layer: This layer handles asynchronous message exchange between Emacs and external language servers using the Language Server Protocol (documented in lsp-protocol.el). It covers sending requests, receiving diagnostics, and parsing responses.
- Language-specific Client Modules: Located in the “clients” directory, these files (e.g., lsp-angular.el, lsp-clangd.el, lsp-rust.el, etc.) provide custom integrations and configurations for different languages. They essentially map server capabilities to Emacs functionalities.
- Testing and Feature Suites: The “test” and “features” directories contain integration tests, BDD-style feature tests, and support scripts that verify correct behavior of core and client features.
- Documentation & Build Infrastructure: Directories such as “docs”, “mkdocs.yml”, “Makefile”, and GitHub workflows (under “.github/”) hold CI/CD configurations, documentation templates, tutorials, and various support scripts (like those in “scripts”).
- Overrides and Customization: The “overrides” directory provides custom HTML/templates that likely modify how docs or UI components are rendered.

##### Relationships and Interactions
- The Emacs Core/Integration layer sends requests via the LSP Communication Layer to external language servers.
- Language-specific Client Modules in “clients” extend or adjust the communication for particular languages, handing off specific LSP commands and parsing responses.
- The Communication Layer continuously interacts with the external servers, and results are used by the Emacs UI features for code completion, diagnostics, hovers, etc.
- The Test Suite and Feature tests ensure that these interactions and the core functionalities behave as expected.
- The Documentation and Build/CI components support both developer collaboration (through GitHub workflows, CI, and automated testing) and user adoption by providing rich guides and integration tips.

##### Architectural Patterns and Design Principles
- Modular Design: Separation is evident between the generic LSP support in the core and language-specific extensions in the “clients” directory.
- Asynchronous Non-Blocking Communication: The communication with language servers is done asynchronously, which aligns with Emacs’ event-driven architecture.
- Integration and Extensibility: The design supports pluggability with various Emacs packages (flycheck, company, etc.) and external language servers, following open and flexible integration principles.

##### Relevant Technologies, Frameworks, and Libraries
- Emacs Lisp as the primary implementation language.
- Emacs packages/integrations (company, flycheck, imenu, projectile, lsp-ui, etc.).
- LSP specification (Language Server Protocol v3.14) as the guiding standard.
- Testing frameworks and tools (Cucumber-style BDD tests in “features”, unit tests in “test”).

##### Instructing the Principal Software Engineer – What
- Clearly label major components: Core Integration Layer (Emacs lsp-mode), LSP Communication Layer, Clients (language specific), Testing & CI/CD, and Documentation/Build Tools.
- From the Emacs UI (lsp-mode) sending requests to external Language Servers.
- Responses flowing back from servers to the Emacs core and then distributed to the appropriate client modules.
- Internal modules (e.g., primary .el files in core),
- Plug-in modules (clients),
- External systems (language servers),
- Infrastructure components (CI, docs, tests).
- Optionally, break out additional modules such as “overrides” or “scripts” if further granularity is desired.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Emacs Integration
    subgraph "Core Emacs Integration"
        lsp_main["lsp.el"]:::core
        lsp_mode["lsp-mode.el"]:::core
        lsp_protocol["lsp-protocol.el"]:::core
        lsp_diagnostics["lsp-diagnostics.el"]:::core
        lsp_completion["lsp-completion.el"]:::core
        lsp_headerline["lsp-headerline.el"]:::core
        lsp_icons["lsp-icons.el"]:::core
        lsp_ido["lsp-ido.el"]:::core
        lsp_iedit["lsp-iedit.el"]:::core
        lsp_inline["lsp-inline-completion.el"]:::core
        lsp_lens["lsp-lens.el"]:::core
        lsp_modeline["lsp-modeline.el"]:::core
        lsp_semantic["lsp-semantic-tokens.el"]:::core
    end

    %% LSP Communication Layer
    subgraph "LSP Communication Layer"
        lsp_comm["LSP Communication Layer"]:::communication
    end

    %% Language-specific Client Modules
    subgraph "Language-specific Client Modules"
        lsp_clients["Language-specific Clients"]:::client
    end

    %% Testing & Feature Suites
    subgraph "Testing & Feature Suites"
        test_suite["Test Suite"]:::testing
        feature_tests["Feature Tests"]:::testing
    end

    %% Documentation & Build Infrastructure
    subgraph "Documentation & Build Infrastructure"
        docs["Documentation"]:::doc
        build_ci["Build/CI"]:::doc
    end

    %% Overrides and Customization
    subgraph "Overrides and Customization"
        overrides["Overrides"]:::override
    end

    %% External Systems
    subgraph "External Systems"
        lang_servers["Language Servers"]:::external
    end

    %% Data Flow Connections
    lsp_mode -->|"request"| lsp_comm
    lsp_comm -->|"clientCmds"| lsp_clients
    lsp_comm -->|"request"| lang_servers
    lang_servers -->|"response"| lsp_comm
    lsp_comm -->|"updateUI"| lsp_mode

    %% Supporting Infrastructure Connections
    test_suite -->|"tests"| lsp_mode
    feature_tests -->|"tests"| lsp_mode
    docs -->|"guides"| lsp_mode
    build_ci -->|"builds"| docs
    overrides -->|"customizes"| docs

    %% Click Events
    click lsp_main "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp.el"
    click lsp_mode "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-mode.el"
    click lsp_protocol "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-protocol.el"
    click lsp_diagnostics "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-diagnostics.el"
    click lsp_completion "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-completion.el"
    click lsp_headerline "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-headerline.el"
    click lsp_icons "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-icons.el"
    click lsp_ido "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-ido.el"
    click lsp_iedit "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-iedit.el"
    click lsp_inline "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-inline-completion.el"
    click lsp_lens "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-lens.el"
    click lsp_modeline "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-modeline.el"
    click lsp_semantic "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-semantic-tokens.el"
    click lsp_comm "https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-protocol.el"
    click lsp_clients "https://github.com/emacs-lsp/lsp-mode/tree/master/clients"
    click test_suite "https://github.com/emacs-lsp/lsp-mode/tree/master/test"
    click feature_tests "https://github.com/emacs-lsp/lsp-mode/tree/master/features"
    click docs "https://github.com/emacs-lsp/lsp-mode/tree/master/docs"
    click build_ci "https://github.com/emacs-lsp/lsp-mode/tree/master/Makefile"
    click overrides "https://github.com/emacs-lsp/lsp-mode/tree/master/overrides"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef communication fill:#ccf,stroke:#333,stroke-width:2px;
    classDef client fill:#cfc,stroke:#333,stroke-width:2px;
    classDef testing fill:#fc9,stroke:#333,stroke-width:2px;
    classDef doc fill:#cff,stroke:#333,stroke-width:2px;
    classDef override fill:#fcc,stroke:#333,stroke-width:2px;
    classDef external fill:#ff9,stroke:#333,stroke-width:2px;
```
