Panel/.github/module-map.md

GSP Module & Interaction Map

This file captures how the control panel, storefront, agents, and helper scripts talk to one another. Read it before diving into any subsystem—most regressions last time came from touching one module without realizing who consumed its data.

Core runtime (shared by every module)

Area	Key files	Responsibilities	Downstream callers
Database bootstrap	Panel/includes/functions.php, Panel/includes/database_mysqli.php	Creates the OGPDatabase instance and exposes helpers such as resultQuery(), addGameHome(), and logging.	Every panel page, Website/Website/includes/panel_bridge.php, cron jobs.
Session helpers	includes/helpers.php (startSession())	Sets session_name('opengamepanel_web'), sanitizes request vars, loads locales.	index.php, home.php, provisioning pages, storefront session bridge.
Remote control	Panel/includes/lib_remote.php	Wraps agent RPC (install/update, FTP user management, rsync, SteamCMD).	Panel/modules/gamemanager/*, Website/create_servers.php, cron jobs.
XML parser	Panel/modules/config_games/server_config_parser.php	Converts Panel/modules/config_games/server_configs/*.xml into PHP arrays used for provisioning and pricing metadata.	Panel/modules/gamemanager, Website/ (catalog + provisioner), cron installers.
API surface	ogp_api.php, includes/api_functions.php	HTTP API for third-party tooling. Exposes operations such as starting/stopping homes, querying stats.	Mobile apps, automated provisioning, selected billing workflows.
Cron/automation	scripts/ (cron-shop.php, status/*, etc.)	Suspends/unsuspends services, refreshes status caches, runs backups.	Triggered via system cron or panel scheduler.

High-level flows

1. Auth/session – Driven by index.php (panel) and Website/login.php (storefront). Both set $_SESSION['user_id'], users_login, users_group, and website_user_id. The shared session cookie opengamepanel_web means logging into either surface immediately authenticates the other.
2. Catalog – modules/config_games hosts XML definitions. Panel modules (gamemanager, config_games) and storefront pages (serverlist.php, order.php, documentation pages, and the XML-notes mirror) parse these files for display and provisioning metadata.
3. Provisioning – Orders land in gsp_billing_orders. Website/create_servers.php allocates homes, assigns nodes/IPs, configures mods, kicks off SteamCMD/rsync/manual installers, and then syncs the resulting home_id back into billing_orders, billing_invoices, and billing_transactions so paid services never stay orphaned. The same provisioner is invoked by:
   • PayPal capture endpoint (Website/api/capture_order.php).
   • Panel module page home.php?m=billing&p=provision_servers.
   • Cron/repair actions in Website/cron-shop.php.
4. Renewals – cron-shop.php inspects billing_orders.end_date and toggles status between installed, invoiced, suspended, and deleted. PayPal renewals extend end_date in capture_order.php and immediately flip status back to installed.
5. Documentation – Website/docs.php, per-game folders under Website/docs/, and the XML wiki mirror (PHP port of XML-Notes) are used by both admins and AI helpers to craft game templates.

Panel modules (selected)

Module	Key files	Primary responsibilities	Upstream/Downstream dependencies
dashboard	Panel/modules/dashboard/dashboard.php	Landing page once authenticated. Pulls stats from homes, invoices, and support modules. Shows "Last updated" footer based on Website/timestamp.txt.	Reads billing_orders, game_homes, tickets.
gamemanager	Panel/modules/gamemanager/server_monitor.php, Panel/modules/gamemanager/game_monitor.php	Shows owned homes, start/stop, update, reinstall, port usage. Uses XML to know command lines.	Relies on lib_remote, config_games, user_games assignments.
config_games	modules/config_games/add_mod.php, server_config_parser.php, XML files under server_configs/	Admin UI for XML definitions. Controls what appears in storefront/service catalog.	Feeds gamemanager, billing catalog, cron installers.
steam_workshop	modules/steam_workshop/admin.php, user.php, Panel/includes/functions.php, navigation.xml	Admin profile defaults + per-home mod management. Profile defaults can now be refreshed from game XML and the user route is explicitly exposed via p=user.	Uses config_games XML metadata + server_homes/assignment tables; feeds workshop agent updater.
user_games	modules/user_games/add_home.php, assign_home.php, edit_home.php	Admin workflow to add homes manually or edit assignments. Shares DB tables with billing provisioner.	Uses game_homes, remote_servers, billing_orders.
administration / user_admin	CRUD around users, groups, permissions, expire dates.	Sets roles consumed by storefront admin guard and provisioning ACLs.
server	modules/server/*	Remote server management (agents, IPs, ports, reinstall keys). Billing uses these tables for available nodes/locations.
modulemanager	Manage module install/uninstall/menus. Billing module registers navigation.xml to surface create_servers.php & admin pages.
tickets, support	Support ticketing/email utilities.	Pulls user info and logger records.
extras, addonsmanager	Workshop/add-on management.	Hooks into game homes after provisioning.
litefm, ftp, TS3Admin	File managers and TeamSpeak controllers.	Depend on homes and remote server credentials set during provisioning.
news, circular, faq	Content modules for panel UI.	Use standard MVC wrappers, share session/auth.
cron	Scheduler UI feeding scripts/ commands.	Maintains job metadata that OS cron reads.

Storefront (Panel/modules/billing runtime + Website/ compatibility wrappers)

Area	Key files	Notes
Public pages	Panel/modules/billing/index.php, serverlist.php, order.php, cart.php, payment_success.php, docs.php	Runtime now lives under Panel/modules/billing. Website/*.php wrappers proxy legacy paths to these files.
Auth	Panel/modules/billing/login.php, register.php, reset_password.php, forgot_password.php, includes/login_required.php, includes/admin_auth.php	Share opengamepanel_web session, call into panel DB to validate roles.
Admin	Panel/modules/billing/admin.php, adminserverlist.php, admin_orders.php, admin_coupons.php, admin_config.php, my_orders_panel.php	Manage services, coupons, prices, and provisioning. adminserverlist.php controls service availability per node.
PayPal API	Panel/modules/billing/api/create_order.php, api/capture_order.php, paypal/webhook.php, logs/payment_capture.log	Implements REST checkout. Legacy Website/api/* and Website/paypal/webhook.php wrappers proxy to module runtime.
Provisioning bridge	Panel/modules/billing/create_servers.php, includes/provisioner.php, includes/panel_bridge.php	Shared between panel module and storefront backend. Encapsulates whole server creation/renewal pipeline.
Cron helpers	Panel/modules/billing/cron-shop.php, diag_remote.php	Automations for renewals, diagnostics, health checks.
Documentation	Panel/modules/billing/docs.php, docs/*, docs/admin_xml_notes.php (PHP mirror of XML wiki)	Provide guidance for editing XML and game configs directly inside repo.
Logs/data	Panel/modules/billing/logs/, data/, timestamp.txt	Payment JSON archives, debug traces, and runtime timestamp (synced from canonical Website/timestamp.txt).

External/agent side

Component	Location	Purpose
Remote agent	Panel/modules/gamemanager talks to standalone agent binaries configured per remote_servers.	Executes installs, updates, start/stop commands. Provisioner relies on it for SteamCMD and rsync workflows.
Apache/Nginx vhosts	/etc/apache2/sites-available (not in repo)	Point either the storefront domain or panel subpath at Website/. Required for shared session cookie scope.

Data touchpoints

• Users – gsp_users table is shared. Registration uses Website/register.php, admin pages use Panel/modules/user_admin. Password upgrades must not break panel logins.
• Billing tables – gsp_billing_services, gsp_billing_orders, gsp_billing_invoices, gsp_billing_coupons. Admin edits (pricing, enable/disable, locations) are done via adminserverlist.php; automation uses cron-shop.php.
• Homes/Mods/IPs – Stored in gsp_game_homes, gsp_game_mods, gsp_remote_server_ips. Provisioner writes to these tables; gamemanager, litefm, ftp, and user_games read them.
• Logging – $db->logger() writes to ogp_logs. Storefront-specific logs live in Website/logs/ for quick inspection (payment capture, provisioning outcomes, coupon usage).

Usage tips

1. Need a DB object inside Website/? Include Website/includes/panel_bridge.php and call billing_get_panel_db(). It sets up constants, loads helpers, and caches the OGPDatabase instance so multi-call flows (e.g., capture → provision → email) reuse it.
2. Want to change provisioning? Update Website/includes/provisioner.php once. create_servers.php, PayPal webhooks, cron jobs, and admin repair flows all use it.
3. Working on XML or documentation? Update the XML file under Panel/modules/config_games/server_configs/, regenerate docs if needed, and keep the PHP XML-notes mirror (Website/docs/xml_notes.php) accurate so the admin link stays trustworthy.
4. Need to know who uses a table? Search .github/module-map.md first; the table above lists the canonical readers/writers for each major schema.

Last updated: 2025-11-20.