# ZeroLagHub – File System & File Browser Strategy

**Date:** 2026-02-28
**Status:** Planning — not yet implemented
**Next Action:** Stub file endpoints in existing agent, prove end-to-end, extract later

---

## Context

This document captures the architectural decisions and UX direction for file system access in ZeroLagHub game and dev containers. It is a planning document, not an implementation spec.

---

## Use Cases

### Game Server Owners (non-technical)
- Edit `server.properties` and config files
- Upload mod `.jar` files to `/mods`
- Restore deleted mods from `/mods-removed`
- Download log files for debugging

### Developers / BYOS (technical)
- Full shell access
- File transfer (upload/download)
- SFTP access to dev container filesystem

These are two distinct personas with different needs and different solutions.

---

## Architecture Decision

### Game Server File Access
Handled via **agent file endpoints + portal file browser UI**.

No SSH required. The agent exposes REST file management endpoints. The API proxies them behind auth + ownership enforcement (same pattern as all other agent endpoints). The portal renders a file browser panel.

### Dev Container File Access
Handled via **WebSSH2 + SFTP**, proxied through the API.

Developers get a real SSH2 session with SFTP channel. No direct container access from the browser — API proxy maintains the security boundary (DEC-008).

---

## Agent File Endpoints (Planned)

```
GET    /game/files?path=          — list directory
GET    /game/files/download?path= — download file
POST   /game/files/upload?path=   — upload file
DELETE /game/files?path=          — delete file
PATCH  /game/files                — rename file
```

Mirrored in API under:
```
/api/game/servers/:id/files/*
```

### Security Requirements
- Hard-rooted to `serverRoot` — no path traversal outside container root
- HTTPS only
- Auth + ownership enforced at API layer
- Upload size limits enforced
- No execution of uploaded files

---

## Implementation Sequencing

**Do not split the agent yet.**

Land file endpoints in the existing agent first. Prove the feature end-to-end. Once the surface area is clear and stable, extract if needed.

SFTP is the exception — if SFTP access for dev containers is implemented, it warrants its own separate process from day one due to SSH server complexity. It does not belong in the main game agent.

### Phased approach
1. File endpoints in existing agent (stub → prove → harden)
2. Portal file browser UI wired to API proxy
3. SFTP as separate agent process for dev containers (separate binary, separate port, separate systemd unit)

---

## Frontend File Browser Direction

### Layout
Split-pane panel — directory tree left, file detail/actions right. Slides in as a panel, does not replace the console view. Server console remains visible.

### Navigation
Breadcrumb-based. Flat navigation within each directory rather than deep tree expansion. Click folder → replace view. Not expand-in-place.

### File Listing
Columns: name, size, modified date, type icon. For `.jar` files: status badge (enabled / disabled / removed).

### Actions
Context menu or per-row three-dot menu. Actions: download, delete, rename. For `.jar` files: enable / disable toggle. Drag-to-upload supported, file picker fallback.

### In-Browser Editor
Plain textarea or Monaco for text files (`server.properties`, `.json`, `.txt`). Binary files get download link only. Not required for launch.

### `mods-removed` Surface
"Recently removed" section or toggle to show `/mods-removed` alongside active mods. This makes soft delete visible and gives users a restore path without knowing the underlying filesystem layout.

### What to Avoid
- Deep expand/collapse tree for mod directory (use flat list + filter)
- In-browser zip/unzip
- Making the file browser the primary surface — mod manager stays primary, file browser is secondary/advanced

---

## Per-Container Web Server Decision

**Do not run Nginx or Caddy per container.**

The agent already runs an HTTP server. Serving static file browser assets from the agent directly keeps per-container footprint minimal. No additional process, no config management, no extra memory overhead.

Caddy or Nginx per container would make sense if you needed per-container SSL termination or direct browser access without the API proxy. ZLH's architecture routes everything through the API proxy (`zlh-proxy` handles SSL at the edge), so a local web server adds a layer without adding capability.

---

## Resilience Notes

The file agent (when extracted) should follow the same binary resilience pattern as the main agent:

- Versioned release layout (`releases/<version>/`)
- `current` symlink pointing to active binary
- Previous version retained on disk
- Systemd watchdog flips `current` back to previous on health check failure
- No dependency on artifact server for rollback — local fallback only

This keeps the file service self-healing without operator intervention, consistent with ZLH's overall design goal.

---

## Related Documents

- `docs/architecture/mod-deployment-safety.md` — mod lifecycle and rollback model
- `docs/architecture/dev-to-game-artifact-pipeline.md` — dev container promotion pipeline
- `OPEN_THREADS.md` — file browser listed as next major feature
- `Frontend/TerminalView_Component.md` (knowledge-base) — terminal implementation reference
- WebSSH2: `https://github.com/billchurch/webssh2` — SFTP + SSH2 for dev containers