# weibaohui/kom architecture

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

- Interactive diagram: https://gitdiagram.com/weibaohui/kom
- Repository: https://github.com/weibaohui/kom

## Overview

##### Project Type and Purpose
- Kom is a Kubernetes operations toolkit – in effect an SDK-level wrapper around client-go/kubectl. It supports CRUD operations, SQL-like queries on resources, multi-cluster & CRD management, and a callback mechanism for extending behavior.
- It’s a backend tool/library that can be used either as a standalone CLI utility or integrated into wider MCP (Multi-Cluster Processing) toolchains (e.g., k8m, Cursor, etc.).

##### Analyzing the File Structure
- Top-level directories and files such as “kom”, “mcp”, “callbacks”, “utils”, and “example” indicate a separation of concerns:
- The “kom” folder contains the core functionality (control operations, resource management, resource description, SQL query processing, and dynamic operations).
- The “mcp” folder contains the multi-cluster server aspects that expose endpoints (supporting both SSE and stdio) and include sub-tools that wrap various Kubernetes operations.
- The “callbacks” directory holds a set of functions that plug into various operations (get, list, create, update, etc.) to provide extensibility.
- “utils” provides common helper functions (caching, type conversion, network tools, etc.).
- “example” provides test cases and sample usage scenarios.
- Key configuration/build files (go.mod, .github/workflows) indicate that the project is built using Go and CI/CD is integrated.

- Client/CLI/Application Layer:
- Represents how users invoke Kom. This might be a CLI command (via main.go) or integration into tools that invoke Kom operations.
- Core Kom Engine:
- Represented by the “kom” module: includes resource controllers (e.g., Ctl() components such as ctl_cronjob, ctl_deploy, ctl_ds, etc.), SQL processing (sql.go, sql_builder.go, statement.go), dynamic operations, and description functions.
- Callback Manager:
- MCP Server (Multi-Cluster Management):
- Illustrated from the “mcp” directory. It supports starting an MCP server (via mcp/server.go) with endpoints (e.g., /sse) and integrating with external tools in sse or stdio modes.
- Cluster Registry and Multi-Cluster Support:
- A “Cluster Manager” component that registers multiple Kubernetes clusters. The methods in kom/cluster.go and related files register cluster configurations from the host’s kubeconfig or in-cluster settings.
- Kubernetes API Interaction:
- A component representing the external Kubernetes clusters (or their API servers), which the Kom engine communicates with to perform resource CRUD, watch, and SQL queries.
- Utility/Helper Module:
- Represented by “utils”, used across all layers to support type conversions, caching, computation of resource usage, etc.

##### Relationships and Data Flow
- Users (or external tools) invoke commands via the CLI or integrated UI.
- The invocation is handled by the Core Kom Engine. It passes through the Callback Manager as pre- and post-operation hooks.
- Operations (CRUD, patch, command execution, file manipulations) are then dispatched via “Ctl” methods in the “kom” module.
- For multi-cluster scenarios, the MCP Server oversees the registration and routing of commands to the appropriate registered clusters.
- SQL queries (via the specialized SQL processor in Kom) translate user queries into resource requests against Kubernetes API servers.
- The Engine uses utility functions (from “utils”) for additional processing (e.g., caching, JSON conversions, network interactions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client / Integration Layer"
        CL["Client / Integration Layer"]:::client
    end

    subgraph "Kom Engine Core"
        KE["Kom Engine Core"]:::engine
        RC["Resource Controllers"]:::engine
        SQL["SQL Query Processor"]:::engine
        DC["Dynamic/CRD Handler"]:::engine
    end

    subgraph "Callback Manager"
        CB["Callback Manager"]:::callback
    end

    subgraph "Cluster Registry & Multi-Cluster Manager"
        CR["Cluster Registry & Multi-Cluster Manager"]:::cluster
    end

    subgraph "MCP Server"
        MS["MCP Server (Multi-Cluster API)"]:::server
    end

    subgraph "Utility Module"
        UT["Utility/Helper Module"]:::utils
    end

    subgraph "External Systems"
        KA["Kubernetes API Servers"]:::external
    end

    %% Data Flow
    CL -->|"invokes"| KE
    KE -->|"uses"| RC
    KE -->|"uses"| SQL
    KE -->|"uses"| DC
    KE -->|"pre/post_hook"| CB
    KE -->|"registers"| CR
    KE -->|"CRUD_and_watch"| KA
    KA -->|"responses_to"| KE
    CR -->|"multi-cluster_ops"| MS
    MS -->|"exposes_SSE_stdio"| KA
    UT ---|"supports"| KE
    UT ---|"aids"| CB
    UT ---|"assists"| CR

    %% Click Events
    click CL "https://github.com/weibaohui/kom/blob/main/main.go"
    click KE "https://github.com/weibaohui/kom/tree/main/kom/"
    click CB "https://github.com/weibaohui/kom/tree/main/callbacks/"
    click MS "https://github.com/weibaohui/kom/blob/main/mcp/server.go"
    click CR "https://github.com/weibaohui/kom/blob/main/kom/cluster.go"
    click UT "https://github.com/weibaohui/kom/tree/main/utils/"

    %% Style Classes
    classDef client fill:#a9d0f5,stroke:#333,stroke-width:2px;
    classDef engine fill:#f4d03f,stroke:#333,stroke-width:2px;
    classDef callback fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef cluster fill:#fadbd8,stroke:#333,stroke-width:2px;
    classDef server fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef utils fill:#d6eaf8,stroke:#333,stroke-width:2px;
    classDef external fill:#e8daef,stroke:#333,stroke-width:2px;
```
