Reconcile project context with Codex ownership model
This commit is contained in:
parent
7db130baf4
commit
8e3fa7b2f6
@ -2,9 +2,7 @@
|
||||
|
||||
## What It Is
|
||||
Game server hosting platform targeting modded, indie, and emerging games.
|
||||
Competitive advantages: LXC containers (20-30% perf over Docker), custom
|
||||
agent architecture, open-source stack, and a developer-to-player pipeline that
|
||||
turns mod developers into a distribution channel.
|
||||
Competitive advantages: LXC containers, custom agent architecture, open-source stack, and a developer-to-player pipeline that turns mod developers into a distribution channel.
|
||||
|
||||
System posture: stable, controlled expansion phase.
|
||||
|
||||
@ -50,20 +48,13 @@ System posture: stable, controlled expansion phase.
|
||||
|
||||
## Stack
|
||||
|
||||
**API (`zpack-api`):** Node.js ESM, Express 5, Prisma 6, MariaDB, Redis,
|
||||
BullMQ, JWT, Stripe, argon2, ssh2, WebSocket, http-proxy-middleware
|
||||
**API (`zpack-api`):** Node.js ESM, Express 5, Prisma 6, MariaDB, Redis, BullMQ, JWT, Stripe, argon2, ssh2, WebSocket, http-proxy-middleware
|
||||
|
||||
**Portal (`zpack-portal`):** Next.js 15, TypeScript, TailwindCSS,
|
||||
Axios, WebSocket console. Sci-fi HUD aesthetic (steel textures, neon
|
||||
accents, beveled panels).
|
||||
**Portal (`zpack-portal`):** Next.js 15, TypeScript, TailwindCSS, Axios, WebSocket console. Sci-fi HUD aesthetic (steel textures, neon accents, beveled panels).
|
||||
|
||||
**Agent (`zlh-agent`):** Go 1.21, stdlib HTTP, creack/pty, gorilla/websocket.
|
||||
Runs inside every game/dev container. Only process with direct filesystem
|
||||
access. Pulls runtimes + server jars from `zlh-artifacts`.
|
||||
**Agent (`zlh-agent`):** Go 1.21, stdlib HTTP, creack/pty, gorilla/websocket. Runs inside every game/dev container. Only process with direct filesystem access. Pulls runtimes + server jars from `zlh-artifacts`.
|
||||
|
||||
**Velocity plugin (`ZpackVelocityBridge`):** custom Velocity-side bridge that
|
||||
hydrates/registers backend servers for the proxy and exposes plugin-local
|
||||
register/unregister/status HTTP endpoints.
|
||||
**Velocity plugin (`ZpackVelocityBridge`):** custom Velocity-side bridge that hydrates/registers backend servers for the proxy and exposes plugin-local register/unregister/status HTTP endpoints.
|
||||
|
||||
---
|
||||
|
||||
@ -84,7 +75,12 @@ register/unregister/status HTTP endpoints.
|
||||
- Crash recovery: backoff 30s/60s/120s, resets if uptime ≥ 30s, `error` state after repeated failures
|
||||
- Crash observability: exit code, signal, uptime, log tail, classification
|
||||
- Real Minecraft readiness probing exists in `internal/minecraft/readiness.go`
|
||||
- Current open Minecraft issue is sequencing/use of readiness, not absence of readiness logic
|
||||
|
||||
### Backup boundary
|
||||
- Agent-owned game backups are local, app-aware rollback backups
|
||||
- Current implemented game backup scope is local Minecraft backup create/list/restore/delete plus pre-restore checkpoint hardening
|
||||
- PBS / platform backups are the durability and disaster-recovery layer
|
||||
- Do not treat offsite/PBS durability work as agent implementation work unless ownership changes
|
||||
|
||||
---
|
||||
|
||||
@ -147,8 +143,7 @@ Working hosted flow:
|
||||
- proxies live code-server HTTP + WebSocket traffic to the correct container
|
||||
|
||||
### Local developer access (future / separate track)
|
||||
Headscale/Tailscale for SSH, VS Code Remote, local tools.
|
||||
Constraints: no exit nodes, `magic_dns: false`.
|
||||
Headscale/Tailscale for SSH, VS Code Remote, local tools. Constraints: no exit nodes, `magic_dns: false`.
|
||||
|
||||
### Removed / No Longer Current
|
||||
- path-based `/api/dev/:id/ide` as the primary browser entry
|
||||
@ -166,7 +161,6 @@ Constraints: no exit nodes, `magic_dns: false`.
|
||||
- API exposes polled state back to frontend via `GET /api/servers/:id/status`
|
||||
- Portal uses the API-mediated hosted IDE flow
|
||||
- Portal uses the API websocket bridge for console access
|
||||
- Portal still has some migration debt through `src/lib/api/legacy.ts`
|
||||
- Portal no longer relies on stale DB-only state for console availability
|
||||
- Game publish flow remains untouched by dev routing work
|
||||
|
||||
@ -183,9 +177,8 @@ Constraints: no exit nodes, `magic_dns: false`.
|
||||
- `GET /zpack/status`
|
||||
|
||||
### Important current finding
|
||||
- The likely current bug is **not** generic “Velocity broken”
|
||||
- The likely issue is that the API/plugin path can expose/register a backend while the game server is `running` but not actually `ready`
|
||||
- The plugin is the critical part of that registration path
|
||||
- The likely current issue is sequencing: a backend must not be surfaced before semantic readiness succeeds
|
||||
- Current work is verification of any remaining registration path that could expose a backend before readiness probe success
|
||||
|
||||
### Important implementation note
|
||||
- Current plugin default endpoint behavior still references `zpack-api.internal.zlh` unless overridden
|
||||
@ -195,8 +188,7 @@ Constraints: no exit nodes, `magic_dns: false`.
|
||||
|
||||
## Game Support
|
||||
|
||||
**Production:** Minecraft (vanilla/Fabric/Paper/Forge/Neoforge), Rust,
|
||||
Terraria, Project Zomboid
|
||||
**Production:** Minecraft (vanilla/Fabric/Paper/Forge/Neoforge), Rust, Terraria, Project Zomboid
|
||||
|
||||
**In Pipeline:** Valheim, Palworld, Vintage Story, Core Keeper
|
||||
|
||||
@ -219,17 +211,19 @@ Revenue multiplier: 1 developer → ~10 players → $147.50/mo total.
|
||||
|
||||
## Open Threads (High Level)
|
||||
|
||||
1. Billing / Stripe completion
|
||||
2. Game server world backup / restore
|
||||
3. User onboarding flow
|
||||
4. Fabric readiness gating / Velocity exposure sequencing
|
||||
5. Password reset verification
|
||||
6. Usage limits / quota enforcement
|
||||
7. Email notifications
|
||||
8. Velocity resync / refresh behavior
|
||||
9. Upload testing, stress testing, OPNsense audit, provisioning validation
|
||||
Cross-repo / platform work remains in `OPEN_THREADS.md`.
|
||||
|
||||
See `OPEN_THREADS.md` for active detail and priority order.
|
||||
Repo-specific active work now lives under:
|
||||
- `Codex/API/*`
|
||||
- `Codex/Portal/*`
|
||||
- `Codex/Agent/*`
|
||||
|
||||
High-level active themes:
|
||||
1. Backup contract normalization and live validation
|
||||
2. Dev access / SSH / hosted IDE hardening
|
||||
3. Service discovery and provisioning validation
|
||||
4. Email notifications and launch polish
|
||||
5. Launch testing and infrastructure audit
|
||||
|
||||
---
|
||||
|
||||
@ -254,10 +248,13 @@ All at `git.zerolaghub.com/jester/<repo>`
|
||||
- `knowledge-base` is the architecture authority
|
||||
- `zlh-grind` is the execution continuity layer
|
||||
- `INFRASTRUCTURE.md` is the authoritative VM/IP inventory
|
||||
- repo-specific truth is maintained in `Codex/*`
|
||||
- root docs should stay focused on cross-repo/platform truth
|
||||
- Agent is the authority on filesystem enforcement — API must **not** duplicate filesystem logic
|
||||
- Portal does not enforce real policy — agent enforces
|
||||
- Portal never calls agents directly — all traffic goes through API
|
||||
- Upload transport uses raw `http.request` piping, never `fetch()`
|
||||
- Do not mark unimplemented work as complete
|
||||
- remove completed items from `OPEN_ITEMS.md` instead of letting them linger
|
||||
- Game publish flow must never be modified by dev routing changes
|
||||
- `proxyClient.js` must not be deleted — used by game edge publish path
|
||||
|
||||
Loading…
Reference in New Issue
Block a user