# maculinx/better-fabric-console architecture

> Architecture diagram of the GitHub repository maculinx/better-fabric-console, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maculinx/better-fabric-console
- Repository: https://github.com/maculinx/better-fabric-console
- Video tour (about a minute): https://gitdiagram.com/maculinx/better-fabric-console/video

## Overview

Better Fabric Console is a browser-based Minecraft server administration interface hosted by a Fabric mod. The main workflow is browser setup/authentication, then viewing status and live console data or sending configuration, plugin-toggle, and command actions through the WebSocket/HTTP bridge to the running server. It also supports regex log filtering, quick actions, optional Spark metrics, and persisted configuration and log history. The tree contains both a Java-hosted mod and a Node service backend; their runtime relationship is unclear, so they are shown as distinct paths. Some subsystem links follow README claims because their source was not sampled.

Main entry points: [`service/client/src/App.tsx`](https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/App.tsx) (Admin UI), [`src/main/java/com/mbucci/betterfabricconsole/web/WebServerHandler.java`](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/WebServerHandler.java) (HTTP and WS handler), [`src/main/java/com/mbucci/betterfabricconsole/plugin/PluginManager.java`](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/plugin/PluginManager.java) (Plugin manager), [`src/main/java/com/mbucci/betterfabricconsole/BetterFabricConsoleMod.java`](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/BetterFabricConsoleMod.java) (Mod initializer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mod["Fabric mod"]
  node_app["Mod initializer"]
  node_webserver["Web server<br/>[WebServer.java]"]
  node_handler["HTTP and WS handler"]
  node_auth["Authentication and sessions<br/>[AuthManager.java]"]
  node_jstorage["Mod storage<br/>[Storage.java]"]
  node_filters["Regex filters<br/>[FilterEngine.java]"]
end

subgraph group_web["Web interface"]
  node_browser["Admin UI<br/>[App.tsx]"]
  node_dashboard["Dashboard and panels<br/>[Dashboard.tsx]"]
  node_consoleui["Console view<br/>[Console.tsx]"]
  node_filterui["Filter controls<br/>[Filters.tsx]"]
  node_pluginui["Plugin controls<br/>[Plugins.tsx]"]
  node_actionsui["Quick actions<br/>[QuickActions.tsx]"]
end

subgraph group_node["Node service"]
  node_nodeapi["Node HTTP and WS API<br/>[server.ts]"]
  node_nodefilter["Node filter engine<br/>[filter.ts]"]
end

subgraph group_state["Configuration and logs"]
  node_nodestore["Node storage<br/>[storage.ts]"]
  node_jdata[("Mod config and logs")]
  node_ndata[("Service JSON files<br/>[config.json]")]
end

subgraph group_integrations["Server integrations"]
  node_console["Console bridge<br/>[ConsoleBridge.java]"]
  node_plugins["Plugin manager<br/>[PluginManager.java]"]
  node_spark["Spark metrics<br/>[SparkBridge.java]"]
  node_minecraft["Minecraft server"]
end

node_admin(("Administrator"))

node_admin -->|"uses"| node_browser
node_browser -->|"HTTP and WS"| node_handler
node_handler -->|"validates sessions"| node_auth
node_handler -->|"reads and writes"| node_jstorage
node_handler -->|"toggles plugins"| node_plugins
node_handler -->|"executes commands"| node_minecraft
node_app -->|"starts and stops"| node_webserver
node_app -->|"initializes"| node_plugins
node_app -->|"starts and stops"| node_console
node_plugins -->|"toggles capture"| node_console
node_plugins -.->|"starts and stops"| node_spark
node_plugins -->|"broadcasts capabilities"| node_webserver
node_console -->|"streams logs"| node_webserver
node_spark -.->|"reads metrics"| node_minecraft
node_jstorage -->|"persists"| node_jdata
node_browser -->|"renders"| node_dashboard
node_browser -->|"renders"| node_consoleui
node_browser -->|"renders"| node_filterui
node_browser -->|"renders"| node_pluginui
node_browser -->|"renders"| node_actionsui
node_admin -.->|"uses"| node_nodeapi
node_nodeapi -->|"reads and writes"| node_nodestore
node_nodeapi -->|"evaluates log rules"| node_nodefilter
node_nodestore -->|"persists"| node_ndata

click node_app "https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/BetterFabricConsoleMod.java"
click node_webserver "https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/WebServer.java"
click node_handler "https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/WebServerHandler.java"
click node_auth "https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/AuthManager.java"
click node_jstorage "https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/Storage.java"
click node_filters "https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/FilterEngine.java"
click node_console "https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/console/ConsoleBridge.java"
click node_plugins "https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/plugin/PluginManager.java"
click node_spark "https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/spark/SparkBridge.java"
click node_browser "https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/App.tsx"
click node_dashboard "https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/Dashboard.tsx"
click node_consoleui "https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/Console.tsx"
click node_filterui "https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/Filters.tsx"
click node_pluginui "https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/Plugins.tsx"
click node_actionsui "https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/QuickActions.tsx"
click node_nodeapi "https://github.com/maculinx/better-fabric-console/blob/main/service/src/server.ts"
click node_nodefilter "https://github.com/maculinx/better-fabric-console/blob/main/service/src/filter.ts"
click node_nodestore "https://github.com/maculinx/better-fabric-console/blob/main/service/src/storage.ts"
click node_ndata "https://github.com/maculinx/better-fabric-console/blob/main/service/data/config.json"

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_app,node_webserver,node_handler,node_auth,node_jstorage,node_filters toneBlue
class node_browser,node_dashboard,node_consoleui,node_filterui,node_pluginui,node_actionsui toneAmber
class node_nodeapi,node_nodefilter toneMint
class node_nodestore,node_jdata,node_ndata toneRose
class node_console,node_plugins,node_spark,node_minecraft,node_admin toneIndigo
```

## Components

### Fabric mod

- [Mod initializer](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/BetterFabricConsoleMod.java): `src/main/java/com/mbucci/betterfabricconsole/BetterFabricConsoleMod.java`
- [Web server](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/WebServer.java): `src/main/java/com/mbucci/betterfabricconsole/web/WebServer.java`
- [HTTP and WS handler](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/WebServerHandler.java): `src/main/java/com/mbucci/betterfabricconsole/web/WebServerHandler.java`
- [Authentication and sessions](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/AuthManager.java): `src/main/java/com/mbucci/betterfabricconsole/web/AuthManager.java`
- [Mod storage](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/Storage.java): `src/main/java/com/mbucci/betterfabricconsole/web/Storage.java`
- [Regex filters](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/web/FilterEngine.java): `src/main/java/com/mbucci/betterfabricconsole/web/FilterEngine.java`

### Web interface

- [Admin UI](https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/App.tsx): `service/client/src/App.tsx`
- [Dashboard and panels](https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/Dashboard.tsx): `service/client/src/components/Dashboard.tsx`
- [Console view](https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/Console.tsx): `service/client/src/components/Console.tsx`
- [Filter controls](https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/Filters.tsx): `service/client/src/components/Filters.tsx`
- [Plugin controls](https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/Plugins.tsx): `service/client/src/components/Plugins.tsx`
- [Quick actions](https://github.com/maculinx/better-fabric-console/blob/main/service/client/src/components/QuickActions.tsx): `service/client/src/components/QuickActions.tsx`

### Node service

- [Node HTTP and WS API](https://github.com/maculinx/better-fabric-console/blob/main/service/src/server.ts): `service/src/server.ts`
- [Node filter engine](https://github.com/maculinx/better-fabric-console/blob/main/service/src/filter.ts): `service/src/filter.ts`

### Configuration and logs

- [Node storage](https://github.com/maculinx/better-fabric-console/blob/main/service/src/storage.ts): `service/src/storage.ts`
- **Mod config and logs**
- [Service JSON files](https://github.com/maculinx/better-fabric-console/blob/main/service/data/config.json): `service/data/config.json`

### Server integrations

- [Console bridge](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/console/ConsoleBridge.java): `src/main/java/com/mbucci/betterfabricconsole/console/ConsoleBridge.java`
- [Plugin manager](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/plugin/PluginManager.java): `src/main/java/com/mbucci/betterfabricconsole/plugin/PluginManager.java`
- [Spark metrics](https://github.com/maculinx/better-fabric-console/blob/main/src/main/java/com/mbucci/betterfabricconsole/spark/SparkBridge.java): `src/main/java/com/mbucci/betterfabricconsole/spark/SparkBridge.java`
- **Minecraft server**

### Other components

- **Administrator**

## Connections

- Administrator → Admin UI: uses
- Admin UI → HTTP and WS handler: HTTP and WS
- HTTP and WS handler → Authentication and sessions: validates sessions
- HTTP and WS handler → Mod storage: reads and writes
- HTTP and WS handler → Plugin manager: toggles plugins
- HTTP and WS handler → Minecraft server: executes commands
- Mod initializer → Web server: starts and stops
- Mod initializer → Plugin manager: initializes
- Mod initializer → Console bridge: starts and stops
- Plugin manager → Console bridge: toggles capture
- Plugin manager → Spark metrics: starts and stops
- Plugin manager → Web server: broadcasts capabilities
- Console bridge → Web server: streams logs
- Spark metrics → Minecraft server: reads metrics
- Mod storage → Mod config and logs: persists
- Admin UI → Dashboard and panels: renders
- Admin UI → Console view: renders
- Admin UI → Filter controls: renders
- Admin UI → Plugin controls: renders
- Admin UI → Quick actions: renders
- Administrator → Node HTTP and WS API: uses
- Node HTTP and WS API → Node storage: reads and writes
- Node HTTP and WS API → Node filter engine: evaluates log rules
- Node storage → Service JSON files: persists