# omnisharp/csharp-language-server-protocol architecture

> Architecture diagram of the GitHub repository omnisharp/csharp-language-server-protocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omnisharp/csharp-language-server-protocol
- Repository: https://github.com/omnisharp/csharp-language-server-protocol

## Overview

The project is a highly modular .NET implementation of the Language Server Protocol (LSP) along with related protocols (Debug Adapter Protocol – DAP – and JSON-RPC), built around a MediatR-based request/response model with extensive use of Microsoft.Extensions for configuration, dependency injection, and logging. In other words, this is a library (and suite of libraries) that implements protocol handling and communication layers in C#, with clear separations between protocol definitions, request routing, serialization, and the actual client/server implementations.

##### Core Architectural Components
- JSON-RPC Core Layer: This is at the heart of the library and includes the JSON-RPC abstractions, messaging, serialization (e.g., DapSerializer, optional converters) as well as the generated components in the JsonRpc.Generators directory.
- MediatR Request/Response Pipeline: Represent the usage of MediatR for managing request handling and routing. This sits on top of the JSON-RPC layer and acts as the central hub for dispatching protocol-specific requests.
- Protocol Abstractions: A dedicated layer for protocol definitions and models (the “Protocol” directory) that encapsulates the types, notifications, and requests in strict conformance with the Language Server Protocol. Similarly, the Debug Adapter Protocol is separated into its own DAP modules.
- Language Client/Server Components: This includes the language client (LSP Client) and language server abstractions, along with supporting classes (for example, in /src/Client, /src/Server, and /src/Shared). These are built on top of the JSON-RPC and MediatR infrastructure.
- Debug Adapter Components: Comprising both the client and server sides of the Debug Adapter Protocol (from the /src/Dap.Client, /src/Dap.Protocol, and /src/Dap.Server directories), these modules implement the debug-specific parts of the overall protocol strategy.

##### Relationships and Interactions
- The JSON-RPC layer provides the fundamental communication – it both serializes messages and routes JSON messages into MediatR requests.
- MediatR acts as the “glue” that links protocol requests (LSP/DAP) to the appropriate handlers. It does so via dependency injection configured with Microsoft.Extensions.DependencyInjection, found in the various LanguageServer and LanguageClient ServiceCollection extensions.
- The protocol-specific layers (LSP and DAP) are built as distinct modules that depend on and extend the JSON-RPC base.
- There is a clear boundary between the protocol definitions (data models, serialization, and protocol structures in the “Protocol” directories) and the implementation code (handlers and runtime in “Server”, “Client”, “Dap.Server”, “Dap.Client”, etc.).
- Test and sample projects (e.g., those under /test, /benchmarks, /sample, and VS Code/Atom extensions) validate integration points and ensure that the components interact correctly.

##### Architectural Patterns & Principles
- Layered/Modular Architecture: Separation between core protocol abstractions (models, serialization), transport (JSON-RPC), and higher-level protocol implementations (LSP and DAP).
- Dependency Injection: The heavy use of Microsoft.Extensions.DependencyInjection ensures that dependencies among the communication, handler registration, and business logic are decoupled.
- MediatR Pattern: Centralized routing of requests and responses promotes clean separation of concerns and makes extension via new handlers straightforward.
- Code Generation: The inclusion of JsonRpc.Generators indicates that part of the system’s functionality is auto-generated based on reflective or declarative attributes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Integration
    External["Client Applications (IDEs/Editors)"]:::ext

    %% Client Components
    subgraph "Client Layer"
        LC["Language Client"]:::lsp
        DC["DAP Client"]:::dap
    end
    External -->|"initiates"| LC
    External -->|"initiates"| DC

    %% Core Communication Layer
    subgraph "Core Communication Layer"
        JRC["JSON-RPC Core"]:::core
        JRG["JsonRpc.Generators"]:::core
        Protocol["Protocol Abstractions"]:::proto
    end
    LC -->|"sends_requests"| JRC
    DC -->|"sends_requests"| JRC
    JRC -->|"invokes"| JRG
    Protocol -->|"supports"| JRC

    %% Routing Layer (MediatR Pipeline)
    subgraph "Routing Layer"
        Mediator["MediatR Pipeline"]:::med
        ClientDI["LanguageClientServiceCollectionExtensions.cs"]:::med
        ServerDI["LanguageServerServiceCollectionExtensions.cs"]:::med
    end
    JRC -->|"routes_to"| Mediator
    Protocol -->|"informs"| Mediator
    Mediator -->|"configures"| ClientDI
    Mediator -->|"configures"| ServerDI

    %% Server/Handler Layers (LSP and DAP)
    subgraph "Server/Handler Layers"
        LSP_Server["Language Server"]:::lsp
        Sample_Server["Sample Server"]:::lsp
        DAP_Server["DAP Server"]:::dap
    end
    Mediator -->|"dispatches_LSP"| LSP_Server
    Mediator -->|"dispatches_DAP"| DAP_Server
    LSP_Server -->|"example"| Sample_Server

    %% Debug Adapter Protocol Support
    subgraph "Debug Adapter Support"
        DAP_Prot["DAP Protocol"]:::dap
    end
    DAP_Server ---|"uses"| DAP_Prot

    %% Dependency Injection
    DI["DI (Microsoft.Extensions)"]:::di
    DI ---|"wires"| Mediator

    %% Click Events
    click JRC "https://github.com/omnisharp/csharp-language-server-protocol/tree/master/src/JsonRpc"
    click JRG "https://github.com/omnisharp/csharp-language-server-protocol/blob/master/src/JsonRpc.Generators"
    click ClientDI "https://github.com/omnisharp/csharp-language-server-protocol/blob/master/src/Client/LanguageClientServiceCollectionExtensions.cs"
    click ServerDI "https://github.com/omnisharp/csharp-language-server-protocol/blob/master/src/Server/LanguageServerServiceCollectionExtensions.cs"
    click Protocol "https://github.com/omnisharp/csharp-language-server-protocol/tree/master/src/Protocol"
    click LC "https://github.com/omnisharp/csharp-language-server-protocol/tree/master/src/Client"
    click LSP_Server "https://github.com/omnisharp/csharp-language-server-protocol/tree/master/src/Server"
    click Sample_Server "https://github.com/omnisharp/csharp-language-server-protocol/tree/master/sample/SampleServer"
    click DC "https://github.com/omnisharp/csharp-language-server-protocol/blob/master/src/Dap.Client"
    click DAP_Prot "https://github.com/omnisharp/csharp-language-server-protocol/blob/master/src/Dap.Protocol"
    click DAP_Server "https://github.com/omnisharp/csharp-language-server-protocol/blob/master/src/Dap.Server"

    %% Styles
    classDef core fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef med fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef proto fill:#d5f5e3,stroke:#28b463,stroke-width:2px;
    classDef lsp fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef dap fill:#d6eaf8,stroke:#2471a3,stroke-width:2px;
    classDef di fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef ext fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
```
