initial

README.md

@@ -0,0 +1,30 @@
+# Hearthmod Modernization Notes
+
+This workspace contains the Hearthmod stack (game server, lobby server, web UI,
+and supporting components). The current goal is to stabilize the development
+environment and improve maintainability without changing client protocol
+compatibility.
+
+## Component-by-Component Replacement Plan
+
+Replacing services incrementally is the safest path. It preserves existing
+behavior while enabling modernization behind compatibility boundaries.
+
+1. **Baseline and observability**: document startup order, ports, and data flows;
+   add basic health checks and structured logs.
+2. **Gateway layer**: introduce a thin gateway that speaks the legacy protocol
+   and routes to existing lobby/game services.
+3. **Lobby replacement**: implement lobby endpoints behind the gateway, canary
+   traffic to validate parity.
+4. **Game server replacement**: implement the game loop and compare deterministic
+   state snapshots with the legacy server before shifting traffic.
+5. **Data layer swap**: add a DAL in new services, mirror writes to a new store,
+   then flip reads after validation.
+6. **Decommission legacy**: remove unused services and dependencies once traffic
+   is fully migrated.
+
+## Maintainability Priorities
+
+- Keep configuration centralized (env or config files).
+- Prefer a single entrypoint script or container orchestration for local dev.
+- Add small smoke tests to validate service health and database connectivity.