# underctrl-io/commandkit architecture

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

- Interactive diagram: https://gitdiagram.com/underctrl-io/commandkit
- Repository: https://github.com/underctrl-io/commandkit

## Overview

##### Project type and purpose
- This is a monorepo for “commandkit,” a plugin-based Discord bot meta-framework.
- It contains:
- A core library (`packages/commandkit`) plus companion plugins (`ai`, `analytics`, `cache`, `i18n`, `legacy`, `queue`, `redis`, `tasks`).
- A CLI tool to scaffold new bots (`packages/create-commandkit`).
- A sample “test-bot” app demonstrating usage (`apps/test-bot`).
- A documentation website (`apps/website`) built with Docusaurus.
- A Devtools suite split into a UI SPA (`packages/devtools-ui`) and a backend API server (`packages/devtools`).
- Build & release orchestrated with pnpm workspaces and Turborepo, plus GitHub Actions workflows for CI/CD.

##### File structure analysis
- Top-level: `.github/workflows`, `pnpm-workspace.yaml`, `turbo.json` → CI, publish pipelines, monorepo orchestration.
- `packages/…`: each folder is a separately versioned/published npm package (core, plugins, CLI, devtools, tsconfig presets).
- `apps/…`: two full-stack “applications”:
- `apps/test-bot`: a Discord bot built on commandkit + plugins.
- `apps/website`: the public documentation site.
- `scripts/…`: internal doc generation tooling.

##### README insights
- “commandkit” is a discord.js meta-framework.
- Primary deliverables are the npm packages (core + plugins) and companion apps (CLI, example bot, docs site).

a. Main components
- Monorepo layer: pnpm / Turborepo / GitHub Actions
- Package modules:
- Core library (`commandkit`)
- Plugins (`ai`, `analytics`, `cache`, `i18n`, `legacy`, `queue`, `redis`, `tasks`)
- CLI scaffolder (`create-commandkit`)
- Devtools server + UI
- Sample application (`test-bot`)
- Documentation website
- External dependencies: Discord API, npm Registry, PostHog/Umami (analytics), Redis/BullMQ/SQLite (pluggable storage)
b. Relationships & interactions
- Developer → uses CLI to scaffold a new bot → built on core + chosen plugins → deployed to Discord
- Test-bot app imports core + plugin packages
- Devtools UI ↔ Devtools server (REST) ↔ underlying packages for configuration, auth, monitoring
- `apps/website` reads auto-generated API docs (via `scripts/docs`) and serves static site
- CI/CD pipelines watch code changes → build/test → publish packages to npm → deploy docs
c. Architectural patterns
- Monorepo modularization by domain (core, plugins, apps, tools)
- Plugin architecture (core dispatches to runtime/compile-time plugins)
- Example/sample application demonstrating the framework
- Separate docs site decoupled from code but integrated into CI
- Devtools split into frontend SPA + backend API
d. Key technologies
- Node.js + TypeScript
- pnpm workspaces & Turborepo
- Docusaurus (docs)
- GitHub Actions (CI/CD)
- Discord.js (runtime target)
- Redis, BullMQ, SQLite (pluggable queues & storage)
- REST + Axios (Devtools UI ↔ server)

##### Final advice
- Every major piece (monorepo orchestrator, libraries, plugins, CLI, sample app, docs site, devtools).
- Plugin-based, modular nature.
- How components relate to external systems (Discord, npm registry, analytics backends).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Orchestrator
    subgraph "Monorepo Orchestrator"
        direction TB
        CI["GitHub Actions\n(.github/workflows)"]:::orchestrator
        PNP["pnpm-workspace.yaml"]:::orchestrator
        TURBO["turbo.json"]:::orchestrator
    end

    %% Libraries & Plugins
    subgraph "Libraries & Plugins"
        direction TB
        Core["commandkit core"]:::lib
        AI["@commandkit/ai plugin"]:::lib
        Analytics["@commandkit/analytics plugin"]:::lib
        Cache["@commandkit/cache plugin"]:::lib
        I18n["@commandkit/i18n plugin"]:::lib
        Legacy["@commandkit/legacy plugin"]:::lib
        Queue["@commandkit/queue plugin"]:::lib
        RedisP["@commandkit/redis plugin"]:::lib
        Tasks["@commandkit/tasks plugin"]:::lib
    end

    %% Tools
    subgraph "Tools"
        direction TB
        CLI["create-commandkit CLI"]:::tool
        subgraph "Devtools"
            direction TB
            DevUI["Devtools UI"]:::tool
            DevAPI["Devtools API Server"]:::tool
        end
    end

    %% Applications
    subgraph "Applications"
        direction TB
        TestBot["Test-Bot App"]:::app
        Website["Documentation Website"]:::app
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Discord["Discord API"]:::external
        NPM["npm Registry"]:::external
        AnalyticsSvc["PostHog/Umami"]:::external
        Storage["Redis/BullMQ/SQLite"]:::external
    end

    %% Connections
    CI -->|build/test/publish| Core
    CI -->|build/test/publish| AI
    CI -->|build/test/publish| Analytics
    CI -->|build/test/publish| Cache
    CI -->|build/test/publish| I18n
    CI -->|build/test/publish| Legacy
    CI -->|build/test/publish| Queue
    CI -->|build/test/publish| RedisP
    CI -->|build/test/publish| Tasks
    CI -->|build/test/publish| CLI
    CI -->|build/test/publish| DevUI
    CI -->|build/test/publish| DevAPI
    CI -->|build/test/deploy| Website

    CLI -->|scaffold bot| TestBot
    TestBot -->|imports| Core
    TestBot -->|imports| AI
    TestBot -->|imports| Analytics
    TestBot -->|imports| Cache
    TestBot -->|imports| I18n
    TestBot -->|imports| Legacy
    TestBot -->|imports| Queue
    TestBot -->|imports| RedisP
    TestBot -->|imports| Tasks
    TestBot -->|connects to| Discord

    DevUI <-->|REST / Axios| DevAPI
    DevAPI -->|uses| Core
    DevAPI -->|uses| AI
    DevAPI -->|uses| Analytics
    DevAPI -->|uses| Cache
    DevAPI -->|uses| I18n
    DevAPI -->|uses| Legacy
    DevAPI -->|uses| Queue
    DevAPI -->|uses| RedisP
    DevAPI -->|uses| Tasks

    Website -->|serves static docs| NPM
    Website -->|collects analytics| AnalyticsSvc

    %% Click Events
    click CI "https://github.com/underctrl-io/commandkit/tree/main/.github/workflows/"
    click PNP "https://github.com/underctrl-io/commandkit/blob/main/pnpm-workspace.yaml"
    click TURBO "https://github.com/underctrl-io/commandkit/blob/main/turbo.json"
    click Core "https://github.com/underctrl-io/commandkit/tree/main/packages/commandkit/"
    click AI "https://github.com/underctrl-io/commandkit/tree/main/packages/ai/"
    click Analytics "https://github.com/underctrl-io/commandkit/tree/main/packages/analytics/"
    click Cache "https://github.com/underctrl-io/commandkit/tree/main/packages/cache/"
    click I18n "https://github.com/underctrl-io/commandkit/tree/main/packages/i18n/"
    click Legacy "https://github.com/underctrl-io/commandkit/tree/main/packages/legacy/"
    click Queue "https://github.com/underctrl-io/commandkit/tree/main/packages/queue/"
    click RedisP "https://github.com/underctrl-io/commandkit/tree/main/packages/redis/"
    click Tasks "https://github.com/underctrl-io/commandkit/tree/main/packages/tasks/"
    click CLI "https://github.com/underctrl-io/commandkit/tree/main/packages/create-commandkit/"
    click DevUI "https://github.com/underctrl-io/commandkit/tree/main/packages/devtools-ui/"
    click DevAPI "https://github.com/underctrl-io/commandkit/tree/main/packages/devtools/"
    click TestBot "https://github.com/underctrl-io/commandkit/tree/main/apps/test-bot/"
    click Website "https://github.com/underctrl-io/commandkit/tree/main/apps/website/"

    %% Styles
    classDef orchestrator fill:#FFA07A,stroke:#333,stroke-width:1px
    classDef lib fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef app fill:#90EE90,stroke:#333,stroke-width:1px
    classDef tool fill:#FFD700,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
