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	includes/functions.php, includes/database_mysqli.php	Creates the OGPDatabase instance and exposes helpers such as resultQuery(), addGameHome(), and logging.	Every panel page, modules/billing/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	includes/lib_remote.php	Wraps agent RPC (install/update, FTP user management, rsync, SteamCMD).	modules/gamemanager/*, modules/billing/create_servers.php, cron jobs.
XML parser	modules/config_games/server_config_parser.php	Converts modules/config_games/server_configs/*.xml into PHP arrays used for provisioning and pricing metadata.	modules/gamemanager, modules/billing (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 modules/billing/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. modules/billing/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 (modules/billing/api/capture_order.php).
   • Panel module page home.php?m=billing&p=provision_servers.
   • Cron/repair actions in modules/billing/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 – modules/billing/docs.php, per-game folders under modules/billing/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	modules/dashboard/dashboard.php	Landing page once authenticated. Pulls stats from homes, invoices, and support modules. Shows "Last updated" footer based on modules/billing/timestamp.txt.	Reads billing_orders, game_homes, tickets.
gamemanager	modules/gamemanager/server_monitor.php, 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.
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 (modules/billing)

Area	Key files	Notes
Public pages	index.php, serverlist.php, order.php, cart.php, payment_success.php, docs.php	All include bootstrap.php, header/footer, shared CSS. Links remain root-relative.
Auth	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	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	api/create_order.php, api/capture_order.php, webhook.php, logs/payment_capture.log	Implements REST checkout. The cart stamps PayPal custom_id with the exact invoice IDs being purchased; capture/webhook handlers use that to mark the correct invoices paid, create/extend orders, and kick provisioning idempotently.
Provisioning bridge	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	cron-shop.php, diag_remote.php	Automations for renewals, diagnostics, health checks.
Documentation	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	logs/, data/, timestamp.txt	Payment JSON archives, debug traces, and "Last updated" canonical string.

External/agent side

Component	Location	Purpose
Remote agent	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 modules/billing/. Required for shared session cookie scope.

Data touchpoints

• Users – gsp_users table is shared. Registration uses modules/billing/register.php, admin pages use 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 modules/billing/logs/ for quick inspection (payment capture, provisioning outcomes, coupon usage).

Usage tips

1. Need a DB object inside modules/billing? Include 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 modules/billing/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 modules/config_games/server_configs/, regenerate docs if needed, and keep the PHP XML-notes mirror (modules/billing/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.