initial commit

integrations/whmcs/README.md

@@ -0,0 +1,65 @@
+# WHMCS integration
+
+This directory contains the future WHMCS provisioning and addon modules for HexaHost GameCloud.
+
+## Overview
+
+In production billing mode (`BILLING_PROVIDER=whmcs`), WHMCS is the **commercial system of record** for customers, orders, invoices, and payments. GameCloud remains the **technical system of record** for servers, nodes, lifecycle, and usage metrics.
+
+Integration is **API-only** — no direct cross-database writes.
+
+## Directory structure
+
+```text
+integrations/whmcs/
+  README.md                          # This file
+  modules/
+    servers/hexagamecloud/           # Provisioning module (Phase WHMCS-A+)
+    addons/hexagamecloud/            # Global settings, mappings, reconciliation
+  tests/
+    Unit/
+    Integration/
+    Contract/
+    Fixtures/
+  packaging/
+    build-package.sh
+    manifest.json
+```
+
+## Modules
+
+### Server module (`hexagamecloud`)
+
+Install path on WHMCS: `/modules/servers/hexagamecloud/`
+
+Handles per-service lifecycle:
+
+- CreateAccount, Suspend, Unsuspend, Terminate
+- Renew, ChangePackage
+- Client area status and SSO
+- Usage metrics export
+
+### Addon module (`hexagamecloud`)
+
+Install path: `/modules/addons/hexagamecloud/`
+
+Handles global configuration:
+
+- API credentials and mTLS
+- Product / option / addon mappings
+- Reconciliation dashboard
+- Event polling from GameCloud
+
+## Status
+
+**Phase 0:** Directory placeholders only. Implementation follows MVP Phase 9 and WHMCS phases A–F documented in the master specification.
+
+## Documentation (planned)
+
+- `docs/integrations/whmcs/installation.md`
+- `docs/integrations/whmcs/configuration.md`
+- `docs/integrations/whmcs/security.md`
+
+## Technical module name
+
+Always `hexagamecloud` — do not rename without a migration plan.

integrations/whmcs/modules/addons/hexagamecloud/README.md

@@ -0,0 +1,7 @@
+# Addon module placeholder
+
+Implementation planned in WHMCS Phase A.
+
+Target install path: `/modules/addons/hexagamecloud/`
+
+Handles global API settings, product mappings, reconciliation, and event polling.

integrations/whmcs/modules/servers/hexagamecloud/README.md

@@ -0,0 +1,7 @@
+# Server provisioning module placeholder
+
+Implementation planned in WHMCS Phase A–B.
+
+Target install path: `/modules/servers/hexagamecloud/`
+
+See `integrations/whmcs/README.md` for the full module layout.

integrations/whmcs/packaging/README.md

@@ -0,0 +1,9 @@
+# WHMCS module packaging
+
+Reproducible ZIP packages for distribution to WHMCS installations.
+
+Planned artifacts:
+
+- `build-package.sh` — assembles modules into a versioned ZIP
+- `manifest.json` — module metadata and compatibility matrix
+- `checksums.txt` — SHA-256 hashes for release verification

integrations/whmcs/tests/README.md

@@ -0,0 +1,10 @@
+# WHMCS integration tests
+
+PHPUnit and contract tests against the GameCloud integration API will live here.
+
+Subdirectories:
+
+- `Unit/` — mapping, signatures, idempotency
+- `Integration/` — module functions with mocked WHMCS
+- `Contract/` — API request/response validation
+- `Fixtures/` — sample WHMCS payloads