jester/zlh-grind
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
d9e070afd4
zlh-grind/PROJECT_CONTEXT.md

4.8 KiB
Raw Blame History

ZeroLagHub – Project Context

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, developer-to-player pipeline that turns mod developers into a distribution channel.

System posture: stable, controlled expansion phase.

Infrastructure (Proxmox)

Active VMs

VM Name Role
104 zlh-monitor Prometheus/Grafana monitoring
105 zlh-router Core services router (node 1)
300 zlh-velocity Minecraft Velocity proxy
1000 zlh-router Game + dev server router (node 2)
1001 zlh-dns Technitium DNS
1002 zlh-proxy Traefik (dev + other games)
1003 zlh-artifacts Runtime binaries + Minecraft server jars (agent install source)
1004 zlh-zpack-proxy Traefik (zpack stack)
1005 zpack-api Node.js API
1006 zlh-zpack-router zpack stack router
1100 zpack-portal Next.js frontend
2001 zlh-back PBS backup + Backblaze B2

Legacy / Reference Only (not active production)

VM Name Notes
100 zlh-panel Old Pterodactyl panel — kept for reference
101 zlh-wings Old Wings — kept for reference
103 zlh-api Old API VM — kept for reference

Stack

API (zpack-api, VM 1005): Node.js ESM, Express 5, Prisma 6, MariaDB, Redis, BullMQ, JWT, Stripe, argon2, ssh2, WebSocket

Portal (zpack-portal, VM 1100): 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 (VM 1003).

Agent (Operational)

  • HTTP server on :18888, internal only — API is the only caller
  • Container types: game (Minecraft, Rust, Valheim, etc.) and dev (node/python/go/java runtimes)
  • Runtime root: /opt/zlh/minecraft/<runtime>/<world>/
  • Lifecycle: POST /config triggers async provision + start pipeline
  • Filesystem: strict path allowlist, atomic writes, shadow backups (7-day retention, 6h cleanup cycle)
  • Upload paths: mods/*.jar (250MB), world/datapacks/*.zip (100MB)
  • Upload transport: raw http.request piping (req.pipe(proxyReq)), never fetch()
  • Console: PTY-backed WebSocket, one read loop per container
  • Self-update: periodic check + apply
  • Forge/Neoforge: automated 5-step post-install patch sequence
  • Modrinth mod lifecycle: install/enable/disable/delete — fully operational
  • Provenance: .zlh_metadata.json — source is null if not set, no curated inference currently implemented

Game Support

Production: Minecraft (vanilla/Fabric/Paper/Forge/Neoforge), Rust, Terraria, Project Zomboid

In Pipeline: Valheim, Palworld, Vintage Story, Core Keeper

Developer-to-Player Pipeline (Revenue Model)

LXC Dev Environment ($15-40/mo)
  → Game/mod creation + testing
  → Testing servers (50% dev discount)
  → Player community referrals (25% player discount)
  → Developer revenue share (5-10% commission)
  → Viral growth

Revenue multiplier: 1 developer → ~10 players → $147.50/mo total.

Open Threads

  1. Upload timeout tuning — need clear separation of client abort / upstream timeout / socket reset in upload route logging
  2. Dev server filesystem model — game servers complete; dev container file layout, artifact promotion strategy, and edit scope not yet designed
  3. Curated provenance — tracking install origin (Modrinth, manual, etc.) not yet implemented
  4. Optional future: config diff viewer, upload progress UI, upload cancellation, log search

Repo Registry

Repo Purpose
zlh-grind Architecture decisions, constraints, session logs — source of truth
zlh-docs API/agent/portal reference docs (read from source)
zpack-api API source (mirror)
zpack-portal Portal source (mirror)
zlh-agent Agent source

All at git.zerolaghub.com/jester/<repo>

Session Guidance

  • zlh-grind is the authoritative constraint layer — check before making architecture decisions
  • zlh-docs has full agent documentation (routes, filesystem rules, provisioning pipeline)
  • 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 through API
  • Upload transport uses raw http.request piping, never fetch()
  • VMs 100, 101, 103 are legacy reference only — not active production
  • Do not speculate future features as implemented