# 0adiy/shellbot architecture

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

- Interactive diagram: https://gitdiagram.com/0adiy/shellbot
- Repository: https://github.com/0adiy/shellbot

## Overview

##### Project type and purpose
- This is a backend-only, event-driven microservice (a Discord bot) written in Go.
- Purpose: listen for commands on Discord, authenticate against a superuser list, execute them on a Linux shell, and relay results back to Discord.

##### File structure
- Top-level
- .github/workflows/go.yml – CI pipeline (build & test)
- taskfile.yaml – local build tasks
- go.mod / go.sum – dependency management
- app/
– config.go: reads config.yaml (token, prefix, superusers, emojis)
– discord.go: wraps Discord API client, event handlers
– main.go: orchestrates start-up, ties together config loader + Discord client
- There are no frontend or database components; instead there are two external systems: the Discord platform and the local OS shell.

##### README for additional insights
- Configuration drives the bot’s behavior (prefix, token, superusers).
- Build process can be invoked via Taskfile or direct go build.
- The runtime is a single long-running process on a Linux VPS.

##### Detailed breakdown
- Layer 1: End users & Discord Platform
- Layer 2: ShellBot binary, separated into sub-components
- Layer 3: Underlying OS shell
- Side-bar: CI/CD pipeline feeding into the ShellBot release and deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        DU["Discord User"]:::external
        DP["Discord Platform/API"]:::external
    end

    %% ShellBot Application
    subgraph "ShellBot Application (Go binary)" 
        MB["Main (app/main.go)"]:::app
        CL["Config Loader (app/config.go)"]:::app
        DC["Discord Client Module (app/discord.go)"]:::app
        CP["Command Processor"]:::app
        SE["Shell Executor"]:::app
    end

    %% OS Shell
    OS["Linux OS Shell (Bash)"]:::external

    %% CI/CD Pipeline
    subgraph "CI/CD & Build"
        GH["GitHub Actions CI (.github/workflows/go.yml)"]:::ci
        TF["Taskfile (taskfile.yaml)"]:::ci
        GD["Go Dependencies (go.mod & go.sum)"]:::ci
    end

    %% Runtime Flow
    DU -->|"sends command"| DP
    DP -->|"message event"| DC
    DC -->|"parse & forward"| CP
    CP -->|"load superusers"| CL
    CL -->|"config data"| CP
    CP -->|"exec command"| SE
    SE -->|"spawn & capture"| OS
    OS -->|"output"| SE
    SE -->|"result event"| DC
    DC -->|"API call"| DP
    DP -->|"message response"| DU

    %% CI/CD Flow
    GH -->|"build/test"| MB
    TF -->|"orchestrate build"| MB
    GD -->|"manage deps"| MB

    %% Click Events
    click MB "https://github.com/0adiy/shellbot/tree/master/app/"
    click CL "https://github.com/0adiy/shellbot/blob/master/app/config.go"
    click DC "https://github.com/0adiy/shellbot/blob/master/app/discord.go"
    click GH "https://github.com/0adiy/shellbot/blob/master/.github/workflows/go.yml"
    click TF "https://github.com/0adiy/shellbot/blob/master/taskfile.yaml"
    click GD "https://github.com/0adiy/shellbot/blob/master/go.mod"

    %% Styles
    classDef external fill:#D0E6F6,stroke:#036FAF,color:#036FAF
    classDef app fill:#D8F8D8,stroke:#2E8B57,color:#2E8B57
    classDef ci fill:#E8E8E8,stroke:#666666,color:#555555
```
