Panel/docs/architecture/REPOSITORY_OVERVIEW.md

Repository Overview

Workspace reference: GSP-WORKSPACE.md

Purpose

This repository contains the GSP game server hosting platform:

• Panel - the web control panel and customer/admin UI.
• Agent_Linux - the Linux agent that starts, stops, monitors, updates, and logs game servers.
• Agent-Windows - the Windows/Cygwin agent that mirrors the Linux agent as closely as possible.
• Website - the public marketing, customer, and commerce site.

Top-Level Layout

/
  Agent_Linux/
  Agent-Windows/
  Panel/
  Website/
  docs/

Major Components

Panel

The Panel is the orchestration layer. It:

• loads module pages from Panel/modules/*
• talks to agents through Panel/includes/lib_remote.php
• stores panel-side state in the database
• renders server lifecycle, file, backup, scheduler, Workshop, support, and billing pages

Important Panel files:

• Panel/includes/lib_remote.php
• Panel/modules/gamemanager/home_handling_functions.php
• Panel/modules/gamemanager/server_monitor.php
• Panel/modules/config_games/schema_server_config.xml
• Panel/modules/addonsmanager/module.php
• Panel/modules/cron/module.php
• Panel/modules/user_games/module.php

Agents

The agents are the execution layer. They:

• launch game servers inside screen
• stop and restart servers
• read logs
• run updates and install jobs
• execute scheduler jobs
• report status back to the Panel

Important agent files:

• Agent_Linux/ogp_agent.pl
• Agent-Windows/OGP64/OGP/ogp_agent.pl
• Agent_Linux/startups/
• Agent-Windows/ServerFiles/
• Agent_Linux/php-query/
• Agent-Windows/php-query/

Website

The Website is separate from the server runtime path. It is used for:

• public product pages
• documentation links
• customer onboarding
• billing and commerce surfaces

Panel <-> Agent Communication

The Panel uses XML-RPC over HTTP to call methods exposed by ogp_agent.pl.

The remote wrapper lives in:

• Panel/includes/lib_remote.php

The most important calls are:

• universal_start
• remote_stop_server
• remote_restart_server
• remote_server_status
• is_screen_running
• get_log
• remote_query
• scheduler methods

The agents decode the request, execute the action locally, and return a status code or payload.

Database Usage

The Panel database stores:

• server homes and assigned ports
• game definitions and mod mappings
• user permissions and subusers
• scheduler definitions and related data
• content and Workshop metadata
• tickets/support records
• billing and provisioning records

Key tables discovered in current code:

• server_homes
• home_ip_ports
• game_mods
• status_cache
• config_homes
• config_mods
• addons
• server_content_workshop
• server_content_manifest
• server_content_install_history
• tickets
• ticket_messages
• ticket_attachments
• ticket_settings
• billing-related tables in Panel/modules/billing

The agents also keep runtime files such as screen logs, update logs, scheduler state, and helper manifests, but those should be treated as runtime state rather than the source of truth.

Startup Flow

1. User clicks start in the Panel.
2. Panel builds the startup command from the game XML and stored server parameters.
3. Panel sends universal_start to the agent.
4. Agent creates a screen session and launches the server command.
5. Panel polls status and logs.
6. If the managed session exists and the required port listens, the server is considered online.

Status Reporting Flow

The desired status flow is:

Panel asks agent for status
  -> agent checks managed session/process
  -> agent checks required listening port
  -> agent optionally performs query metadata lookup
  -> agent returns structured status
  -> Panel renders ONLINE / STARTING / STOPPING / UNRESPONSIVE / OFFLINE / UNKNOWN

Query results are metadata only. They are not the source of truth for online/offline state.

What To Read First

For future investigations, start with:

1. docs/development/CODEX_GUIDE.md
2. docs/architecture/PANEL_AGENT_FLOW.md
3. docs/modules/GAMEMANAGER.md
4. docs/features/STATUS_SYSTEM.md
5. docs/features/XML_SYSTEM.md