zlh-grind/UPSTREAMS.md

Upstreams / Dependency Notes

This file is a concise reference for important repo/runtime dependencies that affect current implementation work.

Use it for:

• major framework/runtime dependencies
• important transport or proxy assumptions
• shared infrastructure dependencies such as the artifact server

Do not use this file as a backlog.

---

Portal (zpack-portal)

Core dependencies / assumptions:

• Next.js
• Axios for API interaction
• WebSocket-backed console UI through the API bridge
• multipart/FormData upload flows through API/agent paths

Portal boundary:

• Portal talks to API, not directly to agents, for normal state/actions

---

API (zpack-api)

Core dependencies / assumptions:

• Node.js (ESM)
• Express
• Prisma
• token/cookie-based auth flows
• WebSocket proxying for console / IDE flows
• raw http.request piping for upload proxy paths

API boundary:

• API is the polling/heartbeat authority for agent state
• API normalizes state for Portal consumption

---

Agent (zlh-agent)

Core dependencies / assumptions:

• Go
• filesystem enforcement / sandboxing
• PTY and WebSocket console transport
• local metadata tracking for managed files/workloads
• local Minecraft backup / restore support

Agent boundary:

• agent owns local workload-aware behavior
• agent does not own offsite/PBS durability strategy

---

zlh-artifacts (Artifact Server)

Role:

• central artifact distribution for runtime and addon installs

Artifacts currently hosted:

devcontainer/
  _catalog.json
  go/
  node/
  python/
  java/
  dotnet/

addons/
  code-server/

Used by:

• zlh-agent

Artifacts are downloaded during provisioning via artifact URL helpers (for example, provcommon.BuildArtifactURL(...)).

Containers do not rely on prepositioned artifacts.

---

Operational reminders

• upload transport uses raw piping, not fetch(), on proxy/upload paths
• hosted browser IDE flow is edge → API → container, not direct edge → container
• game publish flow and dev IDE flow should not be conflated