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.