architecture

1 files changed, 37 insertions, 0 deletions

diff --git a/docs/adr/0001-rcon-only-interaction.md b/docs/adr/0001-rcon-only-interaction.md
new file mode 100644
index 0000000..ec7bb41
--- /dev/null
+++ b/docs/adr/0001-rcon-only-interaction.md
@@ -0,0 +1,37 @@
+# ADR 0001: RCON-only Minecraft server interaction (no console, no file editing)
+
+## Status
+
+Accepted
+
+## Context
+
+The webUI needs to interact with the running Minecraft server for several operations: querying player count (dashboard), managing the whitelist, managing OPs, and managing bans. Two primary approaches exist:
+
+1. **File editing** — Read and write `whitelist.json`, `ops.json`, `banned-players.json` directly on disk. Requires a server restart or `/reload` to apply changes.
+2. **RCON** — Send commands over the RCON protocol. Changes apply immediately, no restart needed. Also enables querying server state (`/list`).
+3. **Docker stdin/stdout** — Attach to the container's console. Enables log streaming and command input. Requires persistent WebSocket/SSE connection.
+
+## Decision
+
+We will use **RCON exclusively** for all webUI-to-server interaction:
+
+- Player count queries via RCON `/list`
+- Whitelist, OP, and ban management via RCON commands (`/whitelist add`, `/op`, `/ban`, etc.)
+- No log streaming, no Docker console attachment
+- No direct editing of `whitelist.json`, `ops.json`, or other server files
+- RCON password is auto-generated per Instance and stored internally
+
+## Consequences
+
+### Positive
+- Changes apply immediately without server restart
+- No WebSocket or SSE infrastructure required
+- No log parsing or streaming complexity
+- User-facing player management is username-based (users don't need to know UUIDs or JSON structure)
+- Simpler codebase: request/response pattern over TCP, not persistent connections
+
+### Negative
+- No server logs visible in the webUI — debugging crashes requires Docker CLI access (but this is a system administration concern, out of scope for the webUI)
+- RCON must be enabled and reachable (`enable-rcon=true`, port exposed) for the webUI to function for live Instance operations
+- If the Minecraft process crashes inside the container, RCON becomes unreachable and the webUI can only report "crashed — check Docker logs" rather than showing the error