From 669b8d745553351cf492349f79b8e35dcc3a1c17 Mon Sep 17 00:00:00 2001 From: mohammad Date: Wed, 11 Mar 2026 18:35:02 +0300 Subject: [PATCH] initial --- AGENTS.md | 53 ++++++++++++++++++++++++++--------------------------- README.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 27 deletions(-) create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md index c6321df..4f0de31 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,51 +2,50 @@ ## Project Structure & Module Organization -- `hearthmod/` contains orchestration scripts (`host_ctl_ubuntu.sh`, `docker_ctl.sh`) and legacy Docker setup. +- `hearthmod/` contains legacy orchestration scripts and original docs. - Core C services live in `hm_gameserver/`, `hm_lobbyserver/`, and shared code in `hm_base/`. - Web UI is in `hm_web/` (Python `web.py`, templates, and static assets). -- Card rendering and assets are in `hm_sunwell/` (Node-based renderer). +- Card rendering lives in `hm_sunwell/` (Node-based renderer). - TLS proxy and web server components live in `hm_stud/` and `hm_nginx/`. -- Database snapshot and seed data are in `hm_database/`. - -Long-term maintainability should focus on repeatable local environments and -centralized configuration. See `README-dev.md` for the current plan. +- Database snapshot/seed data is in `hm_database/`. ## Build, Test, and Development Commands -- `make -C hm_base target=game` builds the shared base library for the gameserver. +- `make -C hm_base target=game` builds the shared base library. - `make -C hm_gameserver` builds the gameserver binary. - `make -C hm_lobbyserver` builds the lobbyserver binary. -- `bash hearthmod/host_ctl_ubuntu.sh start ` starts the stack (legacy flow). -- `bash hearthmod/host_ctl_ubuntu.sh build` runs the full build, including client/web assets. +- `bash hearthmod/host_ctl_ubuntu.sh start ` starts the legacy stack. -Current priority is a stable dev environment. Prefer adding a unified `dev` script -or `docker-compose` workflow over expanding the legacy scripts. +When adding new workflows, prefer a single entrypoint script (e.g., `./dev`) or +container orchestration; keep legacy scripts untouched unless required. ## Coding Style & Naming Conventions -- C code uses 4-space indentation and snake_case for functions and variables. +- C code uses 4-space indentation and snake_case identifiers. - Python uses 4-space indentation; prefer explicit names over abbreviations. -- Avoid one-letter variable names unless used as simple loop counters. -- Keep config constants centralized; avoid embedding ports/paths inline. -- New config values should be documented in `README-dev.md` and `.env.example`. +- Avoid one-letter variable names except for simple loop counters. +- Centralize ports and credentials in config or env variables. ## Testing Guidelines -- There is no dedicated test suite currently. -- If you introduce tests, keep them close to the component (e.g., `hm_web/tests/`). -- Prefer simple smoke tests (service port checks, Couchbase connectivity) that - validate the dev environment. +- There is no dedicated test suite today. +- If you add tests, keep them close to the component (e.g., `hm_web/tests/`). +- Favor smoke tests that validate service ports and Couchbase connectivity. ## Commit & Pull Request Guidelines -- Git history is not available in this workspace, so no commit convention is enforced. -- For new work, use concise imperative messages (e.g., “Add dev config loader”). -- Pull requests should include a short summary, testing notes, and any config changes. -- If the change impacts the dev environment, update `README-dev.md` in the same PR. +- Git history is limited here; use concise imperative commit messages. +- Pull requests should include a short summary and testing notes. +- If you touch configuration or workflows, update the README. -## Security & Configuration Tips +## Modernization Roadmap (Maintainability) -- Couchbase credentials and ports are hard-coded in places; prefer `.env` or config files. -- `hm_stud` is abandonware; avoid deploying it to production without replacement. -- When adding config, document defaults and provide an `.env.example`. +The long-term goal is to replace components one at a time while keeping protocol +compatibility. Suggested phases: + +- Baseline: document current behavior and add logs/health checks. +- Gateway: add a thin protocol gateway to route traffic to legacy services. +- Lobby: reimplement lobby features behind the gateway with canary routing. +- Game: reimplement game loop and compare state snapshots for parity. +- Data: introduce a new data layer, mirror writes, then flip reads. +- Decommission: remove unused legacy components once traffic is migrated. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c4de723 --- /dev/null +++ b/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.