zlh-grind/CONSTRAINTS.md

ZeroLagHub — Frontend Constraints (ZLH Grind)

These constraints are non-negotiable.
They exist to prevent architectural drift, instability, and "demo-ware" UI patterns.

Runtime & Framework

• Node.js 22 LTS
• Next.js App Router
• React 18
• TypeScript
• Build once → run many
• No runtime builds
• No PM2 during active development

SSR & Client Boundaries

• Any file that touches:
  • window
  • document
  • location
  • WebSockets
  • xterm / DOM refs
    MUST be a client component with "use client" as the first line.
• No browser globals at module scope in server components.
• Prefer useEffect for browser-only logic.

UI Philosophy

• Control-plane first, not marketing gimmicks.
• Flat UI by default.
• Subtlety beats spectacle.
• Readability > novelty.

Explicitly Forbidden

• Neon / RGB accent colors outside error states
• Scanline / CRT / HUD overlays
• Persistent 3D transforms or perspective UI
• Excessive glow stacking
• Clip-path bevel frames
• Continuous decorative animations

Branding

• Brand: ZeroLagHub
• Shorthand: ZLH
• Gaming heritage is acceptable, esports aesthetic is not.

Authentication Constraints (APIv2)

• APIv2 authentication is stateless
• JWT tokens are issued by APIv2 only
• No CSRF protection is allowed
• No cookies are allowed for auth
• Portal stores tokens client-side (sessionStorage)
• APIv1 and Pterodactyl auth patterns are forbidden

---

Network & Agent Architecture (CRITICAL)

Frontend Cannot Reach Agents

The Rule

• Frontend must never call agents directly
• All agent access flows through API
• Container IPs are internal-only (10.x network)
• No CORS headers exist on agents

Why This Is Enforced

• Agents are not web services
• They have no public network path
• Direct calls would fail (no route)
• API enforces auth, logging, rate limits

Correct Pattern

Frontend → API → Agent

Forbidden Pattern

Frontend → Agent (FAILS)

Common Violations

Adding CORS to Agents

• Never add CORS headers to agents
• Agents are not HTTP APIs
• This breaks security model

Exposing Agent Ports

• Do not proxy agent ports through Caddy
• Do not expose container IPs
• API is the only gateway

Frontend Shortcuts

• No direct WebSocket to agent
• No fetch() to container IPs
• No "quick fixes" that bypass API

---

Enforcement

If a change violates these constraints:

• The change must be reverted
• The documentation takes precedence
• AI tools must be corrected

These constraints override convenience.