A secure, prepaid Cloud Server reseller storefront and customer portal for WordPress.
Presentation artwork — the real LocalWP product appears in the demo below.
Demo · Product Tour · Capabilities · Architecture · Security · Testing · Installation
End-to-end Mock Mode: wallet top-up → configuration → authoritative estimate → order → provisioning → active resource.
The 34.5-second, 1280×800, 12fps loop below was captured from the real LocalWP runtime. It also closes with the existing dark-mode card and button interactions in Persian and English. It does not claim or depict paid Live provisioning.
Important
Mock Mode is the safe default. Historical baseline checks are recorded in PROJECT_STATUS.md; the current release-polish branch has not been test-run. The narrow Live adapter is implemented, but a real ArvanCloud Machine User connection has not been verified by an authorized human. This is not an official ArvanCloud product or certified partnership.
ArvanCloud Commerce is a standalone WordPress plugin built around ArvanCloud Cloud Server reseller APIs. It combines a theme-independent public storefront, bilingual customer portal, prepaid wallet, immutable ledger, provisioning, hourly billing, invoices, notifications, and reseller operations.
It relies on WordPress core APIs, authentication, roles, REST, Cron, and custom database tables. It does not require WooCommerce, Elementor, ACF, a page builder, a third-party commerce plugin, or a particular WordPress theme.
| Product area | Current status |
|---|---|
| Customer and reseller portals | Complete |
| Wallet, ledger, billing, invoices, notifications | Complete |
| Catalog, estimate, orders, provisioning | Complete in Mock Mode |
| Payments | Mock only |
| Settlement | Internal accounting only |
| Live ArvanCloud adapter | Implemented · Live unverified |
| Commercial product scope | Cloud Server only |
See PROJECT_STATUS.md for the detailed implementation and verification matrix.
- Exact fixed-scale wallet, quote, billing, invoice, and settlement presentation.
- Server-paginated customer/admin operations with bounded search and honest empty states.
- Theme-safe embedded shortcodes plus isolated standalone Storefront and Portal pages.
- Idempotent provisioning, recovery/manual-review states, redacted audit events, and bounded Cron work.
- Keyboard-aware dialogs/drawers, FA/EN customer UI, responsive layouts, and reduced-motion support.
Eight primary captures represent the real product without turning the README into a vertical screenshot dump. The customer UI supports Persian and English, light and dark themes, responsive navigation, and reduced-motion preferences.
 |
 |
| Public storefront | Customer dashboard · dark · English |
 |
 |
| Wallet and Mock top-up | Server configurator |
 |
 |
| Estimate and order review | Active resource details |
 |
 |
| Reseller operations | Mobile experience |
The complete capture set, including the Persian/English dark interaction states and mobile navigation drawer, is available in docs/screenshots/.
Customers can:
- register, sign in, and use a protected WordPress-backed customer session;
- top up a virtual prepaid wallet in Mock Mode and review immutable transactions;
- configure a Cloud Server and receive a backend-authoritative estimate;
- place an idempotent order and follow provisioning to a mapped Resource ID;
- view services, usage, billing windows, invoices, orders, and notifications.
Resellers and trusted administrators can:
- configure identity, Cloud Server access, pricing share, and lifecycle policies;
- inspect customers, wallets, payments/refunds, orders, and mapped resources;
- review usage, invoices, internal settlement, reconciliation, job health, and audit history;
- rotate or delete an encrypted Machine User credential without exposing it through the settings API.
| Foundation | Reliability and operations |
|---|---|
Integer money at scale 10,000; floats rejected |
Idempotent payments, orders, billing, invoices, and settlement |
| Atomic wallet balance and immutable ledger mutation | Local pending state before remote provisioning |
| Backend-authoritative estimates and first-24-hour prepayment | Recovery markers, reconciliation, bounded retries, and Cron health |
| Snapshotted hourly price and exact UTC billing windows | Low-balance notices, suspension, and termination policies |
| Deterministic zero-network Mock adapter | Allowlisted HTTPS Live adapter for documented IaaS operations |
| Stable Resource ID mapping and customer ownership | Schema migrations, pagination, health checks, and redacted audit events |
| Reseller-share and per-currency internal settlement | Encrypted secret lifecycle, anti-IDOR responses, nonce/capability protection |
Authenticated WordPress REST requests pass through nonce, capability, ownership, and rate-limit controls into the commerce services. Mock provisioning is deterministic and performs zero external provisioning HTTP. Live requests are restricted to a validated regional HTTPS ArvanCloud IaaS v3 destination.
| Stage | Current guarantee |
|---|---|
| Top up | Mock payment confirmation is atomic, idempotent, and credits once. |
| Estimate | Decimal-string hours, integer money, and catalog pricing avoid floating-point drift. |
| Order | The backend prices and debits the first 24 hours before remote create; a unique key prevents duplicates. |
| Provision | Local pending state exists first; recovery and reconciliation cover partial or ambiguous outcomes. |
| Bill | Immutable UTC usage windows and unique ledger references prevent duplicate charging after prepaid_until. |
| Protect | Low-balance notices, suspension, and configured termination are retry-safe. |
| Settle | Per-currency internal settlement references are deterministic and idempotent; no payout is implied. |
| Capability | Mock Mode | Live Mode |
|---|---|---|
| External provisioning HTTP | Zero | Validated HTTPS .arvanapis.ir destination only |
| Catalog and estimate | Complete deterministic fixtures | Adapter implemented; real connection unverified |
| Orders and provisioning | Complete and browser-tested | Implemented; paid provisioning not tested |
| Resource mapping | Complete | Implemented; human integration verification pending |
| Billing and invoices | Complete from snapshotted hourly pricing and UTC windows | Same local model; no official per-server usage endpoint |
| Payments | Mock create/confirm/refund | External payment gateway not implemented |
| Notifications | Complete | Local notification lifecycle implemented |
| Settlement | Internal accounting only | Internal accounting only; no external payout |
| Machine User key | Not required | Authenticated-encrypted least-privilege key |
Customer identity <- authenticated WordPress user resolved server-side
Write authority <- authenticated cookie/session + REST nonce
Admin authority <- manage_arvan_reseller capability + protected endpoints
Secrets <- authenticated encryption; never returned through settings REST
Live destination <- validated region + fixed HTTPS ArvanCloud host rules
Financial mutation <- transaction/locking + immutable ledger + idempotency
- Customer IDs are not accepted from customer requests; customer A cannot retrieve customer B resources.
- Cross-customer authenticated REST isolation tests pass, and foreign/missing resources share the same safe 404 shape to limit ownership leakage.
- Raw remote payloads, SQL errors, stack traces, filesystem paths, and encrypted material are excluded from safe responses and redacted from audit data.
- Unsafe redirects and arbitrary Live API hosts are rejected.
- Corrupt or unsupported credential encryption fails closed; rotation and deletion require explicit actions.
- Deactivation retains data. Uninstall removes the encrypted API credential and transient security state; domain tables follow the configured deletion policy.
Base namespace: /wp-json/arvan-reseller/v1
State-changing calls use the authenticated WordPress cookie/session and
X-WP-Nonce; payment and order creation also use a unique Idempotency-Key.
Customer identity is always derived server-side.
| Area | Current routes |
|---|---|
| Wallet | GET /wallet, GET /wallet/transactions |
| Payments | GET/POST /payments, POST /payments/{reference}/confirm |
| Catalog | GET /catalog/regions, /images, /flavors; POST /catalog/estimate |
| Orders | GET/POST /orders |
| Resources | GET /resources, GET /resources/{local-id} |
| Records | GET /usage, GET /invoices, GET /notifications; POST /notifications/{id}/read |
| Area | Current routes |
|---|---|
| Configuration | GET/PUT/PATCH /admin/settings, POST /admin/connection-test |
| Operations | GET /admin/overview, POST /admin/cron/run, POST /admin/reconciliation/run, GET /admin/health |
| Commerce | GET /admin/customers, /wallets, /payments, /orders, /resources, /usage |
| Finance and audit | POST /admin/payments/{reference}/refund, GET /admin/settlements, GET /admin/audit-logs |
The exact request/response contract, parameters, error codes, pagination, redaction, and ownership rules live in the backend contract.
The following results belong only to historical baseline commit
b0a0b53419bd6bff4037571d0c95c4cf53b1e888; they are not results for the current
branch:
| Check | Result |
|---|---|
| Standalone domain suite | 29 passed · 0 failed |
| Activation and migration harness | PASS |
| Mock end-to-end lifecycle | PASS |
| Disposable real WordPress E2E | PASS |
| Clean installation | PASS |
| Cross-customer authenticated isolation | PASS |
| PHPUnit | 11 tests · 51 assertions · PASS |
| PHPStan | 0 errors |
| PHP syntax | 43/43 · PASS |
| JavaScript syntax | 4/4 · PASS |
| Authenticated encryption / crypto | PASS |
| Secret and debug scan | PASS |
| Browser Mock provisioning and retry stability | PASS |
The current release-polish branch intentionally has no local validation result. CI is configured to run Composer install, PHP syntax checks, PHPUnit, and PHPStan after the branch is pushed or proposed as a pull request. PHPCS is not part of that workflow; historical style debt remains a separate cleanup concern.
- WordPress 6.4 or newer
- PHP 8.2 or newer
- MySQL or MariaDB with InnoDB
- Composer 2 only for development checks
- Install the
arvan-reseller/plugin directory or its release package underwp-content/plugins/. - Activate ArvanCloud Commerce in WordPress.
- Open ArvanCloud Commerce → Setup/Settings and keep API Mode on Mock for development and demonstrations.
- Review the activation-created Storefront and Customer Portal pages.
- Grant
manage_arvan_reselleronly to trusted administrators.
Activation performs versioned custom-table migrations, assigns the administrator
capability, creates/checks the generated pages idempotently, and schedules billing
and reconciliation jobs. The pages use [arvan_reseller_store] and
[arvan_reseller_portal].
Normal WP-Cron is traffic-dependent. For reliable production billing, use a monitored
system scheduler to invoke wp-cron.php regularly; do not disable visitor-triggered
Cron until its replacement is verified.
composer install
composer lint
composer phpunit
composer phpstan
composer phpcs
php tests/run.php
php tests/activation.php
php tests/e2e.phpNo npm package or JavaScript framework is required at runtime. The customer experience uses PHP templates, scoped CSS, modular vanilla JavaScript, and the WordPress REST API.
.
├── arvan-reseller/
│ ├── admin/ # Reseller operations
│ ├── assets/ # Shared design system and JavaScript
│ ├── database/ # Schema and versioned migrations
│ ├── frontend/ # Storefront, authentication, customer portal
│ ├── includes/ # Commerce, security, REST, cloud adapters
│ ├── arvan-reseller.php # Plugin bootstrap
│ └── uninstall.php # Data-retention-aware uninstall
├── docs/
│ ├── assets/ # Hero, architecture, lifecycle artwork
│ ├── demo/ # Real Mock-mode GIF
│ └── screenshots/ # Real LocalWP product captures
├── tests/ # Unit, invariant, activation, and E2E harnesses
├── composer.json # Development quality commands
├── phpunit.xml.dist
├── phpstan.neon.dist
└── phpcs.xml.dist
Further documentation: backend contract · setup guide · UI system · frontend architecture · Live API checklist · project status
Project governance: security policy · GPL-2.0-or-later license · release checklist
The Live adapter is intentionally narrow and currently implements only these documented ArvanCloud IaaS v3 concepts:
GET /availability-zones
GET /images
GET /flavors
POST /servers
GET /servers/{id}
POST /servers/{id}/power-off
POST /servers/{id}/terminate
Anything outside this allowlisted surface is neither invented nor implied. The adapter is implemented and code-reviewed; an authorized, read-only human connection test with a real least-privilege Machine User credential remains outstanding. Follow the Live API checklist before any potentially billable operation.
- Live authentication with a real Machine User and paid Live provisioning remain unverified.
- No external payment gateway is integrated; customer payments are Mock only.
- Settlement is internal accounting and does not initiate an external payout.
- Cloud Server is the only supported commercial product; CDN, Object Storage, DNS, Kubernetes, and other ArvanCloud products are outside the purchase flow.
- Powering off a server cannot guarantee that the external provider stops billing.
- Ambiguous Live create failures require human resolution instead of unsafe automatic retry or refund.
- Billing uses snapshotted hourly flavor pricing and exact UTC windows, not an official per-server usage endpoint.
- Visitor-triggered WP-Cron is not a guaranteed scheduler.
- Current-branch automated and manual acceptance checks remain outstanding; release is blocked until they pass.
Built around ArvanCloud Cloud Server reseller APIs.
Deterministic in Mock Mode. Defensive in Live Mode. Exact around money.