# konveyor/kai architecture

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

- Interactive diagram: https://gitdiagram.com/konveyor/kai
- Repository: https://github.com/konveyor/kai

## Overview

##### High-level layers and key components
- Client/Integration Layer – Interfaces where users interact with Kai (for example, via VSCode extensions as referenced in the README, demo scripts in “example”, and notebooks that guide usage).
- Core Business Logic – The modules that perform code analysis, modernize code, and generate fixes.
- Communication & API Layer – Using JSON-RPC and the Go-based analyzer service.
- Data & Storage – Caching modules, configuration data, historical Konveyor analysis reports and migration incident reports.
- Web/Server Components – The “kai_solution_server” which provides RESTful routes for solution handling, incident store processing and integration with the hub.
- Auxiliary & Support Modules – Notebooks, tests, documentation, CI/CD definitions, and build configurations.

##### Every module, grouping them by their functionality
- Kai Core (Python):
- Analyzer Modules: “kai/analyzer.py”, “kai/analyzer_types.py” which perform static code analysis.
- Cache & Constants: “kai/cache.py” and “kai/constants.py” used for caching LLM responses and holding global settings.
- Data Storage: “kai/data” directory that holds llm_cache and related cached analysis results.
- JSON-RPC & Communication:
- “kai/jsonrpc” module, including “core.py”, “callbacks.py”, “logs.py”, “models.py”, “streams.py”, “util.py”. This layer deals with remote procedure call communication.
- LLM Interfacing:
- “kai/llm_interfacing” contains “model_provider.py” and the token output callbacks. Its purpose is to abstract interactions with external LLM providers.
- Logging:
- “kai/logging” which holds “kai_trace.py” and “logging.py” to trace events and debug operations.
- Reactive Code Planner:
- “kai/reactive_codeplanner” is one of the most complex modules. It includes:
▪ Agent modules: “agent/analyzer_fix”, “agent/ast_diff”, “agent/dependency_agent”, “agent/maven_compiler_fix”, and “agent/reflection_agent.py” – each responsible for different aspects of code modification.
▪ Task Manager and Task Runner: “kai/reactive_codeplanner/task_manager” and “kai/reactive_codeplanner/task_runner” (with subdirectories for analyzer LSP, compiler, and dependency task runners) which orchestrate jobs.
▪ Virtual File System (vfs): “kai/reactive_codeplanner/vfs” for snapshotting repository contexts.
▪ The main entry point “kai/reactive_codeplanner/main.py” that ties these pieces together.
- RPC Server:
- “kai/rpc_server” contains modules such as “chat.py”, “main.py”, “server.py”, and “util.py”. These provide direct communication endpoints for remote interactions.
- Go-Based Analyzer (kai_analyzer_rpc):
- Written in Go, this includes “kai_analyzer_rpc/main.go” and supporting packages like “pkg/codec”, “pkg/scope”, “pkg/service/analyzer.go”, and “pkg/tracing” for performance tracing.
- Solution Server:
- “kai_solution_server” provides server functionality with “main.py”, routing under “routes/”, build scripts under “build/”, and templates for solution presentation. It is responsible for integrating analysis reports and solution generation.
- Additional modules:
- “kai/kai_config.py” for configuration settings.
- “kai_analyzer_rpc/provider/java” for Java-specific analysis.
- “tests” directory contains unit and integration tests for various modules.
- “docs” contains design, configuration, design patterns, and sample scenarios.
- “notebooks” provide interactive demonstrations, evaluation examples, and even experiments—for both development and research purposes.

##### Relationships and interactions between these components
- Data Flow:
- The Client/Integration Layer sends user input (or file snapshots) into the Core Engine.
- The Analyzer (from the kai core) processes static code and triggers the Reactive Code Planner functions for generating transformation steps.
- For code modernization suggestions, the LLM Interfacing module sends requests to external LLM providers (using Retrieval Augmented Generation with historical context from Konveyor analysis).
- Communication between components is coordinated via the JSON-RPC modules and the serving endpoints provided by the “kai/rpc_server” and “kai_analyzer_rpc” (Go) modules.
- The “kai_solution_server” aggregates the generated solutions, applies templates (Jinja in “kai_solution_server/data/templates”), and serves these through RESTful API endpoints.
- Feedback Loops:
- Caching (kai/cache) and persistent data storage (kai/data) contribute to learning from past migrations and help refine recommendations.
- Logging and tracing (kai/logging and Go tracing) provide monitoring and debugging support.

##### Architectural Principles and Patterns
- Modular design: Each component (analysis, planning, LLM interfacing, RPC communication, UI integration) is a separate module.
- Layered architecture: Separate layers exist for data access, business logic, and presentation/service.
- Microservices: The use of independent services (such as the Go analyzer RPC service and the Python-based solution server) which communicate via well-defined interfaces.
- Extensibility: The presence of custom rules (under “docs/custom_ruleset-example” and “example/default_rules”) and dynamic templates (Jinja files in the solution server) illustrates a design that can be extended as new modernization rules emerge.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Client/Integration Layer
    subgraph "Client/Integration Layer"
        client_readme["README.md"]:::integration
        client_example["example"]:::integration
        client_notebooks["notebooks"]:::integration
    end

    %% Core Business Logic
    subgraph "Core Business Logic"
        core_analyzer["kai/analyzer.py"]:::python
        core_analyzer_types["kai/analyzer_types.py"]:::python
        core_cache["kai/cache.py"]:::python
        core_constants["kai/constants.py"]:::python
        core_data["kai/data"]:::python
    end

    %% Communication & API Layer (JSON-RPC)
    subgraph "Communication & API Layer (JSON-RPC)"
        jsonrpc["kai/jsonrpc"]:::communication
    end

    %% LLM Interfacing
    subgraph "LLM Interfacing"
        llm_interfacing["kai/llm_interfacing"]:::llm
    end

    %% Logging
    subgraph "Logging"
        logging_module["kai/logging"]:::logging
    end

    %% Reactive Code Planner
    subgraph "Reactive Code Planner"
        reactive_main["kai/reactive_codeplanner/main.py"]:::reactive
        reactive_vfs["kai/reactive_codeplanner/vfs"]:::reactive
        reactive_task_manager["kai/reactive_codeplanner/task_manager"]:::reactive
        reactive_task_runner["kai/reactive_codeplanner/task_runner"]:::reactive
        subgraph "Agent Modules"
            agent_analyzer_fix["agent/analyzer_fix"]:::reactive
            agent_ast_diff["agent/ast_diff"]:::reactive
            agent_dependency["agent/dependency_agent"]:::reactive
            agent_maven_fix["agent/maven_compiler_fix"]:::reactive
            agent_reflection["agent/reflection_agent.py"]:::reactive
        end
    end

    %% RPC Server
    subgraph "RPC Server"
        rpc_server["kai/rpc_server"]:::python
    end

    %% Go-Based Analyzer
    subgraph "Go-Based Analyzer"
        go_analyzer["kai_analyzer_rpc"]:::go
    end

    %% Solution Server
    subgraph "Solution Server"
        solution_server["kai_solution_server"]:::solution
    end

    %% Configuration Module
    config_module["kai/kai_config.py"]:::config

    %% Auxiliary & Support Modules
    subgraph "Auxiliary & Support Modules"
        docs["docs"]:::support
        tests["tests"]:::support
        support_notebooks["notebooks"]:::support
        cicd[".github/workflows"]:::support
    end

    %% Data & Storage flow (implicit within Core Business Logic)
    core_data -- "provides historical context" --> core_analyzer

    %% Relationships
    client_example -- "triggers_analysis" --> core_analyzer
    core_analyzer -- "starts_planning" --> reactive_main
    core_analyzer -- "requests_modernization" --> llm_interfacing
    llm_interfacing -- "communicates_via" --> jsonrpc
    jsonrpc -- "routes_to" --> rpc_server
    rpc_server -- "calls_service" --> go_analyzer
    go_analyzer -- "traces_performance" --> logging_module
    reactive_main -- "logs_events" --> logging_module
    reactive_main -- "aggregates_solutions" --> solution_server
    rpc_server -- "exposes_endpoints" --> solution_server
    config_module -- "configures" --> core_constants

    %% Auxiliary relationships
    docs -- "informs" --> config_module
    tests -- "validate" --> core_analyzer
    cicd -- "triggers" --> tests
    support_notebooks -- "enhance_usage" --> client_notebooks

    %% Click Events
    click client_readme "https://github.com/konveyor/kai/blob/main/README.md"
    click client_example "https://github.com/konveyor/kai/tree/main/example"
    click client_notebooks "https://github.com/konveyor/kai/tree/main/notebooks"
    
    click core_analyzer "https://github.com/konveyor/kai/blob/main/kai/analyzer.py"
    click core_analyzer_types "https://github.com/konveyor/kai/blob/main/kai/analyzer_types.py"
    click core_cache "https://github.com/konveyor/kai/blob/main/kai/cache.py"
    click core_constants "https://github.com/konveyor/kai/blob/main/kai/constants.py"
    click core_data "https://github.com/konveyor/kai/tree/main/kai/data"
    
    click jsonrpc "https://github.com/konveyor/kai/tree/main/kai/jsonrpc"
    
    click llm_interfacing "https://github.com/konveyor/kai/tree/main/kai/llm_interfacing"
    
    click logging_module "https://github.com/konveyor/kai/tree/main/kai/logging"
    
    click reactive_main "https://github.com/konveyor/kai/blob/main/kai/reactive_codeplanner/main.py"
    click reactive_vfs "https://github.com/konveyor/kai/tree/main/kai/reactive_codeplanner/vfs"
    click reactive_task_manager "https://github.com/konveyor/kai/tree/main/kai/reactive_codeplanner/task_manager"
    click reactive_task_runner "https://github.com/konveyor/kai/tree/main/kai/reactive_codeplanner/task_runner"
    click agent_analyzer_fix "https://github.com/konveyor/kai/tree/main/kai/reactive_codeplanner/agent/analyzer_fix"
    click agent_ast_diff "https://github.com/konveyor/kai/tree/main/kai/reactive_codeplanner/agent/ast_diff"
    click agent_dependency "https://github.com/konveyor/kai/tree/main/kai/reactive_codeplanner/agent/dependency_agent"
    click agent_maven_fix "https://github.com/konveyor/kai/tree/main/kai/reactive_codeplanner/agent/maven_compiler_fix"
    click agent_reflection "https://github.com/konveyor/kai/blob/main/kai/reactive_codeplanner/agent/reflection_agent.py"
    
    click rpc_server "https://github.com/konveyor/kai/tree/main/kai/rpc_server"
    
    click go_analyzer "https://github.com/konveyor/kai/tree/main/kai_analyzer_rpc"
    
    click solution_server "https://github.com/konveyor/kai/tree/main/kai_solution_server"
    
    click config_module "https://github.com/konveyor/kai/blob/main/kai/kai_config.py"
    
    click docs "https://github.com/konveyor/kai/tree/main/docs"
    click tests "https://github.com/konveyor/kai/tree/main/tests"
    click support_notebooks "https://github.com/konveyor/kai/tree/main/notebooks"
    click cicd "https://github.com/konveyor/kai/tree/main/.github/workflows"

    %% Styles
    classDef integration fill:#f8c471,stroke:#aa3f1c,stroke-width:2px;
    classDef python fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef communication fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
    classDef llm fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef logging fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef reactive fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef go fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef solution fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef config fill:#f0b27a,stroke:#e67e22,stroke-width:2px;
    classDef support fill:#d6eaf8,stroke:#2e86c1,stroke-width:2px;
```
