49 lines
5 KiB
Markdown
49 lines
5 KiB
Markdown
# memory — Shattered Void
|
||
|
||
Durable memory for this project. Read at session start, update before session end. Date format: `YYYY-MM-DD`.
|
||
|
||
## Decisions & rationale
|
||
|
||
<!-- Architectural choices, library picks, tradeoffs. Why, not just what. -->
|
||
|
||
- **Genre / inspiration:** text-based post-collapse sci-fi MMO strategy game, explicitly modelled on OGame (stated verbatim in `idea.txt`). Browser-based, asynchronous, persistent galaxy.
|
||
- **Backend: Node.js + Express**, entry `src/server.js`, thin `src/app.js`. Layered structure — `controllers/` → `services/` → `models/`, with `validators/` and `middleware/` alongside.
|
||
- **Database: PostgreSQL primary + Redis** for caching/sessions. Schema is checked in as `database-schema.sql` (~29 KB); migrations run through **Knex** (`knexfile.js`, `npm run db:migrate`).
|
||
- **Real-time: WebSockets** (`src/config/websocket.js`) for live game-state pushes rather than polling.
|
||
- **Auth: JWT with separate player and admin secrets** (distinct `JWT_PLAYER_SECRET` / `JWT_ADMIN_SECRET` / `JWT_REFRESH_SECRET`) — admins and players are deliberately separate trust domains.
|
||
- **Frontend: React 18 + TypeScript + Vite + Tailwind**, in `frontend/`. State via Zustand-style stores (`store/authStore.ts`, `store/gameStore.ts`); API client in `lib/api.ts`; WebSocket hook in `hooks/useWebSocket.ts`. Only two pages exist so far: `Dashboard.tsx`, `Colonies.tsx`.
|
||
- **Plugin architecture for game mechanics** (`src/plugins/`) — combat was built as a plugin, the intent being that mechanics are extensible without touching core.
|
||
- **Game loop: tick-based** (`src/services/game-tick.service.js`) — the galaxy simulates continuously rather than on request.
|
||
- **Orchestrated startup:** `start-game.js` / `start.sh` / `stop-game.js` plus `scripts/startup-checks.js`, `database-validator.js`, `health-monitor.js`. Starting the game runs preflight checks rather than just booting the server.
|
||
|
||
## Open questions / TODOs
|
||
|
||
<!-- Unresolved items. Check off or delete when resolved. -->
|
||
|
||
- [ ] **Does it still run?** Never verified on this machine — the repo had no local checkout until 2026-07-16. Needs PostgreSQL + Redis before `npm run start:game` will do anything.
|
||
- [ ] **Repo is public** on Forgejo, against the `~/claude/CLAUDE.md` default of private. Decide whether to flip it to private.
|
||
- [ ] **`.env.example` ships `DB_PASSWORD=s5d7dfs5e2q23`** — reads like a real local Postgres password rather than a placeholder, and it is committed to a public repo. Confirm it was never reused anywhere real; consider replacing with an obvious placeholder.
|
||
- [ ] Two `.backup` files are committed (`src/middleware/cors.middleware.js.backup`, `src/middleware/auth.js.backup`) — dead weight, probably delete.
|
||
- [ ] No `tests/` directory on disk despite `README.md` documenting a full `tests/unit|integration|e2e` layout and `package.json` wiring Jest. Test suite was specced but never written.
|
||
- [ ] `docker:build` / `docker:run` scripts reference a `Dockerfile` and `docker-compose.yml` that aren't in the repo.
|
||
- [ ] Decide the actual goal: revive and build on it, or keep it as an archived reference.
|
||
|
||
## Session log
|
||
|
||
<!-- Append-only. Newest at the bottom. One entry per session. -->
|
||
|
||
### 2026-07-16
|
||
- Tracked the project down after it went missing. It was never on GitHub and had no local working copy anywhere on this box — it existed only as a repo on the Forgejo instance (`git.rdx4.com/megaproxy/Shatteredvoid`), which is why name-based filesystem sweeps found nothing. The only local trace was a stray copy of the pitch doc at `/mnt/c/Users/Doug/shattered_void_game_pitch.md`.
|
||
- Cloned into `~/claude/projects/shatteredvoid` (folder is lowercase house style; **the Forgejo repo is `Shatteredvoid`** — remote URL keeps the capital S).
|
||
- Added this `memory.md` and prepended the standard working-agreement section to the repo's pre-existing `CLAUDE.md` (which is a game-specific dev guide, kept intact below the new section).
|
||
- Scanned all 4 commits for secrets: only `.env.example` is tracked, no real `.env`, no API keys/tokens. The one thing worth a look is the `DB_PASSWORD` noted above.
|
||
- Did not run the game — no Postgres/Redis stood up, nothing verified.
|
||
|
||
## External references
|
||
|
||
<!-- Links, dashboards, tickets, docs. Paths to credential stores, never credentials themselves. -->
|
||
|
||
- **Forgejo repo:** <https://git.rdx4.com/megaproxy/Shatteredvoid> — clone `https://git.rdx4.com/megaproxy/Shatteredvoid.git` (note capital `S`; local folder is `shatteredvoid`). Currently **public**. Original history: 4 commits, 2025-08-02 → 2025-08-03.
|
||
- **In-repo docs:** `idea.txt` (the OGame framing), `shattered_void_game_pitch.md` (21 KB full pitch — economy, tiers, fleet ladder, sector coords, 18–24 month plan), `README.md`, `STARTUP_GUIDE.md` (14 KB), `TESTING_GUIDE.md`, `CLAUDE.md`.
|
||
- **Duplicate pitch doc** on the Windows host: `/mnt/c/Users/Doug/shattered_void_game_pitch.md` — same content, loose copy; the repo version is authoritative.
|
||
- **Forgejo token:** `~/.git-credentials` (plaintext, HTTPS auth). Credentials live there, not here.
|