# ronin-shadow/discordbot architecture

> Architecture diagram of the GitHub repository ronin-shadow/discordbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ronin-shadow/discordbot
- Repository: https://github.com/ronin-shadow/discordbot

## Overview

1. **Overall shape**
   - This is a small **.NET Discord bot** project built with the **Discord.NET** framework.
   - It is organized as a single bot application with a clear split between the **startup/host**, **command handlers**, and **reusable services**.

2. **Entry point and bootstrapping**
   - `DiscordBot/Program.cs` is the application entry point.
   - Its role is to configure the Discord client, wire up command handling, and start the bot runtime using the Discord token/configuration expected by Discord.NET.

3. **Command layer**
   - `DiscordBot/Commands/` contains the bot’s user-facing command handlers.
   - The commands are separated into individual classes, which makes each feature easy to diagram as a discrete handler behind the Discord event stream.

4. **Concrete commands**
   - `HelloCommand.cs` represents a simple greeting/response command.
   - `BanCommand.cs` is an administrative moderation command that likely depends on Discord guild/member permissions and moderation APIs.
   - `DevTools.cs` suggests internal or owner-only utilities for debugging and operational control.

5. **Service layer**
   - `DiscordBot/Services/` holds reusable bot logic that is not tied to a single command.
   - This is the main boundary for nontrivial behavior and external integrations, keeping command classes thin.

6. **AI / external API integration**
   - `RonaldoAI.cs` is the clearest integration point for outbound HTTP-based functionality.
   - The README explicitly mentions examples using `HttpClient` and `System.Text.Json`, so this service likely encapsulates calling an external REST API and parsing JSON responses.

7. **Command orchestration / shared logic**
   - `RonaldoCommands.cs` appears to centralize command-related helpers, registration, or shared command behavior.
   - In an architecture diagram, this should sit between the Discord event loop and the individual command classes, reducing duplication.

8. **Runtime data flow**
   - Discord events arrive from the Discord gateway into the bot process.
   - `Program.cs` routes those events into the command layer.
   - Command handlers either:
     - respond directly to Discord,
     - call shared services in `Services/`,
     - or invoke external APIs through the HTTP/JSON integration layer.

9. **External dependencies and boundaries**
   - The key external dependency is **Discord’s API** via Discord.NET.
   - A second likely boundary is an **external REST service** used by `RonaldoAI`.
   - No database, cache, or message broker is visible in the repository.

10. **Project type and tooling**
   - `DiscordBot.csproj` indicates a standard C#/.NET project.
   - `.github/workflows/dotnet.yml` provides CI for building/testing the project on GitHub Actions.
   - The `.github/ISSUE_TEMPLATE` files are repository maintenance tooling, not runtime architecture.

11. **How to draw it**
   - Draw one main application box labeled **Discord Bot (.NET / Discord.NET)**.
   - Inside it, separate **Program/host**, **Commands**, and **Services**.
   - Show outbound arrows from **Ban/Hello/DevTools** into **Discord API**, and from **RonaldoAI** into an **external REST API**.

Main entry points: [`DiscordBot/Commands`](https://github.com/ronin-shadow/discordbot/tree/main/DiscordBot/Commands) (Commands), [`DiscordBot/Program.cs`](https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Program.cs) (Program), [`DiscordBot/Services`](https://github.com/ronin-shadow/discordbot/tree/main/DiscordBot/Services) (Services), [`DiscordBot/Services/RonaldoAI.cs`](https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Services/RonaldoAI.cs) (RonaldoAI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Bot app"]
  node_root["Discord Bot"]
  node_program["Program<br/>host<br/>[Program.cs]"]
  node_router["Command Core<br/>command orchestration<br/>[RonaldoCommands.cs]"]
  node_commands["Commands<br/>command layer"]
  node_hello["Hello<br/>command<br/>[HelloCommand.cs]"]
  node_ban["Ban<br/>moderation command<br/>[BanCommand.cs]"]
  node_devtools["DevTools<br/>admin command<br/>[DevTools.cs]"]
  node_services["Services<br/>service layer"]
  node_ai["RonaldoAI<br/>http service<br/>[RonaldoAI.cs]"]
  node_project["Project File<br/>.NET project<br/>[DiscordBot.csproj]"]
end

subgraph group_external["External"]
  node_discordnet{{"Discord.NET<br/>framework"}}
  node_discordapi{{"Discord API<br/>external api"}}
  node_restapi{{"REST API<br/>external service"}}
  node_ci["GitHub Actions<br/>ci workflow<br/>[dotnet.yml]"]
  node_readme["README<br/>docs<br/>[README.md]"]
end

node_program -->|"uses"| node_discordnet
node_program -->|"wires"| node_router
node_program -->|"loads"| node_commands
node_program -->|"configures"| node_services
node_commands -->|"contains"| node_hello
node_commands -->|"contains"| node_ban
node_commands -->|"contains"| node_devtools
node_router -->|"orchestrates"| node_commands
node_hello -->|"responds to"| node_discordapi
node_ban -->|"moderates"| node_discordapi
node_devtools -->|"controls"| node_discordapi
node_commands -->|"calls"| node_services
node_services -->|"includes"| node_ai
node_ai -->|"requests"| node_restapi
node_discordnet -->|"connects to"| node_discordapi
node_project -->|"builds"| node_program
node_ci -->|"builds"| node_project
node_readme -.->|"documents"| node_ai

click node_program "https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Program.cs"
click node_router "https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Services/RonaldoCommands.cs"
click node_commands "https://github.com/ronin-shadow/discordbot/tree/main/DiscordBot/Commands"
click node_hello "https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Commands/HelloCommand.cs"
click node_ban "https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Commands/BanCommand.cs"
click node_devtools "https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Commands/DevTools.cs"
click node_services "https://github.com/ronin-shadow/discordbot/tree/main/DiscordBot/Services"
click node_ai "https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Services/RonaldoAI.cs"
click node_ci "https://github.com/ronin-shadow/discordbot/blob/main/.github/workflows/dotnet.yml"
click node_project "https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot.csproj"
click node_readme "https://github.com/ronin-shadow/discordbot/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root,node_program,node_router,node_commands,node_hello,node_ban,node_devtools,node_services,node_ai,node_project toneBlue
class node_discordnet,node_discordapi,node_restapi,node_ci,node_readme toneAmber
```

## Components

### Bot app

Runtime components inside the Discord bot process.

- **Discord Bot**: app · Main .NET Discord bot application.
- [Program](https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Program.cs): host · Entry point and bootstrapper. · `DiscordBot/Program.cs`
- [Command Core](https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Services/RonaldoCommands.cs): command orchestration · Shared command registration and helper logic. · `DiscordBot/Services/RonaldoCommands.cs`
- [Commands](https://github.com/ronin-shadow/discordbot/tree/main/DiscordBot/Commands): command layer · User-facing command handlers. · `DiscordBot/Commands`
- [Hello](https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Commands/HelloCommand.cs): command · Greeting command handler. · `DiscordBot/Commands/HelloCommand.cs`
- [Ban](https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Commands/BanCommand.cs): moderation command · Guild moderation and ban workflow. · `DiscordBot/Commands/BanCommand.cs`
- [DevTools](https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Commands/DevTools.cs): admin command · Owner or developer utility commands. · `DiscordBot/Commands/DevTools.cs`
- [Services](https://github.com/ronin-shadow/discordbot/tree/main/DiscordBot/Services): service layer · Reusable bot logic shared across commands. · `DiscordBot/Services`
- [RonaldoAI](https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot/Services/RonaldoAI.cs): http service · Outbound HTTP and JSON integration service. · `DiscordBot/Services/RonaldoAI.cs`
- [Project File](https://github.com/ronin-shadow/discordbot/blob/main/DiscordBot.csproj): .NET project · C# project definition and dependencies. · `DiscordBot.csproj`

### External

Outside systems and integration boundaries.

- **Discord.NET**: framework · Bot framework used for Discord gateway and command handling.
- **Discord API**: external api · Discord gateway and REST boundary.
- **REST API**: external service · Outbound third-party API used by AI features.
- [GitHub Actions](https://github.com/ronin-shadow/discordbot/blob/main/.github/workflows/dotnet.yml): ci workflow · Build and test automation. · `.github/workflows/dotnet.yml`
- [README](https://github.com/ronin-shadow/discordbot/blob/main/README.md): docs · Repository usage and example guidance. · `README.md`

## Connections

- Program → Discord.NET: uses · Bootstraps the Discord.NET runtime.
- Program → Command Core: wires · Registers shared command behavior.
- Program → Commands: loads · Discovers and activates command handlers.
- Program → Services: configures · Registers reusable services for the bot.
- Commands → Hello: contains · Greeting handler.
- Commands → Ban: contains · Moderation handler.
- Commands → DevTools: contains · Developer utilities handler.
- Command Core → Commands: orchestrates · Coordinates shared command behavior across handlers.
- Hello → Discord API: responds to · Sends messages back to Discord.
- Ban → Discord API: moderates · Uses guild/member APIs to enforce moderation.
- DevTools → Discord API: controls · Issues bot responses and administrative actions.
- Commands → Services: calls · Delegates reusable logic to services.
- Services → RonaldoAI: includes · AI-related integration service.
- RonaldoAI → REST API: requests · Calls external HTTP endpoints and parses JSON.
- Discord.NET → Discord API: connects to · Framework boundary to Discord.
- Project File → Program: builds · Project entry and compilation unit.
- GitHub Actions → Project File: builds · CI validates the .NET project.
- README → RonaldoAI: documents · Describes HTTP and JSON integration examples.