architecture

6 files changed, 90 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..c9af412
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+/target
+/minecraft
diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000..21055f5
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,35 @@
+# CONTEXT — Minecraft Server Manager
+
+## Glossary
+
+- **Server Instance** — The bundled combination of a World, a Version, a Type (mod loader), optionally a Modpack, and a set of server properties (difficulty, gamemode, max players, memory allocation, etc.). Multiple Server Instances can exist, but at most one is *active* (running) at any time. Users can create, modify, delete, and choose which Instance to activate. Editing an active Instance's properties causes a container restart to apply the change.
+
+- **Instance State** — The lifecycle of an Instance relative to the Docker container: **Inactive** (exists, not selected), **Starting** (container spinning up, Minecraft not yet ready), **Running** (container up, RCON responding), **Crashed** (container up, RCON unreachable — "check Docker logs"), **Stopping** (container shutting down), **Stopped** (container stopped, but still marked as the active Instance).
+
+- **World** — A Minecraft save (chunks, player data, etc.). Created either by generating a fresh world from a seed and level type, or by uploading a pre-existing save as a ZIP archive. Worlds can be exported (downloaded as ZIP) and imported independently of full Backups. World exports are transient — streamed to the browser and discarded server-side.
+
+- **World Generation** — The act of creating a new World during Instance creation. The user supplies an optional seed and a level type. Once generated, the seed is immutable for that World.
+
+- **Version** — A mainline Minecraft server version (e.g., 1.8.9, 1.12.2, 1.21). Discovered from the official Minecraft version manifest API.
+
+- **Type** — The server software flavor: `VANILLA`, `FORGE`, or `FABRIC`. Determines which mod loader is installed. Chosen during Instance creation and cannot be changed afterward (changing Type means creating a new Instance).
+
+- **Modpack** — An optional set of server-side mods packaged as a ZIP. Applied on top of a World + Version + Type to produce a modded Server Instance.
+
+- **Backup** — A full snapshot of an Instance's entire `/data` directory at a point in time (world, server properties, mods, whitelist — everything). Stored as a ZIP archive inside the Server Directory. Restoring a Backup creates a new Server Instance; it does not overwrite the original.
+
+- **Whitelist** — The list of Minecraft player usernames allowed to join the server. Managed through RCON commands. Since all Instances run in offline mode, the webUI sends usernames directly; the Minecraft server handles UUID assignment internally.
+
+- **OP** — A player granted operator (admin) privileges on the Minecraft server. Managed through RCON commands, analogous to the Whitelist.
+
+- **Ban** — A player banned from joining the server. Managed through RCON commands. Includes both username bans and IP bans.
+
+- **RCON Password** — A secret auto-generated string per Instance, stored in the Instance's `server.properties` and in the webUI database. Used internally for the webUI to authenticate RCON commands to the Minecraft server. Never exposed to the user.
+
+- **Account** — A set of credentials (username + hashed password) that authenticates a person to the webUI. All accounts have equal access to Server Instances and server operations.
+
+- **Superuser** — An Account with elevated privileges. Only superusers can access the account management page (create/delete accounts, change passwords). At least one superuser must always exist. The initial superuser must change their password on first login.
+
+- **Server Directory** — A configurable path on the host where all Minecraft data lives (world saves, configs, the `docker-compose.yml`, etc.). The Docker container mounts a subdirectory of this per active Instance. Backups are also stored here.
+
+- **Container State** — The running Docker container is an external resource independent of the webUI process. The webUI inspects the container's actual state on startup and reconciles accordingly. If the webUI restarts while the container is running, the container continues unaffected and the webUI reattaches to it.
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 0000000..c53b2a2
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "minecraft-ui"
+version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..493e356
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,6 @@
+[package]
+name = "minecraft-ui"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
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
diff --git a/src/main.rs b/src/main.rs
new file mode 100644
index 0000000..e7a11a9
--- /dev/null
+++ b/src/main.rs
@@ -0,0 +1,3 @@
+fn main() {
+    println!("Hello, world!");
+}