# 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 9 (WHMCS Phase A–B + production DNS)** — implemented.

**Phase D (SSO)** — implemented. See [docs/integrations/whmcs/sso.md](../../docs/integrations/whmcs/sso.md).

**Phase E (Sync & Reconciliation)** — implemented. See [docs/integrations/whmcs/reconciliation.md](../../docs/integrations/whmcs/reconciliation.md).

**Phase F (Usage Billing)** — implemented. See [docs/integrations/whmcs/usage-billing.md](../../docs/integrations/whmcs/usage-billing.md).

- Server module: `integrations/whmcs/modules/servers/hexagamecloud/`
- Addon module: planned for global mappings and reconciliation UI

## 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.