# nextflow-io/language-server architecture

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

- Interactive diagram: https://gitdiagram.com/nextflow-io/language-server
- Repository: https://github.com/nextflow-io/language-server

## Overview

1. **What this repo is**
   - This is a Java 17+ Language Server Protocol implementation for Nextflow.
   - It runs as a stdio-based server jar and serves Nextflow script files and Nextflow config files.

2. **Top-level runtime boundary**
   - The entrypoint is `nextflow.lsp.NextflowLanguageServer`.
   - It sits between the editor/client and the internal language features, receiving LSP requests and publishing responses, diagnostics, and notifications over standard input/output.

3. **Core dispatch layer**
   - `nextflow.lsp.services.LanguageService` is the main routing layer.
   - It selects the appropriate subsystem for the file type: `script` services for `.nf`-style workflow scripts and `config` services for Nextflow config files.
   - `LanguageServerConfiguration` and `ErrorReportingMode` control behavior from workspace configuration changes.

4. **Two main analysis pipelines**
   - The repo has a clear split between:
     - `services/script/*` for workflow scripts
     - `services/config/*` for config files
   - Each side has its own AST cache, visitors, completion/hover/definition/reference providers, formatting, semantic tokens, and symbol support.

5. **Script subsystem**
   - `ScriptService` is the orchestrator for script files.
   - It relies on `ScriptAstCache`, `ScriptAstParentVisitor`, and several specialized visitors/providers to answer editor features.
   - This subsystem also handles workflow-specific concerns like process conversion, plugin include resolution, and workspace preview generation.

6. **Config subsystem**
   - `ConfigService` plays the same role for configuration files.
   - It uses `ConfigAstCache`, `ConfigAstParentVisitor`, and config-specific providers for completion, hover, links, formatting, and semantic highlighting.
   - Config analysis also resolves includes via `CachingResolveIncludeVisitor`.

7. **Parsing, compilation, and diagnostics**
   - `nextflow.lsp.compiler.LanguageServerCompiler` and `LanguageServerErrorCollector` form the diagnostics pipeline.
   - Source files are parsed/compiled, errors are collected, and surfaced back to the client as diagnostics.
   - This is the main path for “diagnostics” support in the language server.

8. **State and caching**
   - `nextflow.lsp.file.FileCache` tracks workspace file contents/state.
   - AST and domain-specific caches reduce repeated parsing and enable cross-request reuse.
   - The design assumes many LSP requests are read-heavy and benefit from cached semantic models.

9. **Language feature providers**
   - Standard LSP features are implemented as separate provider classes: completion, definition, references, rename, hover, formatting, symbols, links, code lens, call hierarchy, and semantic tokens.
   - There is a shared abstraction layer in `nextflow.lsp.services.*`, with script/config specializations beneath it.
   - This makes the architecture provider-oriented: each feature is implemented as a focused service over the cached AST/model.

10. **Nextflow-specific semantic model**
   - `nextflow.lsp.spec.*` defines project-specific specs such as `ScriptSpecFactory`, `ConfigSpecFactory`, and plugin metadata caches.
   - These classes encode knowledge of Nextflow syntax, plugins, and runtime conventions so the LSP can offer accurate completions and navigation.
   - `src/main/java/nextflow/script/*` contains deeper language/type infrastructure, including type checking helpers and shim types that model Nextflow/Groovy semantics.

11. **Workflow DAG preview path**
   - Script analysis includes a dedicated DAG preview subsystem under `services/script/dag`.
   - `DataflowVisitor` builds graph data, `Graph` holds the intermediate representation, and `MermaidRenderer` turns it into a previewable diagram format.
   - `WorkspacePreviewProvider` connects this analysis to the language server feature surface.

12. **Utilities and support code**
   - Shared helpers in `nextflow.lsp.util` handle logging, JSON, positions/ranges, debouncing, and progress notifications.
   - `DebouncingExecutor` suggests some requests are rate-limited or coalesced to avoid expensive repeated analysis while the user is typing.

13. **Build and test structure**
   - The project uses Gradle with a wrapper, plus a `Makefile` for local build/test convenience.
   - Tests are in Groovy under `src/test/groovy`, with coverage for caches, type checking, script/config features, DAG preview, and utility code.
   - GitHub Actions workflows build the project and generate dependency updates.

14. **Repository dependency boundary**
   - The README notes that this server is built alongside the Nextflow repository and the `nf-lang` module.
   - Architecturally, that means this repo depends on Nextflow’s language/runtime semantics for correctness, while exposing them through an LSP-compatible server for editors.

Main entry points: [`src/main/java/nextflow/lsp/services/script/ScriptService.java`](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/script/ScriptService.java) (Script Service), [`src/main/java/nextflow/lsp/services/LanguageService.java`](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/LanguageService.java) (Language Service), [`src/main/java/nextflow/lsp/services/config/ConfigService.java`](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/config/ConfigService.java) (Config Service), [`src/main/java/nextflow/lsp/NextflowLanguageServer.java`](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/NextflowLanguageServer.java) (Language Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server["Language Server<br/>stdio LSP server"]
end

subgraph group_core["Core"]
  node_language_service["Language Service<br/>router"]
  node_compiler["Compiler<br/>diagnostics pipeline"]
  node_errors["Error Collector<br/>diagnostics sink"]
  node_file_cache[("File Cache<br/>workspace state<br/>[FileCache.java]")]
  node_shared_providers["LSP Providers<br/>shared feature APIs"]
  node_ast_utils["AST Utils<br/>shared AST helpers"]
  node_server_cfg["Server Config<br/>workspace settings"]
  node_util["Utilities<br/>shared helpers"]
end

subgraph group_script["Script"]
  node_script_service["Script Service<br/>script orchestrator<br/>[ScriptService.java]"]
  node_script_cache[("Script Cache<br/>script AST cache")]
  node_script_features["Script Features<br/>script providers"]
  node_dag_preview["DAG Preview<br/>workflow graph preview"]
end

subgraph group_config["Config"]
  node_config_service["Config Service<br/>config orchestrator<br/>[ConfigService.java]"]
  node_config_cache[("Config Cache<br/>config AST cache")]
  node_config_features["Config Features<br/>config providers"]
end

subgraph group_model["Model"]
  node_specs["Specs<br/>Nextflow semantics"]
  node_plugin_cache[("Plugin Cache<br/>plugin metadata cache")]
  node_script_types["Script Types<br/>type system"]
end

node_server -->|"routes LSP"| node_language_service
node_server -->|"diagnostics"| node_compiler
node_server -->|"workspace state"| node_file_cache
node_language_service -->|"script files"| node_script_service
node_language_service -->|"config files"| node_config_service
node_language_service -->|"settings"| node_server_cfg
node_language_service -->|"feature API"| node_shared_providers
node_language_service -->|"AST helpers"| node_ast_utils
node_script_service -->|"caches AST"| node_script_cache
node_script_service -->|"serves features"| node_script_features
node_script_service -->|"preview graph"| node_dag_preview
node_script_service -->|"script spec"| node_specs
node_script_service -->|"plugins"| node_plugin_cache
node_script_service -->|"type model"| node_script_types
node_config_service -->|"caches AST"| node_config_cache
node_config_service -->|"serves features"| node_config_features
node_config_service -->|"config spec"| node_specs
node_config_service -->|"plugins"| node_plugin_cache
node_config_service -->|"shared semantics"| node_script_types
node_compiler -->|"collects errors"| node_errors
node_compiler -->|"reads sources"| node_file_cache
node_dag_preview -->|"rendering support"| node_util
node_script_features -->|"AST queries"| node_ast_utils
node_config_features -->|"AST queries"| node_ast_utils
node_shared_providers -.->|"specialized by"| node_script_features
node_shared_providers -.->|"specialized by"| node_config_features

click node_server "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/NextflowLanguageServer.java"
click node_language_service "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/LanguageService.java"
click node_compiler "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/compiler/LanguageServerCompiler.java"
click node_errors "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/compiler/LanguageServerErrorCollector.java"
click node_file_cache "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/file/FileCache.java"
click node_shared_providers "https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/services"
click node_ast_utils "https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/ast"
click node_server_cfg "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/LanguageServerConfiguration.java"
click node_script_service "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/script/ScriptService.java"
click node_script_cache "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/script/ScriptAstCache.java"
click node_script_features "https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/services/script"
click node_dag_preview "https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/services/script/dag"
click node_config_service "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/config/ConfigService.java"
click node_config_cache "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/config/ConfigAstCache.java"
click node_config_features "https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/services/config"
click node_specs "https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/spec"
click node_plugin_cache "https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/spec/PluginSpecCache.java"
click node_script_types "https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/script"
click node_util "https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/util"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server toneBlue
class node_language_service,node_compiler,node_errors,node_file_cache,node_shared_providers,node_ast_utils,node_server_cfg,node_util toneAmber
class node_script_service,node_script_cache,node_script_features,node_dag_preview toneMint
class node_config_service,node_config_cache,node_config_features toneRose
class node_specs,node_plugin_cache,node_script_types toneIndigo
```

## Components

### Runtime

Server entrypoint and LSP boundary

- [Language Server](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/NextflowLanguageServer.java): stdio LSP server · Receives editor requests and publishes responses over stdio · `src/main/java/nextflow/lsp/NextflowLanguageServer.java`

### Core

Dispatch, compilation, state, and shared LSP feature APIs

- [Language Service](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/LanguageService.java): router · Dispatches requests to script or config subsystems · `src/main/java/nextflow/lsp/services/LanguageService.java`
- [Compiler](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/compiler/LanguageServerCompiler.java): diagnostics pipeline · Parses and compiles sources, collecting errors for diagnostics · `src/main/java/nextflow/lsp/compiler/LanguageServerCompiler.java`
- [Error Collector](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/compiler/LanguageServerErrorCollector.java): diagnostics sink · Turns compiler errors into LSP diagnostics · `src/main/java/nextflow/lsp/compiler/LanguageServerErrorCollector.java`
- [File Cache](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/file/FileCache.java): workspace state · Tracks file contents and workspace file state · `src/main/java/nextflow/lsp/file/FileCache.java`
- [LSP Providers](https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/services): shared feature APIs · Common completion, hover, definition, reference, rename, symbols, links, formatting, and semantic token interfaces · `src/main/java/nextflow/lsp/services`
- [AST Utils](https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/ast): shared AST helpers · Common AST caching, parent lookup, and completion helpers · `src/main/java/nextflow/lsp/ast`
- [Server Config](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/LanguageServerConfiguration.java): workspace settings · Applies configuration changes and error reporting policy · `src/main/java/nextflow/lsp/services/LanguageServerConfiguration.java`
- [Utilities](https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/util): shared helpers · Logging, JSON, positions, debouncing, and progress notifications · `src/main/java/nextflow/lsp/util`

### Script

Workflow script analysis and editor features

- [Script Service](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/script/ScriptService.java): script orchestrator · Coordinates analysis and features for Nextflow workflow scripts · `src/main/java/nextflow/lsp/services/script/ScriptService.java`
- [Script Cache](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/script/ScriptAstCache.java): script AST cache · Caches parsed workflow script ASTs · `src/main/java/nextflow/lsp/services/script/ScriptAstCache.java`
- [Script Features](https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/services/script): script providers · Completion, hover, definition, references, rename, formatting, symbols, links, code lens, and semantic tokens for scripts · `src/main/java/nextflow/lsp/services/script`
- [DAG Preview](https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/services/script/dag): workflow graph preview · Builds and renders dataflow DAG previews for workflows · `src/main/java/nextflow/lsp/services/script/dag`

### Config

Nextflow config analysis and editor features

- [Config Service](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/config/ConfigService.java): config orchestrator · Coordinates analysis and features for Nextflow config files · `src/main/java/nextflow/lsp/services/config/ConfigService.java`
- [Config Cache](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/services/config/ConfigAstCache.java): config AST cache · Caches parsed config ASTs · `src/main/java/nextflow/lsp/services/config/ConfigAstCache.java`
- [Config Features](https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/services/config): config providers · Completion, hover, links, formatting, and semantic tokens for config files · `src/main/java/nextflow/lsp/services/config`

### Model

Nextflow-specific semantic and type infrastructure

- [Specs](https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/lsp/spec): Nextflow semantics · Project-specific script and config specs plus plugin metadata · `src/main/java/nextflow/lsp/spec`
- [Plugin Cache](https://github.com/nextflow-io/language-server/blob/main/src/main/java/nextflow/lsp/spec/PluginSpecCache.java): plugin metadata cache · Caches plugin specifications and references · `src/main/java/nextflow/lsp/spec/PluginSpecCache.java`
- [Script Types](https://github.com/nextflow-io/language-server/tree/main/src/main/java/nextflow/script): type system · Nextflow/Groovy type checking helpers and shim types · `src/main/java/nextflow/script`

## Connections

- Language Server → Language Service: routes LSP · Entrypoint delegates editor requests to the service router
- Language Server → Compiler: diagnostics · Server surfaces compiler-driven diagnostics to the client
- Language Server → File Cache: workspace state · Server uses cached file contents and file state
- Language Service → Script Service: script files · Routes workflow scripts to the script subsystem
- Language Service → Config Service: config files · Routes config files to the config subsystem
- Language Service → Server Config: settings · Applies workspace configuration and error reporting mode
- Language Service → LSP Providers: feature API · Shares common LSP feature contracts across subsystems
- Language Service → AST Utils: AST helpers · Uses shared AST helpers and completion utilities
- Script Service → Script Cache: caches AST · Reuses parsed workflow ASTs
- Script Service → Script Features: serves features · Drives script completions, hovers, navigation, and formatting
- Script Service → DAG Preview: preview graph · Connects workflow analysis to DAG preview generation
- Script Service → Specs: script spec · Uses Nextflow script semantics for interpretation
- Script Service → Plugin Cache: plugins · Resolves plugin metadata for script analysis
- Script Service → Script Types: type model · Leverages Nextflow/Groovy typing infrastructure
- Config Service → Config Cache: caches AST · Reuses parsed config ASTs
- Config Service → Config Features: serves features · Drives config completions, hovers, links, formatting, and tokens
- Config Service → Specs: config spec · Uses config-specific Nextflow semantics
- Config Service → Plugin Cache: plugins · Uses plugin metadata during config analysis
- Config Service → Script Types: shared semantics · Relies on common language/type behavior where needed
- Compiler → Error Collector: collects errors · Compiler feeds collected errors into diagnostics handling
- Compiler → File Cache: reads sources · Compiler works from workspace file state
- DAG Preview → Utilities: rendering support · Uses utilities for progress, JSON, and coordination
- Script Features → AST Utils: AST queries · Feature providers depend on shared AST helpers
- Config Features → AST Utils: AST queries · Feature providers depend on shared AST helpers
- LSP Providers → Script Features: specialized by · Script subsystem implements shared LSP contracts
- LSP Providers → Config Features: specialized by · Config subsystem implements shared LSP contracts