# kdash-rs/kdash architecture

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

- Interactive diagram: https://gitdiagram.com/kdash-rs/kdash
- Repository: https://github.com/kdash-rs/kdash

## Overview

##### Major Components
- Terminal User Interface (TUI) – Driven by libraries such as ratatui and crossterm, this is the front-facing UI rendered in the terminal.
- Command & Input Handling – The cmd and event modules (in src/cmd/ and src/event/) manage user commands, keybindings, and event propagation.
- Kubernetes API Client Integration – The application uses the kube-rs library and related modules (most logic in src/app/) to interact with various Kubernetes resources (pods, deployments, configmaps, etc.). This layer will be responsible for calling Kubernetes’ REST APIs and processing the returned data.
- Networking & Async Tasks – Managed via Tokio for asynchronous operations where network calls and polling (as indicated by the poll and tick rate command-line flags) are essential. The network module (src/network/) encapsulates these responsibilities.
- Business Logic/Resource Models – Located primarily in src/app/models.rs and adjacent modules, this layer converts raw API responses into application-specific resource representations.
- Utility Functions – Spread across modules including src/app/utils.rs and src/ui/utils.rs, these support various functionalities such as formatting, error handling, and other helper routines.
- Packaging & Deployment Artifacts – Deployment scripts (in the deployment/ folder) for Homebrew, Scoop, Chocolatey, Dockerfile, and Kubernetes YAML files (like k8s.yml) that show how KDash is containerized and distributed.
- Testing & CI/CD – GitHub workflows, Makefile, and test_data directory for automated testing and continuous integration.

##### Relationships and Data Flow
- The User interacts directly with the TUI.
- Input commands are captured and passed to the Input/Event Handler modules.
- The Event Handler sends commands to the Business Logic layer, which in turn uses Kubernetes API client integration (via kube-rs) to fetch or stream resource data.
- Async networking operations (managed by Tokio along with the network module) handle polling tasks for real-time updates.
- Data retrieved from Kubernetes is then processed, translated into TUI-visible formats by the models and view helpers, and rendered on the screen.
- Utility functions are used throughout these interactions for tasks like copying logs to clipboard or formatting YAML output.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each top-level component (UI, Command processing, Networking/API interactions) is modularized in its own folder or file group.
- Asynchronous Execution: Use of Tokio ensures non-blocking operations, particularly important given the polling of Kubernetes resources.
- CLI/TUI Design: The division between interface and underlying business logic simplifies maintenance.
- Modularity: The source code is organized into submodules (for different Kubernetes resources) which encapsulate resource-specific logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User"]:::user

    subgraph "UI Layer"
        TUI["TUI Interface"]:::ui
        UTIL_UI["UI Utility Functions"]:::util
    end

    subgraph "Command & Event Handling"
        CMD["Command & Input Handler"]:::input
    end

    subgraph "Business Logic Layer"
        BL["Business Logic/Resource Models"]:::logic
        UTIL_APP["App Utility Functions"]:::util
    end

    subgraph "Kubernetes Integration"
        API["Kubernetes API Client Integration"]:::integration
    end

    subgraph "Async Networking"
        NET["Networking & Async Tasks"]:::network
    end

    subgraph "Deployment & Packaging"
        DEP["Deployment Packaging"]:::deploy
    end

    subgraph "CI/CD & Testing"
        CI["Testing & CI/CD"]:::cicd
    end

    %% Data Flow
    U -->|"initiates"| TUI
    TUI -->|"captures_input"| CMD
    CMD -->|"sends_event"| BL
    BL -->|"requests_data"| API
    API -->|"async_calls"| NET
    NET -->|"returns_updates"| BL
    BL -->|"renders"| TUI

    %% Utility Functions Support (dotted lines)
    UTIL_UI --- TUI
    UTIL_APP --- BL

    %% Deployment and CI/CD as ancillary components
    BL -->|"builds"| DEP
    DEP -->|"packaged"| CI

    %% Click Events
    click TUI "https://github.com/kdash-rs/kdash/tree/main/src/ui/"
    click CMD "https://github.com/kdash-rs/kdash/blob/main/src/cmd/mod.rs"
    click BL "https://github.com/kdash-rs/kdash/blob/main/src/app/models.rs"
    click API "https://github.com/kdash-rs/kdash/tree/main/src/app/"
    click NET "https://github.com/kdash-rs/kdash/tree/main/src/network/"
    click UTIL_APP "https://github.com/kdash-rs/kdash/blob/main/src/app/utils.rs"
    click UTIL_UI "https://github.com/kdash-rs/kdash/blob/main/src/ui/utils.rs"
    click DEP "https://github.com/kdash-rs/kdash/tree/main/deployment/"
    click CI "https://github.com/kdash-rs/kdash/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef user fill:#FFDD89,stroke:#333,stroke-width:2px
    classDef ui fill:#C1E1C1,stroke:#333,stroke-width:2px
    classDef input fill:#F9D5E5,stroke:#333,stroke-width:2px
    classDef logic fill:#B5EAEA,stroke:#333,stroke-width:2px
    classDef integration fill:#FFE5B4,stroke:#333,stroke-width:2px
    classDef network fill:#D5E1DF,stroke:#333,stroke-width:2px
    classDef util fill:#E6E6FA,stroke:#333,stroke-width:2px
    classDef deploy fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef cicd fill:#F0E68C,stroke:#333,stroke-width:2px
```
