# danielvflores/mc-discord-ws architecture

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

- Interactive diagram: https://gitdiagram.com/danielvflores/mc-discord-ws
- Repository: https://github.com/danielvflores/mc-discord-ws

## Overview

##### Project Type and Purpose
- This is a full-stack, event-driven integration system (“Discord-Minecraft Chat Bridge”) composed of three main services:
- A TypeScript/Node.js “core” API server (Express + WS + Cors)
- A TypeScript/Node.js Discord bot (DiscordX)
- A Java Spigot plugin (Minecraft server side)
- Purpose: bidirectional real-time chat and event synchronization between Discord and a Minecraft server, plus basic auth and dynamic control of the WebSocket bridge.

##### File Structure
- Top-level directories:
- core/ → Express + WebSocket server (core/src/index.ts)
- discord/ → DiscordX bot, WebSocket client, command handlers, local JSON storage (servers.json)
- java/discordmcapi/ → Spigot plugin code, Maven build, listeners, commands, resource YAMLs
- Notice patterns:
- In discord/src/commands and java/src/main/java/.../commands → command handlers (/registerapi, /loginapi, /toggleplugin)
- In src/.../listeners → event listeners for chat, join/quit, WebSocket messages
- Configuration files: api-rest.yml, plugin.yml, servers.json for state persistence
- Build scripts: package.json (core, discord), pom.xml (java)

##### Key Architectural Insights from README
- Core hosts both REST (for register/login/toggle) and WebSocket endpoint for real-time events.
- Discord bot and Java plugin both open WS clients to the core server.
- Commands trigger REST calls or WS messages; plugin persists “enabled” state in YML, bot persists server info in JSON.
- Flow is purely local now but designed for cloud deployment and external DB in the future.

##### Main Components
- External Clients
- Discord user on Discord server
- Minecraft player on Minecraft server
- Service Components
- Minecraft Plugin (Java/Spigot)
– Listeners: ChatListener, JoinQuitListener, WSListener
– Commands: RegisterApiCommand, TogglePluginCommand
– WS client & REST client
- Core API Server (TypeScript/Express)
– REST API endpoints: /register, /login, /toggle
– WS server (ws library)
– JSON storage (servers.json)
- Discord Bot (TypeScript/DiscordX)
– Command handlers (loginApi.ts)
– WS client & event emitter
– Message listeners for sync
- Data Stores
- Local JSON file (servers.json)
- YML files (api-rest.yml, plugin.yml)

##### Relationships and Data Flows
1. Minecraft Plugin → WebSocket → Core Server → WebSocket → Discord Bot → Discord Server → Discord User
2. Discord User → Discord Bot → WebSocket → Core Server → WebSocket → Minecraft Plugin → Minecraft Server → Player
3. Minecraft Plugin ↔ REST API (core) for register/login/toggle
4. Discord Bot ↔ REST API (core) for login

##### Architectural Patterns & Design Principles
- Event-driven, pub/sub style using WebSocket
- Layered separation: API layer (Express), Presentation/Clients (bot, plugin), Data layer (JSON/YML)
- Command pattern for bot and plugin commands
- Single source of truth for authentication and control flows in core server

##### Essential Elements to Capture
- Component boundaries and interactions
- Protocols and data formats (JSON over WS/HTTP)
- Persistence layers and config files
- Authentication flow (UUID generation, login, toggle)
- Real-time event loop between three parties

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        DU["Discord User"]:::external
        MP["Minecraft Player"]:::external
    end

    %% Discord Bot Service
    subgraph "Discord Bot (TypeScript/DiscordX)" 
        direction TB
        DBot["Discord Bot"]:::service
        BotInit["bot.ts"]:::component
        APIListen["apiListener.ts"]:::component
        CmdLogin["loginApi.ts"]:::component
        CmdLoader["loadCommands.ts"]:::component
        DBStorage["servers.json"]:::storage
    end

    %% Core API Server
    subgraph "Core API Server\n(Node.js/Express/WS)" 
        direction TB
        CoreSrv["Core Server"]:::service
        RESTAPI["REST Endpoints\n/register, /login, /toggle"]:::component
        WSsrv["WebSocket Server"]:::component
        CoreStorage["servers.json"]:::storage
    end

    %% Minecraft Plugin Service
    subgraph "Minecraft Plugin (Java/Spigot)"
        direction TB
        PluginMain["Main.java"]:::component
        CmdReg["RegisterApiCommand.java"]:::component
        CmdToggle["TogglePluginCommand.java"]:::component
        ListenerChat["ChatListener.java"]:::component
        ListenerJoin["JoinQuitListener.java"]:::component
        ListenerWS["WSListener.java"]:::component
        YMLRest["api-rest.yml"]:::storage
        YMLPlugin["plugin.yml"]:::storage
    end

    %% Interactions
    DU -->|"Discord Command"| DBot
    DBot -->|"HTTP POST loginApi"| RESTAPI
    DBot -->|"ws:// events"| WSsrv
    WSsrv -->|"chatMessage"| DBot
    WSsrv -->|"joinEvent"| DBot
    MP -->|"in-game chat/join"| ListenerChat
    ListenerChat -->|"ws:// chatMessage"| WSsrv
    ListenerJoin -->|"ws:// joinEvent"| WSsrv
    ListenerWS -->|"receives ws events"| PluginMain
    PluginMain -->|"HTTP POST register/toggle"| RESTAPI
    RESTAPI -->|"response"| PluginMain
    WSsrv -->|"ws:// event"| ListenerWS
    RESTAPI -->|"response"| DBot

    %% Click Events for Core
    click CoreSrv "https://github.com/danielvflores/mc-discord-ws/tree/main/core/"
    click CoreSrv "https://github.com/danielvflores/mc-discord-ws/blob/main/core/src/index.ts"
    click CoreSrv "https://github.com/danielvflores/mc-discord-ws/blob/main/core/package.json"
    click CoreSrv "https://github.com/danielvflores/mc-discord-ws/blob/main/core/package-lock.json"

    %% Click Events for Discord Bot
    click DBot "https://github.com/danielvflores/mc-discord-ws/tree/main/discord/"
    click DBot "https://github.com/danielvflores/mc-discord-ws/blob/main/discord/src/index.ts"
    click BotInit "https://github.com/danielvflores/mc-discord-ws/blob/main/discord/src/bot.ts"
    click APIListen "https://github.com/danielvflores/mc-discord-ws/blob/main/discord/src/apiListener.ts"
    click CmdLogin "https://github.com/danielvflores/mc-discord-ws/blob/main/discord/src/commands/loginApi.ts"
    click CmdLoader "https://github.com/danielvflores/mc-discord-ws/blob/main/discord/src/utils/loadCommands.ts"
    click DBStorage "https://github.com/danielvflores/mc-discord-ws/blob/main/discord/src/database/servers.json"
    click DBot "https://github.com/danielvflores/mc-discord-ws/blob/main/discord/package.json"
    click DBot "https://github.com/danielvflores/mc-discord-ws/blob/main/discord/package-lock.json"
    click DBot "https://github.com/danielvflores/mc-discord-ws/blob/main/discord/tsconfig.json"

    %% Click Events for Minecraft Plugin
    click PluginMain "https://github.com/danielvflores/mc-discord-ws/blob/main/java/discordmcapi/src/main/java/com/discordconnection/plugin/Main.java"
    click CmdReg "https://github.com/danielvflores/mc-discord-ws/blob/main/java/discordmcapi/src/main/java/com/discordconnection/plugin/commands/RegisterApiCommand.java"
    click CmdToggle "https://github.com/danielvflores/mc-discord-ws/blob/main/java/discordmcapi/src/main/java/com/discordconnection/plugin/commands/TogglePluginCommand.java"
    click ListenerChat "https://github.com/danielvflores/mc-discord-ws/blob/main/java/discordmcapi/src/main/java/com/discordconnection/plugin/listeners/ChatListener.java"
    click ListenerJoin "https://github.com/danielvflores/mc-discord-ws/blob/main/java/discordmcapi/src/main/java/com/discordconnection/plugin/listeners/JoinQuitListener.java"
    click ListenerWS "https://github.com/danielvflores/mc-discord-ws/blob/main/java/discordmcapi/src/main/java/com/discordconnection/plugin/listeners/WSListener.java"
    click YMLRest "https://github.com/danielvflores/mc-discord-ws/blob/main/java/discordmcapi/src/main/resources/api-rest.yml"
    click YMLPlugin "https://github.com/danielvflores/mc-discord-ws/blob/main/java/discordmcapi/src/main/resources/plugin.yml"
    click javaRoot "https://github.com/danielvflores/mc-discord-ws/tree/main/java/discordmcapi/"
    click pom "https://github.com/danielvflores/mc-discord-ws/blob/main/java/discordmcapi/pom.xml"

    %% Styles
    classDef service fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef component fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef storage fill:#F9E79F,stroke:#B7950B,color:#784212;
    classDef external fill:#A9DFBF,stroke:#186A3B,color:#0B5345;
```
