# omnisharp/omnisharp-server architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source language server / HTTP wrapper around the NRefactory C# parser.
- It exposes REST endpoints (via NancyFx) to editor plugins (Vim, Sublime, Emacs, Atom, YCM).
- It orchestrates solution/project loading, code parsing, analysis, refactoring, build and code-action operations.

##### File structure
Top-level folders:
- OmniSharp — main C# source (handlers/modules, core services, domain models)
- OmniSharp.Tests — feature-by-feature automated tests
- Microsoft.Build.Evaluation — MSBuild project evaluation library
- NRefactory (git submodule) — C# parser/AST generator
- packages — third-party NuGet libraries (NancyFx, Mono.Cecil, NUnit, etc.)
Configuration files: config.json, app.config, .sln, .csproj.

##### Extract README insights
- The “Bootstrapper” spins up a Nancy self-host on a TCP port.
- Each feature (autocomplete, build, code format, find usages, etc.) is implemented as a Nancy module + handler + request/response DTOs.
- Metadata modules generate swagger docs for each endpoint.

##### Main components
A. HTTP/API Layer
– NancyFx Self-Host (Bootstrapper → NancyHost)
– Nancy Modules (one per feature folder, e.g., AutoCompleteModule, BuildModule, CodeFormatModule, etc.)
– Nancy Metadata Modules (Swagger metadata providers)
B. Handler Layer
– Feature Handlers (AutoCompleteHandler, BuildHandler, CodeFormatHandler, etc.)
– Each handler receives a Request DTO, coordinates services, returns a Response DTO.
C. Core Services & Domain Logic
– Request routing → Handler → Service classes (e.g., CompletionDataFactory, BuildCommandBuilder, DocumentationFetcher, QuickFixService)
– Parser layer (BufferParser, NRefactory AST via NRefactory submodule)
– Project/Solution abstraction (CSharpSolution, MsBuildWorkspaceInformation, ProjectFinder)
– File system abstraction (IFileSystem, FileSystem)
– Configuration (OmniSharpConfiguration, path replacement, test commands)
D. External Dependencies
– NRefactory (C# parsing & AST)
– Microsoft.Build (project/solution evaluation)
– Mono.Cecil (assembly metadata / reflection)
– NancyFx (HTTP + routing + DI)
– Newtonsoft.Json (JSON serialization)
– Swagger / Nancy.Swagger (API docs)
E. Test Harness
– OmniSharp.Tests (unit/integration tests organized by feature)
– FakeFileSystem, FakeSolution, etc.

##### Relationships & data-flow
1. Editor plugin → HTTP POST/GET → NancyFx endpoint
2. Nancy Module (defines route) → invokes corresponding Handler
3. Handler: deserialize Request DTO → invoke one or more Service components
4. Services consult Parser / Solution / Project / FileSystem / MSBuild as needed
5. Service returns Response DTO → NancyFx serializes to JSON → HTTP response back to editor
6. Metadata modules supply Swagger JSON via separate endpoints

##### Architectural patterns & principles
- Modular “feature per folder” structure (each feature = module + handler + DTOs + metadata)
- Request–response DTOs decoupled from domain models
- Dependency injection via Nancy’s built-in container
- Separation of concerns: API layer vs. orchestration (handlers) vs. core logic vs. parsing/persistence
- Use of adapter/abstraction layers over file system, MSBuild, and parsing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    subgraph "Editor Plugins"
        direction TB
        Editor["Editor Plugin"]:::external
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        Bootstrapper["Bootstrapper (Nancy Self-Host)"]:::api
        Program["Program / NancyHost"]:::api

        subgraph "Nancy Modules"
            direction TB
            AutoCompleteModule["AutoCompleteModule"]:::api
            BuildModule["BuildModule"]:::api
            CodeFormatModule["CodeFormatModule"]:::api
            FindUsagesModule["FindUsagesModule"]:::api
            GotoDefinitionModule["GotoDefinitionModule"]:::api
            CheckAliveStatusModule["CheckAliveStatusModule"]:::api
            UpdateBufferModule["UpdateBufferModule"]:::api
        end

        subgraph "Swagger Metadata Modules"
            direction TB
            MetadataAutoComplete["AutoComplete Metadata"]:::api
            MetadataBuild["Build Metadata"]:::api
            MetadataCodeFormat["CodeFormat Metadata"]:::api
        end
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        AutoCompleteHandler["AutoCompleteHandler"]:::orchestration
        BuildHandler["BuildHandler"]:::orchestration
        CodeFormatHandler["CodeFormatHandler"]:::orchestration
        FindUsagesHandler["FindUsagesHandler"]:::orchestration
    end

    %% Core Services & Domain
    subgraph "Core Services & Domain Logic"
        direction TB
        subgraph ParserLayer
            BufferParser["BufferParser"]:::core
            ParsedResult["ParsedResult"]:::core
        end
        subgraph SolutionProject
            CSharpSolution["CSharpSolution"]:::core
            ProjectFinder["ProjectFinder"]:::core
            MsBuildWorkspaceInformation["MsBuildWorkspaceInformation"]:::core
        end
        subgraph FileSystem
            IFileSystem["IFileSystem"]:::core
            FileSystem["FileSystem"]:::core
        end
        subgraph Configuration
            OmniSharpConfiguration["OmniSharpConfiguration"]:::core
        end
        subgraph Factories
            CompletionDataFactory["CompletionDataFactory"]:::core
            BuildCommandBuilder["BuildCommandBuilder"]:::core
            DocumentationFetcher["DocumentationFetcher"]:::core
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        NRefactory["NRefactory"]:::external
        MSBuild["Microsoft.Build.Evaluation"]:::external
        MonoCecil["Mono.Cecil"]:::external
        NancyFx["NancyFx & Swagger & JSON"]:::external
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        Tests["OmniSharp.Tests"]:::test
        FakeFileSystem["FakeFileSystem"]:::test
    end

    %% Relationships
    Editor -->|"HTTP POST/GET"| Bootstrapper
    Bootstrapper --> Program
    Program --> AutoCompleteModule
    Program --> BuildModule
    Program --> CodeFormatModule
    Program --> FindUsagesModule
    Program --> CheckAliveStatusModule
    Program --> UpdateBufferModule

    AutoCompleteModule --> AutoCompleteHandler
    BuildModule --> BuildHandler
    CodeFormatModule --> CodeFormatHandler
    FindUsagesModule --> FindUsagesHandler

    AutoCompleteHandler --> BufferParser
    AutoCompleteHandler --> CompletionDataFactory
    BufferParser --> NRefactory
    CompletionDataFactory --> ParsedResult

    BuildHandler --> BuildCommandBuilder
    BuildCommandBuilder --> MSBuild

    CodeFormatHandler --> DocumentationFetcher
    DocumentationFetcher --> MonoCecil

    ParsedResult --> CSharpSolution
    CSharpSolution --> ProjectFinder
    ProjectFinder --> MsBuildWorkspaceInformation

    IFileSystem --> FileSystem
    OmniSharpConfiguration --> FileSystem

    NancyFx --> Program
    NancyFx --> AutoCompleteModule
    NancyFx --> SwaggerMetadata

    SwaggerMetadata["Swagger Metadata"]:::external

    Tests -.-> AutoCompleteHandler
    Tests -.-> BuildHandler
    Tests -.-> CodeFormatHandler
    Tests -.-> FakeFileSystem

    %% Click Events
    click Bootstrapper "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Bootstrapper.cs"
    click Program "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Program.cs"
    click AutoCompleteModule "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/AutoComplete/AutoCompleteModule.cs"
    click BuildModule "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Build/BuildModule.cs"
    click CodeFormatModule "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/CodeFormat/CodeFormatModule.cs"
    click FindUsagesModule "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/FindUsages/FindUsagesModule.cs"
    click CheckAliveStatusModule "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/CheckAliveStatus/CheckAliveStatusModule.cs"
    click UpdateBufferModule "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/UpdateBuffer/UpdateBufferModule.cs"
    click AutoCompleteHandler "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/AutoComplete/AutoCompleteHandler.cs"
    click BuildHandler "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Build/BuildHandler.cs"
    click CodeFormatHandler "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/CodeFormat/CodeFormatHandler.cs"
    click FindUsagesHandler "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/FindUsages/FindUsagesHandler.cs"
    click BufferParser "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Parser/BufferParser.cs"
    click ParsedResult "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Parser/ParsedResult.cs"
    click CSharpSolution "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Solution/CSharpSolution.cs"
    click ProjectFinder "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Solution/ProjectFinder.cs"
    click MsBuildWorkspaceInformation "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/FindProjects/MsBuildWorkspaceInformation.cs"
    click IFileSystem "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Common/IFileSystem.cs"
    click FileSystem "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Common/FileSystem.cs"
    click OmniSharpConfiguration "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Configuration/OmniSharpConfiguration.cs"
    click CompletionDataFactory "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/AutoComplete/CompletionDataFactory.cs"
    click BuildCommandBuilder "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Build/BuildCommandBuilder.cs"
    click DocumentationFetcher "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp/Documentation/DocumentationFetcher.cs"
    click NRefactory "https://github.com/omnisharp/omnisharp-server/tree/master/NRefactory/"
    click MSBuild "https://github.com/omnisharp/omnisharp-server/tree/master/Microsoft.Build.Evaluation/"
    click MonoCecil "https://github.com/omnisharp/omnisharp-server/tree/master/cecil/"
    click NancyFx "https://github.com/omnisharp/omnisharp-server/blob/master/packages/Nancy.*"
    click Tests "https://github.com/omnisharp/omnisharp-server/tree/master/OmniSharp.Tests/"
    click FakeFileSystem "https://github.com/omnisharp/omnisharp-server/blob/master/OmniSharp.Tests/FakeFileSystem.cs"

    %% Styles
    classDef api fill:#cfe2ff,stroke:#084298,color:#084298
    classDef orchestration fill:#d1e7dd,stroke:#0f5132,color:#0f5132
    classDef core fill:#fff3cd,stroke:#664d03,color:#664d03
    classDef external fill:#f8d7da,stroke:#842029,color:#842029
    classDef test fill:#e2e3e5,stroke:#495057,color:#495057
```
