# konveyor/analyzer-lsp architecture

> Architecture diagram of the GitHub repository konveyor/analyzer-lsp, 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/konveyor/analyzer-lsp
- Repository: https://github.com/konveyor/analyzer-lsp

## Overview

##### Project Type and Purpose
- This project is a rule engine designed for Konveyor that applies rules against codebases by leveraging multiple pluggable providers (including Language Server Protocol providers). Its purpose is to allow configurable rule checking and violation analysis via a CLI (or containerized demo) while supporting external providers in different languages (e.g., Java, .NET, Go, and even YAML and NodeJS).
- Key functionality is provided by reading rule configurations (e.g., rule-example.yaml) and provider settings (provider_settings.json) and then running check processes that use an engine core, event propagation, and provider integrations.

##### Main Components by Reviewing the File Structure
- Command-Line Interface (CLI) and Entry Points:
– The “cmd” directory holds executables such as “analyzer” and “dep”, which are entry points for running the engine from source.
– Dockerfiles at the top level (Dockerfile, demo.Dockerfile) support deployment as containerized apps.
- Rule Engine Core:
– The “engine” directory contains the core logic to evaluate conditions, execute rule checks, and generate violation outputs.
– It also includes tests to ensure core functionality.
- Event Handling and Export:
– The “event” directory covers different aspects of event-related flows (e.g., exporting logs, metrics, tracing, and tag handling).
– Submodules for different export types like Prometheus, OC Agent, and generic printer indicate support for external reporting and monitoring.
- Rule Parsing:
– The “parser” folder includes modules for processing input rule files (YAML) and associated testdata to validate rule format.
- Provider Integration:
– The “provider” directory implements the base and internal provider logic, and it is tightly coupled with the pluggable nature of the engine.
– External providers are further supported in “external-providers” for various environments (e.g., dotnet, java, golang, generic, and yq).
- Language Server Protocol (LSP):
– The “lsp” directory provides components to support the LSP framework/communication (using JSONRPC2) for language-specific rule provision.
– This module leverages definitions from Go’s gopls (stripped down for communication).
- Ancillary Modules:
– “jsonrpc2” and “jsonrpc2_v2” support communications using JSON-RPC, indicating the backend messaging mechanisms between the engine and providers.
– “tracing” helps with distributed tracing (for example, via Jaeger integration).
– “docs”, “examples”, and “debug” directories serve as highly useful support for configuration, demonstration, and testing.

##### Relationships and Interactions
- The CLI (under “cmd/analyzer”) acts as the user’s entry point and orchestrates the configuration of providers (via “provider_settings.json”) and rule file input.
- The core Engine is responsible for processing the provided rules (parsed by components in “parser”) and coordinating with the Providers.
- Providers can be internal (in “provider/internal”) or external (in “external-providers”). They communicate using protocols exposed by the “lsp” and “jsonrpc2” modules. Their configuration is customizable.
- The Event system captures violations and metrics, exporting them using various “event/export” mechanisms (such as to Prometheus, OC agent, etc.).
- Docker and Makefile build scripts support containerized deployment and integration into CI/CD pipelines (GitHub workflows in “.github”).

##### Architectural Patterns and Major Design Principles
- Plugin/Extensibility Pattern: The engine is built to support pluggable providers. The clear separation between the core rule engine and provider-specific logic (both internal and external) is key.
- Layered Architecture: There is a separation between the CLI, core logic (engine), provider integrations, rule parsing, and reporting/event export.
- Use of Standard Protocols: LSP and JSONRPC2 are used for consistent communication between components.
- Containerization: With Dockerfiles and CI workflows, there’s a clear path for building, testing, and deploying container images.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI/Entry Points Subgraph
    subgraph "CLI/Entry Points"
        A1["CLI - Analyzer"]:::core
        A2["CLI - Dep"]:::core
        D["Docker Deployment"]:::deployment
    end

    %% Core Processing Subgraph
    subgraph "Core Processing"
        RECore["Rule Engine Core"]:::core
        RP["Rule Parser"]:::core
        PM["Provider Manager"]:::integration
        EE["Event Exporter"]:::integration
    end

    %% Provider Manager Internal Subgraph
    subgraph "Provider Integrations"
        BI["Built-in Providers"]:::integration
        EX["External Providers"]:::integration
    end

    %% Communication Layer Subgraph
    subgraph "Communication Layer"
        LSP["LSP Module"]:::communication
        JRPC["JSONRPC2 Module"]:::communication
        TR["Tracing Module"]:::communication
    end

    %% Ancillary & Support Subgraph
    subgraph "Ancillary & Support"
        DOCS["Docs"]:::support
        EXMP["Examples"]:::support
        DBG["Debug"]:::support
        CI["CI/CD Pipelines"]:::support
    end

    %% Connections from CLI/Entry Points to Core Processing
    A1 -->|"invoke"| RECore
    A2 -->|"invoke"| RECore
    D -->|"containerizes"| RECore

    %% Connections within Core Processing
    RP -->|"parsedRules"| RECore
    RECore -->|"executesRules"| PM
    RECore -->|"generatesViolations"| EE
    RECore -->|"traceData"| TR

    %% Provider Manager internal breakdown
    PM -->|"loads"| BI
    PM -->|"loads"| EX

    %% Communication interactions with Provider Manager
    PM -->|"calls"| LSP
    LSP -->|"responses"| PM
    PM -->|"calls"| JRPC
    JRPC -->|"responses"| PM

    %% CI/CD supports deployment
    CI -->|"builds"| D

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef integration fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef communication fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef deployment fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef support fill:#dda0dd,stroke:#000,stroke-width:1px;

    %% Click Events
    click A1 "https://github.com/konveyor/analyzer-lsp/tree/main/cmd/analyzer"
    click A2 "https://github.com/konveyor/analyzer-lsp/tree/main/cmd/dep"
    click D "https://github.com/konveyor/analyzer-lsp/tree/main/Dockerfile"
    click RECore "https://github.com/konveyor/analyzer-lsp/tree/main/engine"
    click RP "https://github.com/konveyor/analyzer-lsp/tree/main/parser"
    click BI "https://github.com/konveyor/analyzer-lsp/tree/main/provider"
    click EX "https://github.com/konveyor/analyzer-lsp/tree/main/external-providers"
    click EE "https://github.com/konveyor/analyzer-lsp/tree/main/event"
    click LSP "https://github.com/konveyor/analyzer-lsp/tree/main/lsp"
    click JRPC "https://github.com/konveyor/analyzer-lsp/tree/main/jsonrpc2"
    click TR "https://github.com/konveyor/analyzer-lsp/tree/main/tracing"
    click DOCS "https://github.com/konveyor/analyzer-lsp/tree/main/docs"
    click EXMP "https://github.com/konveyor/analyzer-lsp/tree/main/examples"
    click DBG "https://github.com/konveyor/analyzer-lsp/tree/main/debug"
    click CI "https://github.com/konveyor/analyzer-lsp/blob/main/.github"
```
