From b03836057ffa9e5ef04fe37c0c7e9f0c2a1e9ec7 Mon Sep 17 00:00:00 2001
From: jester <admin@zerolaghub.com>
Date: Sun, 18 Jan 2026 23:57:55 +0000
Subject: [PATCH] docs: add architectural boundaries to prevent frontend-agent
 drift

---
 PORTAL_MIGRATION.md | 61 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 55 insertions(+), 6 deletions(-)

diff --git a/PORTAL_MIGRATION.md b/PORTAL_MIGRATION.md
index 97b9aec..6a4dd98 100644
--- a/PORTAL_MIGRATION.md
+++ b/PORTAL_MIGRATION.md
@@ -113,12 +113,12 @@ It does not directly query agents, Proxmox, or exporters.
 ### UI Mapping
 
 | Container Type | Host Online | Agent State | UI Status |
-|---------------|------------|-------------|-----------|
-| DEV           | true       | n/a         | running   |
-| DEV           | false      | n/a         | offline   |
-| GAME          | true       | running     | running   |
-| GAME          | true       | idle        | stopped   |
-| GAME          | false      | n/a         | offline   |
+|----------------|-------------|-------------|-----------|
+| DEV            | true        | n/a         | running   |
+| DEV            | false       | n/a         | offline   |
+| GAME           | true        | running     | running   |
+| GAME           | true        | idle        | stopped   |
+| GAME           | false       | n/a         | offline   |
 
 ### Notes
 - "Idle" does **not** mean broken
@@ -149,3 +149,52 @@ This model intentionally mirrors Pterodactyl semantics.
 - Must not assume process state
 
 This split is intentional and enforced to prevent drift.
+
+---
+
+## Architectural Boundaries (CRITICAL)
+
+### What Frontend MUST NOT Do
+
+**Never Call Agents Directly**
+- Frontend cannot reach container IPs
+- Frontend has no network path to agents
+- All agent access flows through API
+- This is non-negotiable architecture
+
+**Why This Matters**
+- Container IPs are internal-only (10.x network)
+- No CORS headers on agents (they're not web services)
+- Direct calls would fail and break the security model
+- API enforces auth, rate limits, and access control
+
+**Correct Flow**
+```
+User Action → Frontend → API → Agent → Response
+```
+
+**Incorrect Flow (FORBIDDEN)**
+```
+User Action → Frontend → Agent (FAILS - no network path)
+```
+
+### What Can Break This
+
+**AI Coding Tools**
+- May suggest "quick fixes" that call agents directly
+- May treat agents as HTTP APIs with CORS
+- May generate code that "just works" in wrong way
+
+**Convenience Changes**
+- Adding CORS headers to agents (never do this)
+- Exposing agent ports through proxy (breaks security)
+- Creating frontend → agent shortcuts (breaks architecture)
+
+### Enforcement
+
+If a change violates these boundaries:
+- The change must be reverted
+- The documentation takes precedence
+- AI tools must be corrected
+
+These constraints override convenience.