# 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:

```text
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