# 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/includes/provisioner.php` reuses `modules/billing/create_servers.php` logic to allocate homes, assign nodes/IPs, configure mods, and kick off SteamCMD/rsync/manual installers. 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. Once capture is confirmed, writes invoices/orders, updates coupons, and kicks `BillingProvisioner`. |
| 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._
