# lucasjoel1/openmc-panel architecture

> Architecture diagram of the GitHub repository lucasjoel1/openmc-panel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucasjoel1/openmc-panel
- Repository: https://github.com/lucasjoel1/openmc-panel

## Overview

##### Project Type and Purpose
- This is a full-stack server-management application.
– Backend in Go (HTTP server, WebSocket, Discord bot).
– Frontend in React+TypeScript (Vite, Tailwind CSS, Radix UI).
– Integrates with a local Minecraft server process.
– Enables control via web UI and Discord commands.

##### File Structure
- Top-level “src” folder is the Go backend.
– `src/main.go` boots: starts HTTP server + Discord bot.
– `src/globals/` holds state managers (player, serverProperties, buffer, state).
– `src/listeners/bot/` implements Discord event handling.
– `src/listeners/share/` deals with WebSocket connections for real-time data and logs.
– `src/server/` contains code to start/stop/restart the Minecraft process.
– `src/web/` defines HTTP API handlers (`/api/...`) and static‐file serving.
- “frontend/” folder is the web client: React components, hooks, UI primitives under `src/components/*`, Vite config, static `public/`, built assets snapshot under `src/web/frontend/assets/`.
- Root config: `.env.example`, `server.json`, Go modules.

##### README Insights
- Main features: start/stop/restart server, real-time monitoring via WebSocket, console access, server properties editor, memory controls, Discord chat bridge, notifications.
- Tech stack callouts: Discord API via discordgo, gopsutil, WebSocket for real-time, React + TanStack Query.
- API endpoints: REST (`/api/startServer`, `/api/stopServer`, etc.) and WebSocket at `/api/ws/serverInfo`.
- Lifecycle: `go run src/main.go` → HTTP+WebSocket+Discord gateway; frontend built & served from Go binary.

##### Main Components and Their Relationships
a. External Actors:
- Web user (browser)
- Discord user (Discord client)
b. Presentation Layer:
- React Frontend (served as static files)
- Uses REST (HTTP) for administrative actions
- Opens WebSocket for real-time server status & logs
c. Application Layer (Go backend):
- HTTP Server (net/http)
- WebSocket Hub (listeners/share/connectionHandler.go)
- Discord Bot (listeners/bot/messageListener.go)
- API Handlers (`src/web/api/*.go`)
- Global State Managers (in-memory)
d. Domain / Service Layer:
- Server Management Service (`src/server/startServer.go` + stop/restart routines)
- Player Manager, Server Properties Manager
- System Monitor (gopsutil) for CPU/RAM metrics
e. Persistence / Infrastructure:
- Minecraft Server Process (JVM)
- Local filesystem (`server/` directory with JAR, worlds, properties)
f. External Service:
- Discord Gateway API

##### Architectural Patterns & Design Principles
- Layered architecture: Presentation → Application → Domain → Infrastructure
- Event-driven for Discord and WebSocket listeners
- Single process monolith grouping all concerns but logically separated in packages
- Real-time pub/sub pattern for logs & status updates via WebSocket hub

- Clear, human-readable labels for each component.
- Callouts for critical technologies: Go 1.24.1, React+Vite, WebSocket, discordgo, gopsutil, Tailwind CSS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    subgraph "Actors"
        WebUser["Web User (Browser)"]:::external
        DiscordUser["Discord User"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend (React + Vite + Tailwind)" 
        direction TB
        MainTS["frontend/src/main.tsx"]:::frontend
        AppTS["frontend/src/App.tsx"]:::frontend
        subgraph "UI Components & Pages"
            direction TB
            UIComps["frontend/src/components/*"]:::frontend
        end
        Hooks["frontend/src/hooks/use-mobile.ts & frontend/src/lib/utils.ts"]:::frontend
    end

    %% Go Backend Layer
    subgraph "Go Backend (Go 1.24.1 Monolith)"
        direction TB
        MainGo["Bootstrap: src/main.go"]:::service

        subgraph "Global State Managers (in-memory)"
            direction TB
            Buffer["bufferHandler.go"]:::service
            Player["playerManager.go"]:::service
            Props["serverPropertiesManager.go"]:::service
            StateM["stateManager.go"]:::service
        end

        subgraph "Listeners"
            direction TB
            Bot["Discord Bot Listeners"]:::service
            Share["WebSocket Hub & RT Listeners"]:::service
        end

        subgraph "Server Management Service"
            direction TB
            StartSrv["startServer.go"]:::service
        end

        subgraph "HTTP API Handlers (/api)"
            direction TB
            APIStart["startServer.go"]:::service
            APIStop["stopServer.go"]:::service
            APIRestart["restartServer.go"]:::service
            APIInfo["serverInfo.go"]:::service
            APILogs["serverLogs.go"]:::service
        end

        subgraph "Static File Serving & API Setup"
            direction TB
            ServerGo["server.go"]:::service
            Assets["frontend/assets"]:::service
            IndexHTML["index.html"]:::service
        end
    end

    %% Minecraft Server and Filesystem
    subgraph "Minecraft Server & Filesystem"
        direction TB
        Proc["Minecraft Process (JVM)"]:::storage
        FS["server/ directory (worlds, properties, server.json)"]:::storage
    end

    %% External Service
    DiscordAPI["Discord Gateway API"]:::external

    %% Connections
    WebUser -->|"REST (HTTP)"| APIStart
    WebUser -->|"REST (HTTP)"| APIStop
    WebUser -->|"REST (HTTP)"| APIRestart
    WebUser -->|"REST (HTTP)"| APIInfo
    WebUser -->|"REST (HTTP)"| APILogs
    WebUser -->|"WebSocket (WS)"| Share

    DiscordUser -->|"Discord Gateway"| DiscordAPI
    DiscordAPI -->|"Gateway Events"| Bot

    Bot -->|"Triggers Commands"| StartSrv
    Bot -->|"Updates State"| StateM

    APIStart -->|"calls"| StartSrv
    APIStop -->|"calls"| StartSrv
    APIRestart -->|"calls"| StartSrv

    StartSrv -->|"Shell Exec"| Proc
    StartSrv -->|"Reads/Writes"| FS

    Proc -->|"Logs & Metrics"| Share
    Share -->|"WS Push"| WebUser

    ServerGo -->|"Serves Static"| WebUser
    ServerGo -->|"Routes API"| APIStart

    MainGo --> Buffer
    MainGo --> Player
    MainGo --> Props
    MainGo --> StateM
    MainGo --> Bot
    MainGo --> Share
    MainGo --> APIStart
    MainGo --> ServerGo

    %% Click Events
    click MainGo "https://github.com/lucasjoel1/openmc-panel/blob/main/src/main.go"
    click Buffer "https://github.com/lucasjoel1/openmc-panel/blob/main/src/globals/bufferHandler.go"
    click Player "https://github.com/lucasjoel1/openmc-panel/blob/main/src/globals/playerManager.go"
    click Props "https://github.com/lucasjoel1/openmc-panel/blob/main/src/globals/serverPropertiesManager.go"
    click StateM "https://github.com/lucasjoel1/openmc-panel/blob/main/src/globals/stateManager.go"
    click Bot "https://github.com/lucasjoel1/openmc-panel/tree/main/src/listeners/bot/"
    click Share "https://github.com/lucasjoel1/openmc-panel/tree/main/src/listeners/share/"
    click StartSrv "https://github.com/lucasjoel1/openmc-panel/blob/main/src/server/startServer.go"
    click APIStart "https://github.com/lucasjoel1/openmc-panel/blob/main/src/web/api/startServer.go"
    click APIStop "https://github.com/lucasjoel1/openmc-panel/blob/main/src/web/api/stopServer.go"
    click APIRestart "https://github.com/lucasjoel1/openmc-panel/blob/main/src/web/api/restartServer.go"
    click APIInfo "https://github.com/lucasjoel1/openmc-panel/blob/main/src/web/api/serverInfo.go"
    click APILogs "https://github.com/lucasjoel1/openmc-panel/blob/main/src/web/api/serverLogs.go"
    click ServerGo "https://github.com/lucasjoel1/openmc-panel/blob/main/src/web/server.go"
    click Assets "https://github.com/lucasjoel1/openmc-panel/tree/main/src/web/frontend/assets/"
    click IndexHTML "https://github.com/lucasjoel1/openmc-panel/blob/main/src/web/index.html"
    click MainTS "https://github.com/lucasjoel1/openmc-panel/blob/main/frontend/src/main.tsx"
    click AppTS "https://github.com/lucasjoel1/openmc-panel/blob/main/frontend/src/App.tsx"
    click UIComps "https://github.com/lucasjoel1/openmc-panel/tree/main/frontend/src/components/"
    click Hooks "https://github.com/lucasjoel1/openmc-panel/blob/main/frontend/src/hooks/use-mobile.ts"

    %% Styles
    classDef frontend fill:#a8e6cf,stroke:#05668d,stroke-width:1px
    classDef service fill:#89cff0,stroke:#034f84,stroke-width:1px
    classDef storage fill:#ffd97d,stroke:#d97904,stroke-width:1px
    classDef external fill:#cccccc,stroke:#666666,stroke-width:1px

    %% Legend
    subgraph "Legend"
        direction TB
        L1["■ Frontend (React+TS)"]:::frontend
        L2["■ Backend Services (Go)"]:::service
        L3["■ Storage / Filesystem"]:::storage
        L4["■ External Actors / APIs"]:::external
    end
```
