# iximiuz/cdebug architecture

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

- Interactive diagram: https://gitdiagram.com/iximiuz/cdebug
- Repository: https://github.com/iximiuz/cdebug

## Overview

This project is a command‐line tool written in Go called “cdebug” whose primary purpose is to serve as a “swiss army knife” for container debugging. It provides commands like exec and port-forward to allow users to troubleshoot and interact with containers (or even Kubernetes pods) using various container runtimes (Docker, containerd, Kubernetes, and even nerdctl). The tool’s functionality is implemented through a combination of command subdirectories, dedicated packages for interfacing with container runtimes, and integration/E2E tests.

##### Main components
- CLI Entry Point & Command Dispatcher
- The project uses a main Go file (main.go) and the “cmd” directory which contains subcommands like “exec” and “portforward”. These represent the core entry points where user commands are parsed and dispatched.
- Core Business Logic Layer
- This layer is composed of helper packages and utility libraries located in “pkg”. Subdirectories like “pkg/cliutil”, “pkg/containerd”, “pkg/docker”, “pkg/kubernetes”, “pkg/jsonutil”, “pkg/tty”, “pkg/signalutil”, and “pkg/uuid” encapsulate functionality for managing container interactions, JSON handling, signal processing, and terminal management.
- Container Runtime Abstractions
- Specific adapter packages (e.g., pkg/docker, pkg/containerd, pkg/kubernetes) abstract the details of interacting with different container platforms. These components are key in translating the “exec” and “port-forward” commands into appropriate API calls and runtime actions.
- CI/CD Integration & Testing Infrastructure
- The “.github” and “ci” directories indicate automated workflows for testing and release (using GoReleaser, workflows, and dependabot) as well as integration tests (notably the “e2e” folder which contains end-to-end tests for exec and port-forward functionality).

##### Relationships and interactions between components
- The CLI layer (cmd/) takes user input and then calls into the core business logic.
- The core logic, by coordinating with the runtime adapters in pkg/docker, pkg/containerd, and pkg/kubernetes, interacts with container engines or Kubernetes clusters.
- When handling an “exec” command, the CLI delegates to the corresponding routine that picks the appropriate adapter and prepares the “debugger sidecar” container, setting up symlinks and chroot’s based on the target container’s root filesystem.
- For port forwarding, the system spawns a forwarding container (using a socat-based mechanism as per the README) that handles traffic routing.

##### Architectural patterns or design principles
- Modularity: Each container runtime adapter is isolated in its own package.
- Separation of Concerns: The command parsing, business logic, and direct container API interactions are clearly separated.
- Extensibility: The architecture supports future expansions (e.g., adding more container platforms or features like remote port forwarding).

##### Relevant technologies and frameworks
- Go programming language – for compiling into a statically linked binary.
- CI tools – GitHub Actions defined in .github/workflows and release tools like GoReleaser (.goreleaser.yaml).
- Container runtimes such as Docker, containerd, and Kubernetes.
- Supporting libraries for JSON manipulation and terminal handling.

##### Detail and succinctness
- Be as detailed as possible by mapping out every module along with its interactions.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "CLI Layer"
        A["CLI Entry Point"]:::cli
        A1["main.go"]:::file
        A2["cmd/"]:::directory
    end

    subgraph "Command Implementations"
        B["Execution Engine (cdebug exec)"]:::exec
        B1["cmd/exec"]:::directory
        C["Port-Forward Engine (cdebug port-forward)"]:::pforward
        C1["cmd/portforward/portforward.go"]:::file
    end

    subgraph "Core Business Utilities"
        D["Utility Libraries"]:::util
        D1["pkg/"]:::directory
    end

    subgraph "Container Runtime Adapters"
        E1["Docker Adapter"]:::ctr
        E1a["pkg/docker/client.go"]:::file
        E2["Containerd Adapter"]:::ctr
        E2a["pkg/containerd"]:::directory
        E3["Kubernetes Adapter"]:::ctr
        E3a["pkg/kubernetes"]:::directory
    end

    subgraph "CI/CD & Testing"
        F["CI/CD Pipeline"]:::cicd
        F1[".github"]:::directory
        F2[".goreleaser.yaml"]:::file
        F3["ci/"]:::directory
        G["E2E Testing"]:::e2e
        G1["e2e/"]:::directory
    end

    A -->|"dispatch:exec"| B
    A -->|"dispatch:portforward"| C
    B -->|"utilizes"| D
    C -->|"utilizes"| D
    B -->|"invokes"| E1
    B -->|"invokes"| E2
    B -->|"invokes"| E3
    C -->|"invokes"| E1
    C -->|"invokes"| E2
    C -->|"invokes"| E3
    F -->|"builds"| A
    G -->|"tests"| A

    click A1 "https://github.com/iximiuz/cdebug/blob/main/main.go"
    click A2 "https://github.com/iximiuz/cdebug/tree/main/cmd/"
    click B1 "https://github.com/iximiuz/cdebug/tree/main/cmd/exec"
    click C1 "https://github.com/iximiuz/cdebug/blob/main/cmd/portforward/portforward.go"
    click D1 "https://github.com/iximiuz/cdebug/tree/main/pkg/"
    click E1a "https://github.com/iximiuz/cdebug/blob/main/pkg/docker/client.go"
    click E2a "https://github.com/iximiuz/cdebug/tree/main/pkg/containerd"
    click E3a "https://github.com/iximiuz/cdebug/tree/main/pkg/kubernetes"
    click F1 "https://github.com/iximiuz/cdebug/blob/main/.github"
    click F2 "https://github.com/iximiuz/cdebug/blob/main/.goreleaser.yaml"
    click F3 "https://github.com/iximiuz/cdebug/tree/main/ci/"
    click G1 "https://github.com/iximiuz/cdebug/tree/main/e2e/"

    classDef cli fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef file fill:#FFE0B2,stroke:#333,stroke-width:2px;
    classDef directory fill:#FFD699,stroke:#333,stroke-width:2px;
    classDef exec fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef pforward fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef util fill:#BBDEFB,stroke:#333,stroke-width:2px;
    classDef ctr fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef cicd fill:#C5CAE9,stroke:#333,stroke-width:2px;
    classDef e2e fill:#DCEDC8,stroke:#333,stroke-width:2px;
```
