# 1panel-dev/kubepi architecture

> Architecture diagram of the GitHub repository 1panel-dev/kubepi, 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/1panel-dev/kubepi
- Repository: https://github.com/1panel-dev/kubepi

## Overview

##### Main Components
- Backend Service: Located mainly in the cmd/server, internal, pkg, and migrate directories. This component is responsible for handling API requests, business logic, data models, and integrating with Kubernetes clusters.
- API Layer: The “internal/api/v1” folder shows versioned API endpoints managing functionalities such as clusters, charts, file handling, LDAP, MFA, SSO, and more.
- Business/Service Layer: Folders under “internal/service/v1” contain business logic grouped by domain (e.g., cluster, chart, user, system, etc.).
- Data Model Layer: “internal/model/v1” holds the data definitions for clusters, users, and other resources.
- Routing & Configuration: “internal/route” and “internal/config” provide the routing rules and configuration management for the backend.
- Frontend UIs: There are at least three separate client applications:
- Dashboard UI: Found in the “web/dashboard” folder, implemented using Vue (with its own routing, components, assets, and state management).
- Kubepi UI: In the “web/kubepi” folder, also a Vue-based application designed for cluster management.
- Terminal UI: In the “web/terminal” folder. This Angular-based module likely provides interactive terminal access to clusters.
- Third-Party Terminal Service: The “thirdparty/gotty” directory integrates a terminal access component (“gotty”) that helps facilitate web-based terminal sessions.
- Deployment/Infrastructure Components: There are Dockerfiles, Kubernetes deployment scripts (docs/deploy, init-kube.sh), compose files, and CI/CD workflows (in the .github/workflows directory) used for deployment, testing, and release management.

##### Relationships and Interactions
- The Frontend Applications (Dashboard, Kubepi, and Terminal UIs) will communicate with the Backend via RESTful APIs and WebSocket connections (for real-time features such as terminal sessions).
- The Backend handles client requests, processes them through its API and service layers, and interacts with the Kubernetes clusters (imported and managed via the API).
- The third-party terminal service (gotty) is integrated into the backend to provide shell and terminal access to nodes.
- Deployment scripts and configuration files ensure that the entire stack is containerized and can be deployed to a Kubernetes cluster or directly on Docker.

##### Architectural Patterns and Design Principles
- Layered Architecture: The backend is clearly organized into layers (API, Service, Model, and Route). This separation of concerns simplifies maintenance and testing.
- Modular Versioning: By placing API endpoints under “internal/api/v1”, it becomes easier to evolve the API without breaking existing clients.
- Frontend Separation: Split into multiple UI modules, each with its own dedicated repository structure and configuration.
- Integration with Kubernetes: The system design relies on Kubernetes as the underlying infrastructure, so integration with K8s APIs, managing clusters, namespaces, pods, and other resources is a key design concern.
- Containerization & Deployment: Use of Dockerfiles, Helm charts (in docs/deploy/charts), and Kubernetes YAMLs for orchestrated deployment, which is essential for production environments.
- Use of Third-Party Components: Integration of gotty for terminal access, demonstrating reuse of mature components to extend functionality.

##### Instructing the Principal Software Engineer
- Inside, create sub-blocks for the backend (with layers for API, services, models, routes) and show how it exposes REST/WebSocket endpoints.
- Another block for “Third-Party Components” (gotty) connected to the backend to illustrate the terminal functionality.
- Finally, include deployment elements like Docker containers, Helm/Kubernetes deployment scripts, and CI/CD pipelines to contextualize the deployment environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% KubePi Main System
    subgraph "KubePi System"
        %% Frontend Clients
        subgraph "Frontend Clients"
            Dashboard["Dashboard UI (Vue)"]:::frontend
            Kubepi["Kubepi UI (Vue)"]:::frontend
            TerminalUI["Terminal UI (Angular)"]:::frontend
        end

        %% Backend Service
        subgraph "Backend Service (Go)"
            Server["Server (cmd/server)"]:::backend
            API["API Layer (internal/api/v1)"]:::backend
            Service["Service Layer (internal/service/v1)"]:::backend
            Model["Data Model Layer (internal/model/v1)"]:::backend
            Route["Routing (internal/route)"]:::backend
            Config["Configuration (internal/config)"]:::backend
            Pkg["Pkg (pkg)"]:::backend
            Migrate["Migrate (migrate)"]:::backend
        end
    end

    %% External Services
    subgraph "External Services"
        K8s["Kubernetes Clusters"]:::external
        Gotty["Third-Party Terminal Service (gotty)"]:::external
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        DeployScripts["Deployment Scripts (docs/deploy)"]:::deployment
        InitKube["Init Kube Script (init-kube.sh)"]:::deployment
        DockerCI["Docker & CI/CD (Dockerfile)"]:::deployment
        Workflows["CI/CD Workflows (.github/workflows)"]:::deployment
    end

    %% Relationships: Frontend to Backend
    Dashboard -->|"calls"| API
    Kubepi  -->|"calls"| API
    TerminalUI -->|"calls"| API

    %% Relationships within Backend
    Server -->|"hosts"| API
    API -->|"processes"| Service
    Service -->|"uses"| Model
    API -->|"delegates"| Route
    API -->|"delegates"| Config
    Service -->|"integrates"| Pkg
    Service -->|"integrates"| Migrate

    %% Backend interactions with External Services
    API -->|"accesses"| Gotty
    Service -->|"manages"| K8s

    %% Deployment connecting to Backend
    DeployScripts -->|"deploys"| Server
    InitKube -->|"deploys"| Server
    DockerCI -->|"builds"| Server
    Workflows -->|"runs"| Server

    %% Styles
    classDef backend fill:#E0BBE4,stroke:#333,stroke-width:2px;
    classDef frontend fill:#FFDFD3,stroke:#333,stroke-width:2px;
    classDef external fill:#BDE0FE,stroke:#333,stroke-width:2px;
    classDef deployment fill:#FFF2CC,stroke:#333,stroke-width:2px;

    %% Click Events for Backend Components
    click API "https://github.com/1panel-dev/kubepi/tree/master/internal/api/v1"
    click Service "https://github.com/1panel-dev/kubepi/tree/master/internal/service/v1"
    click Model "https://github.com/1panel-dev/kubepi/tree/master/internal/model/v1"
    click Route "https://github.com/1panel-dev/kubepi/tree/master/internal/route"
    click Config "https://github.com/1panel-dev/kubepi/tree/master/internal/config"
    click Server "https://github.com/1panel-dev/kubepi/tree/master/cmd/server"
    click Pkg "https://github.com/1panel-dev/kubepi/tree/master/pkg"
    click Migrate "https://github.com/1panel-dev/kubepi/tree/master/migrate"

    %% Click Events for Frontend Clients
    click Dashboard "https://github.com/1panel-dev/kubepi/tree/master/web/dashboard"
    click Kubepi "https://github.com/1panel-dev/kubepi/tree/master/web/kubepi"
    click TerminalUI "https://github.com/1panel-dev/kubepi/tree/master/web/terminal"

    %% Click Event for Third-Party Terminal Service
    click Gotty "https://github.com/1panel-dev/kubepi/tree/master/thirdparty/gotty"

    %% Click Events for Deployment Components
    click DeployScripts "https://github.com/1panel-dev/kubepi/tree/master/docs/deploy"
    click InitKube "https://github.com/1panel-dev/kubepi/blob/master/init-kube.sh"
    click DockerCI "https://github.com/1panel-dev/kubepi/tree/master/Dockerfile"
    click Workflows "https://github.com/1panel-dev/kubepi/tree/master/.github/workflows"
```
