How danielvflores/mc-discord-ws works
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