# georgewfraser/java-language-server architecture

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

- Interactive diagram: https://gitdiagram.com/georgewfraser/java-language-server
- Repository: https://github.com/georgewfraser/java-language-server

## Overview

##### Project type and purpose
- This is a language-server implementation for Java, packaged as a VS Code extension (and usable in other editors via scripts).
- It comprises two main layers:
a. A Node/TypeScript “extension” client (in lib/, package.json, and the dist/ scripts) that runs inside the editor’s extension host.
b. A standalone Java process (built with Maven from src/main/java) that implements the Language Server Protocol (LSP) and Debug Adapter Protocol (DAP) using the Java Compiler API.

##### File structure
- Top-level:
- lib/: TypeScript entry point (extension.ts), TextMate grammars, language-configuration.json, snippets, package.json
- src/main/java/: Java LSP & DAP server code (packages org.javacs.*) plus Bazel protobuf definitions under src/main/protobuf
- dist/: shell+cmd launch scripts for the language server, debug adapter, and client launchers
- scripts/: CI/helper scripts (build, download JDK, format, link, release)
- .github/, git_hooks/: CI & formatting hooks
- README.md: overall description and usage
- Patterns:
- LSP and DAP JSON-RPC over STDIO
- Node “extension” spawns child process for language server and/or debug adapter
- Java server uses incremental compilation by erasing method bodies, communicates with editor via LSP requests/responses

##### README for additional insights
- Describes features (autocomplete, go-to-definition, hover, lint, debug).
- Shows that the TypeScript code is minimal: its job is to download/link binaries and then launch the Java process with the correct script.
- Build toolchain: npm for the extension, Maven & protobuf for the Java server.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Editor & Extension Host
    subgraph "Editor & Extension Host"
        direction TB
        EditorUI["Editor UI (VS Code)"]:::client
        subgraph "Node/TypeScript Extension"
            direction TB
            ExtTS["extension.ts"]:::client
            Scopes["scopes.ts"]:::client
            TextMate["textMate.ts"]:::client
            Grammar["java.tmLanguage.json"]:::client
            LangConfig["language-configuration.json"]:::client
            PKGJSON["package.json"]:::client
            TSConfig["tsconfig.json"]:::client
        end
    end

    %% Snippets & Grammars
    subgraph "Snippets & Grammars"
        direction TB
        Snippets["snippets/java.json"]:::client
        TMGrammar["lib/java.tmLanguage.json"]:::client
    end

    %% Launch Scripts
    subgraph "Launch Scripts (LSP & DAP)" 
        direction TB
        LSPSh["lang_server_*.sh/.cmd"]:::infra
        DAPSh["debug_adapter_*.sh/.cmd"]:::infra
        ClientSh["launch_*.sh/.cmd"]:::infra
    end

    %% Java Server Processes
    subgraph "Java Server Processes"
        direction TB
        subgraph "Language Server"
            direction TB
            MainJava["Main.java"]:::server
            JavaLS["JavaLanguageServer.java"]:::server
        end
        subgraph "Debug Server"
            direction TB
            JavaDebug["JavaDebugServer.java"]:::server
        end
    end

    %% Compiler & Protobuf Modules
    subgraph "Compiler & Protobuf Layer"
        direction TB
        subgraph "Compiler API & Incremental Compilation"
            direction TB
            ReusableCompiler["ReusableCompiler.java"]:::server
            CompileTask["CompileTask.java"]:::server
            CompilerProvider["CompilerProvider.java"]:::server
            ParseTask["ParseTask.java"]:::server
        end
        subgraph "Protobuf Definitions & Generated Classes"
            direction TB
            ProtoDef1["analysis.proto"]:::server
            ProtoDef2["analysis_v2.proto"]:::server
            ProtoDef3["build.proto"]:::server
            Gen1["AnalysisProtos.java"]:::server
            Gen2["AnalysisProtosV2.java"]:::server
            Gen3["Build.java"]:::server
        end
        subgraph "Protocol Bindings"
            direction TB
            LSPBindings["org/javacs/lsp/*"]:::server
            DAPBindings["org/javacs/debug/proto/*"]:::server
        end
    end

    %% File System & Dependency Cache
    FileSystem["File System / Maven & Gradle Cache"]:::infra

    %% Build & Packaging Tools
    subgraph "Build & Packaging"
        direction TB
        MavenPKG["pom.xml"]:::infra
        NpmPKG["package.json & package-lock.json"]:::infra
        VSCE[".vscodeignore"]:::infra
    end

    %% CI & Helper Scripts
    subgraph "CI & Helper Scripts"
        direction TB
        WorkflowTest[".github/workflows/test.yml"]:::infra
        WorkflowRel[".github/workflows/release.yml"]:::infra
        BuildScript["scripts/build.sh"]:::infra
        DownloadJDK["scripts/download_*_jdk.sh"]:::infra
        LinkScripts["scripts/link_*.sh"]:::infra
        GenProto["scripts/gen_proto.sh"]:::infra
        ReleaseScript["scripts/release.sh"]:::infra
    end

    %% Tests
    subgraph "Tests"
        direction TB
        JSTest["JavaLanguageServerTest.java"]:::server
        DebugTest["JavaDebugServerTest.java"]:::server
        LSPTest["LspTest.java"]:::server
    end

    %% Connections
    EditorUI -->|"Registers handlers"| ExtTS
    EditorUI -->|"Uses snippets/grammar"| Snippets
    EditorUI -->|"Uses snippets/grammar"| TMGrammar

    ExtTS -->|"spawns"| LSPSh
    ExtTS -->|"spawns"| DAPSh
    ExtTS -->|"spawns"| ClientSh

    LSPSh -->|"JSON-RPC LSP over STDIO"| MainJava
    DAPSh -->|"JSON-RPC DAP over STDIO"| JavaDebug

    MainJava -->|"implements"| JavaLS
    JavaLS -->|"calls"| ReusableCompiler
    JavaLS -->|"calls"| CompileTask
    JavaLS -->|"gets provider"| CompilerProvider
    JavaLS -->|"parses"| ParseTask
    JavaLS -->|"uses"| LSPBindings
    JavaLS -->|"uses"| ProtoDef1
    JavaLS -->|"uses"| ProtoDef2
    JavaLS -->|"uses"| ProtoDef3
    JavaLS -->|"reads/writes"| FileSystem

    JavaDebug -->|"uses"| DAPBindings
    JavaDebug -->|"launches debugging on"| FileSystem

    Gen1 --> ProtoDef1
    Gen2 --> ProtoDef2
    Gen3 --> ProtoDef3

    MavenPKG --> MainJava
    NpmPKG --> ExtTS
    VSCE --> NpmPKG

    WorkflowTest --> BuildScript
    WorkflowRel --> ReleaseScript

    %% Classes
    classDef client fill:#b2dfdb,stroke:#00695c,color:#004d40
    classDef server fill:#bbdefb,stroke:#1565c0,color:#0d47a1
    classDef infra fill:#ffe0b2,stroke:#ef6c00,color:#e65100

    %% Click events
    click ExtTS "https://github.com/georgewfraser/java-language-server/blob/master/lib/extension.ts"
    click Scopes "https://github.com/georgewfraser/java-language-server/blob/master/lib/scopes.ts"
    click TextMate "https://github.com/georgewfraser/java-language-server/blob/master/lib/textMate.ts"
    click Grammar "https://github.com/georgewfraser/java-language-server/blob/master/lib/java.tmLanguage.json"
    click LangConfig "https://github.com/georgewfraser/java-language-server/blob/master/language-configuration.json"
    click PKGJSON "https://github.com/georgewfraser/java-language-server/blob/master/package.json"
    click TSConfig "https://github.com/georgewfraser/java-language-server/blob/master/tsconfig.json"
    click Snippets "https://github.com/georgewfraser/java-language-server/blob/master/snippets/java.json"
    click TMGrammar "https://github.com/georgewfraser/java-language-server/blob/master/lib/java.tmLanguage.json"
    click LSPSh "https://github.com/georgewfraser/java-language-server/blob/master/dist/lang_server_*.sh"
    click DAPSh "https://github.com/georgewfraser/java-language-server/blob/master/dist/debug_adapter_*.sh"
    click ClientSh "https://github.com/georgewfraser/java-language-server/blob/master/dist/launch_*.sh"
    click MainJava "https://github.com/georgewfraser/java-language-server/blob/master/src/main/java/org/javacs/Main.java"
    click JavaLS "https://github.com/georgewfraser/java-language-server/blob/master/src/main/java/org/javacs/JavaLanguageServer.java"
    click JavaDebug "https://github.com/georgewfraser/java-language-server/blob/master/src/main/java/org/javacs/debug/JavaDebugServer.java"
    click ReusableCompiler "https://github.com/georgewfraser/java-language-server/blob/master/src/main/java/org/javacs/ReusableCompiler.java"
    click CompileTask "https://github.com/georgewfraser/java-language-server/blob/master/src/main/java/org/javacs/CompileTask.java"
    click CompilerProvider "https://github.com/georgewfraser/java-language-server/blob/master/src/main/java/org/javacs/CompilerProvider.java"
    click ParseTask "https://github.com/georgewfraser/java-language-server/blob/master/src/main/java/org/javacs/ParseTask.java"
    click ProtoDef1 "https://github.com/georgewfraser/java-language-server/blob/master/src/main/protobuf/analysis.proto"
    click ProtoDef2 "https://github.com/georgewfraser/java-language-server/blob/master/src/main/protobuf/analysis_v2.proto"
    click ProtoDef3 "https://github.com/georgewfraser/java-language-server/blob/master/src/main/protobuf/build.proto"
    click LSPBindings "https://github.com/georgewfraser/java-language-server/tree/master/src/main/java/org/javacs/lsp"
    click DAPBindings "https://github.com/georgewfraser/java-language-server/tree/master/src/main/java/org/javacs/debug/proto"
    click MavenPKG "https://github.com/georgewfraser/java-language-server/blob/master/pom.xml"
    click NpmPKG "https://github.com/georgewfraser/java-language-server/blob/master/package.json"
    click VSCE "https://github.com/georgewfraser/java-language-server/blob/master/.vscodeignore"
    click WorkflowTest "https://github.com/georgewfraser/java-language-server/blob/master/.github/workflows/test.yml"
    click WorkflowRel "https://github.com/georgewfraser/java-language-server/blob/master/.github/workflows/release.yml"
    click BuildScript "https://github.com/georgewfraser/java-language-server/blob/master/scripts/build.sh"
    click DownloadJDK "https://github.com/georgewfraser/java-language-server/blob/master/scripts/download_*_jdk.sh"
    click LinkScripts "https://github.com/georgewfraser/java-language-server/blob/master/scripts/link_*.sh"
    click GenProto "https://github.com/georgewfraser/java-language-server/blob/master/scripts/gen_proto.sh"
    click ReleaseScript "https://github.com/georgewfraser/java-language-server/blob/master/scripts/release.sh"
    click JSTest "https://github.com/georgewfraser/java-language-server/blob/master/src/test/java/org/javacs/JavaLanguageServerTest.java"
    click DebugTest "https://github.com/georgewfraser/java-language-server/blob/master/src/test/java/org/javacs/JavaDebugServerTest.java"
    click LSPTest "https://github.com/georgewfraser/java-language-server/blob/master/src/test/java/org/javacs/lsp/LspTest.java"
```
