Codex documentstion created

docs/architecture/PANEL_AGENT_FLOW.md

@@ -0,0 +1,103 @@
+# Panel Agent Flow
+
+## Overview
+
+The Panel does not directly run servers. It prepares the request, sends it to the agent, and interprets the response.
+
+```text
+User action
+  -> Panel module page
+  -> OGPRemoteLibrary in lib_remote.php
+  -> XML-RPC request to agent /RPC2
+  -> ogp_agent.pl method
+  -> local screen/process/port work
+  -> return status or payload
+  -> Panel renders result
+```
+
+## Request Path
+
+Important Panel files:
+
+- `Panel/includes/lib_remote.php`
+- `Panel/modules/gamemanager/start_server.php`
+- `Panel/modules/gamemanager/stop_server.php`
+- `Panel/modules/gamemanager/restart_server.php`
+- `Panel/modules/gamemanager/server_monitor.php`
+- `Panel/modules/gamemanager/view_server_log.php`
+- `Panel/modules/gamemanager/get_server_log.php`
+- `Panel/modules/gamemanager/home_handling_functions.php`
+
+### Start
+
+1. Panel loads the selected server home and game XML.
+2. Panel composes startup parameters from stored values and XML templates.
+3. Panel calls `universal_start` on the agent.
+4. Agent creates the `screen` session and starts the server command.
+5. Panel polls `remote_server_status`.
+6. When the agent reports that the process/session exists and the game port listens, the server is treated as ONLINE.
+
+### Stop
+
+1. Panel calls `remote_stop_server`.
+2. Agent sends the configured graceful stop command if one exists.
+3. Agent watches the session/process and required port.
+4. If the session/process does not exit in time, the agent escalates to screen quit or process kill.
+5. Panel treats the server as stopped only when the agent confirms it is actually gone.
+
+### Restart
+
+Restart should be:
+
+```text
+stop
+  -> wait
+  -> start
+```
+
+The wait period should be explicit and visible in logs. Restart should not depend on marker files or query success.
+
+### Status
+
+1. Panel calls `remote_server_status`.
+2. Agent checks:
+   - managed screen/session
+   - PID or process tree when available
+   - required game port
+   - optional query/RCON ports
+3. Agent returns a structured status object.
+4. Panel maps the result to the UI state.
+
+### Logs
+
+1. Panel calls `get_log`.
+2. Agent returns the latest screen or console log data.
+3. The log view updates via AJAX instead of full-page refresh.
+4. The UI should preserve scroll position and only auto-scroll when the user is already at the bottom.
+
+## Data Returned by Status
+
+Recommended status fields:
+
+- `status`
+- `ready`
+- `process_running`
+- `session_running`
+- `game_port_listening`
+- `query_port_listening`
+- `rcon_port_listening`
+- `pid`
+- `session_name`
+- `ip`
+- `port`
+- `query_port`
+- `last_error`
+- optional query metadata
+
+## Practical Notes
+
+- The Panel should not mark a server failed only because query metadata was unavailable.
+- The agent should be the source of truth.
+- Marker files may exist, but they should be treated as hints only.
+- The same high-level flow should work for Linux and Windows/Cygwin.
+