Shatteredvoid/memory.md

memory — Shattered Void

Durable memory for this project. Read at session start, update before session end. Date format: YYYY-MM-DD.

Decisions & rationale

• 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

• 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

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

• 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.