# manateelazycat/lsp-bridge architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source Emacs plugin plus external Python service (“lsp-bridge”) that provides a blazing-fast LSP client in Emacs.
- The Elisp side is the frontend: completion UI, keybindings, commands, multi-backend integration. The Python side is a multi‐threaded LSP request dispatcher and handler, talking to one or more language servers via JSON-RPC.
- It also supports remote completion via SSH/tramp and multi-server fusion via simple JSON config files.

##### File structure
- Top-level Elisp files: lsp-bridge.el (main), lsp-bridge-epc.el (IPC glue), plus many feature modules (peek, code-action, diagnostic, breadcrumb, semantic-tokens, etc.).
- The “acm” directory contains the asynchronous completion menu engine in Elisp.
- Python service (“python-lsp-bridge” wrapper, lsp_bridge.py) plus “core” modules: core/lspserver.py (JSON-RPC handler), core/fileaction.py, core/handler/* (per-method LSP handlers), core/remote_file.py (SSH/tramp support), plus backends for Codeium, Copilot, TabNine, search_word, etc.
- “langserver” and “multiserver” directories hold JSON definitions of single and multi-server configs.
- “resources” holds StarDict data used by the search-word backend.
- “test” folder contains unit tests for both Elisp and Python sides.
- Configuration files: pyproject.toml, uv.lock, CI workflow in .github/workflows/test.yml.

##### README insights
- The README describes the high-level architecture (there are two PNGs: framework.png for local, remote_file_framework.png for remote completion).
- Emphasizes plug-and-play design, multi-backend fusion, and remote/SSH/devcontainer support.
- Detailed sections enumerate all commands, keymaps, Elisp options, Python dependencies, and supported language servers.

##### Details to capture
- Front-end feature modules (peek, code-action, inlay-hint, semantic-tokens).
- Python service internals: handler registry, file model, remote file proxy.
- JSON config loading precedence (user-dir overrides default).
- Flow variants: local mode vs. remote SSH/tramp vs. devcontainer.
- Test harness (test/ folder) to indicate QA integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User(["User types in Emacs"]):::frontend
    subgraph "Emacs Client (Elisp Frontend)"
        EBMain["lsp-bridge.el"]:::frontend
        EPCGlue["lsp-bridge-epc.el"]:::ipc
        Peek["Peek Window Module"]:::frontend
        CodeAction["Code Action Module"]:::frontend
        Diagnostic["Diagnostic Module"]:::frontend
        Breadcrumb["Breadcrumb Module"]:::frontend
        CallHierarchy["Call Hierarchy Module"]:::frontend
        InlayHint["Inlay Hint Module"]:::frontend
        SemanticTokens["Semantic Tokens Module"]:::frontend
        Imenu["Imenu Integration"]:::frontend
        Dart["Dart Support"]:::frontend
        RustMod["Rust Support"]:::frontend
        JDTLS["JDTLS Support"]:::frontend
        OrgBabel["Org-Babel Support"]:::frontend
        LSPInstaller["LSP Installer UI"]:::frontend
        ACMCore["acm/acm.el"]:::frontend
        ACMFrame["acm/acm-frame.el"]:::frontend
        ACMIcon["acm/acm-icon.el"]:::frontend
        ACMQuick["acm/acm-quick-access.el"]:::frontend
        ACMDir["acm/icons/"]:::frontend
        ACMBackends["acm/acm-backend-*.el"]:::frontend
    end

    subgraph "IPC Layer"
        EPCGlue
    end

    subgraph "Python Service (lsp_bridge.py)"
        Launcher["python-lsp-bridge"]:::backend
        Entry["lsp_bridge.py"]:::backend
        LSPServer["core/lspserver.py"]:::backend
        FileAction["core/fileaction.py"]:::backend
        RemoteFile["core/remote_file.py"]:::backend
        Handlers["core/handler/*.py"]:::backend
        Codeium["core/codeium.py"]:::backend
        Copilot["core/copilot.py"]:::backend
        TabNine["core/tabnine.py"]:::backend
        CTags["core/ctags.py"]:::backend
        SearchWords["core/search_file_words.py"]:::backend
    end

    subgraph "Config Stores"
        LangServer["langserver/*.json"]:::config
        MultiServer["multiserver/*.json"]:::config
        Resources["resources/*"]:::config
    end

    subgraph "External LSP Servers"
        LSPServers(["clangd, pyright, rust-analyzer, ..."]):::external
    end

    subgraph "Optional Remote Host"
        RemoteService(["python-lsp-bridge (remote)"]):::external
    end

    subgraph "Test & CI"
        Tests["test/"]:::test
        CI[".github/workflows/test.yml"]:::test
        PyConf["pyproject.toml, uv.lock"]:::test
    end

    User -->|types and triggers| ACMCore
    ACMCore -->|EPC call| EPCGlue
    EPCGlue -->|invoke| Entry
    Entry -->|dispatch| LSPServer
    Entry -->|load configs| LangServer
    Entry -->|load configs| MultiServer
    LSPServer -->|handle via| Handlers
    LSPServer -->|send JSON-RPC| LSPServers
    LSPServers -->|response| LSPServer
    LSPServer -->|callback| Entry
    Entry -->|EPC response| EPCGlue
    EPCGlue -->|return| ACMCore
    ACMCore -->|display UI| User

    EBMain -->|on file change| FileAction
    FileAction -->|diff update| LSPServer
    Entry -->|ssh proxy| RemoteFile
    RemoteFile -->|forward| RemoteService

    Entry -->|use backend| Codeium
    Entry -->|use backend| Copilot
    Entry -->|use backend| TabNine
    Entry -->|use backend| CTags
    Entry -->|use backend| SearchWords

    Tests -->|tests both sides| EBMain
    Tests -->|tests both sides| Entry
    CI -->|runs tests| Tests
    PyConf -->|dependencies| Entry

    classDef frontend fill:#D0E6FF,stroke:#333;
    classDef ipc fill:#FFE4B3,stroke:#333;
    classDef backend fill:#DFF2D8,stroke:#333;
    classDef external fill:#ECECEC,stroke:#333;
    classDef config fill:#FFF2B3,stroke:#333;
    classDef test fill:#F5E6FF,stroke:#333;

    click EBMain "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge.el"
    click EPCGlue "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-epc.el"
    click Peek "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-peek.el"
    click CodeAction "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-code-action.el"
    click Diagnostic "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-diagnostic.el"
    click Breadcrumb "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-breadcrumb.el"
    click CallHierarchy "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-call-hierarchy.el"
    click InlayHint "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-inlay-hint.el"
    click SemanticTokens "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-semantic-tokens.el"
    click Imenu "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-imenu.el"
    click Dart "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-dart.el"
    click RustMod "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-rust.el"
    click JDTLS "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-jdtls.el"
    click OrgBabel "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-org-babel.el"
    click LSPInstaller "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp-bridge-lsp-installer.el"
    click ACMCore "https://github.com/manateelazycat/lsp-bridge/blob/master/acm/acm.el"
    click ACMFrame "https://github.com/manateelazycat/lsp-bridge/blob/master/acm/acm-frame.el"
    click ACMIcon "https://github.com/manateelazycat/lsp-bridge/blob/master/acm/acm-icon.el"
    click ACMQuick "https://github.com/manateelazycat/lsp-bridge/blob/master/acm/acm-quick-access.el"
    click ACMDir "https://github.com/manateelazycat/lsp-bridge/tree/master/acm/icons/"
    click ACMBackends "https://github.com/manateelazycat/lsp-bridge/blob/master/acm/acm-backend-*.el"
    click Launcher "https://github.com/manateelazycat/lsp-bridge/tree/master/python-lsp-bridge"
    click Entry "https://github.com/manateelazycat/lsp-bridge/blob/master/lsp_bridge.py"
    click LSPServer "https://github.com/manateelazycat/lsp-bridge/blob/master/core/lspserver.py"
    click FileAction "https://github.com/manateelazycat/lsp-bridge/blob/master/core/fileaction.py"
    click RemoteFile "https://github.com/manateelazycat/lsp-bridge/blob/master/core/remote_file.py"
    click Handlers "https://github.com/manateelazycat/lsp-bridge/tree/master/core/handler/"
    click Codeium "https://github.com/manateelazycat/lsp-bridge/blob/master/core/codeium.py"
    click Copilot "https://github.com/manateelazycat/lsp-bridge/blob/master/core/copilot.py"
    click TabNine "https://github.com/manateelazycat/lsp-bridge/blob/master/core/tabnine.py"
    click CTags "https://github.com/manateelazycat/lsp-bridge/blob/master/core/ctags.py"
    click SearchWords "https://github.com/manateelazycat/lsp-bridge/blob/master/core/search_file_words.py"
    click LangServer "https://github.com/manateelazycat/lsp-bridge/tree/master/langserver/"
    click MultiServer "https://github.com/manateelazycat/lsp-bridge/tree/master/multiserver/"
    click Resources "https://github.com/manateelazycat/lsp-bridge/tree/master/resources/"
    click Tests "https://github.com/manateelazycat/lsp-bridge/tree/master/test/"
    click CI "https://github.com/manateelazycat/lsp-bridge/blob/master/.github/workflows/test.yml"
    click PyConf "https://github.com/manateelazycat/lsp-bridge/blob/master/pyproject.toml"
```
