starcoach-arvan-reseller-wp

Unofficial StarCoach hackathon project for a self-contained WordPress reseller plugin integrating one selected ArvanCloud product end-to-end.

Final hackathon release

Version: 0.7.5

This is an unofficial, independent StarCoach hackathon project for the ArvanCloud challenge. It is not an official ArvanCloud product.

The final MVP implements one complete product flow: ArvanCloud Cloud Server resale through WordPress. The plugin provides customer-isolated virtual wallets, mock wallet top-up, real Cloud Server provisioning and Resource ID mapping, hourly billing and ledger entries, reseller share accounting, low-balance notification, and real zero-balance restriction through provider Power-Off.

The customer UI is a small plugin-owned, scoped, responsive interface that remains independent from the active WordPress theme. The WordPress admin remains WordPress-native. No WooCommerce or frontend framework is required.

Quick install and usage

1. Upload and activate the installable plugin ZIP in WordPress.
2. Configure the reseller integration from the plugin admin screens. Real API keys, encryption keys, SMTP credentials, and other secrets must remain in the approved runtime/secret configuration and must never be committed to the repository.
3. Create customer pages that render:
   • [starcoach_wallet]
   • [starcoach_cloud_server]
4. Sign in as a customer to view the wallet, add mock credit, inspect payment/ledger history, select a region, and use the Cloud Server ordering flow.
5. The demo should use the already-verified runtime/resource state for billing and restriction evidence. Do not recreate destructive or provider-changing evidence solely for demonstration.

Judge-facing demo flow

Setup -> Wallet -> Mock top-up -> Cloud Server order -> Resource ID -> Billing/Ledger -> Threshold/Email -> Suspended resource -> Mobile

The repository documents the implementation and security details; the demo video should focus on behavior and the end-to-end business flow rather than source-code walkthroughs.

Known limitations

• Cloud Server is the one fully implemented product in the final hackathon MVP.
• Wallet top-up is intentionally mocked; no real payment gateway is implemented.
• Settlement is intentionally simulated; no real bank/provider financial settlement is performed.
• Zero-balance service enforcement uses provider Power-Off.
• Automatic service reactivation after a later top-up is not implemented in the current MVP.
• Destructive Delete/Terminate actions remain outside the automatic wallet-protection path and require explicit destructive approval.
• Periodic jobs rely on WordPress scheduling plus a targeted request-path reliability fallback; there is no separate always-on worker daemon.
• The outer WordPress page title, header/footer, typography, and outer whitespace remain theme-owned by design.
• Mobile history tables preserve table semantics and use horizontal scrolling on narrow screens.

Current status

Stage 9 is closed and frozen. Stage 10 is limited to final demo, release, documentation, and submission closure. ArvanCloud Cloud Server is the final MVP product for this submission; the proven backend/UI/security behavior from earlier stages is not being reopened for feature expansion.

Frozen architecture direction

• PHP + WordPress Core APIs
• thin WordPress shell/adapters
• isolated Business/Domain layer
• WordPress Users for customer identity
• Custom Tables for transactional/financial state
• PHP-rendered templates
• scoped Sorkhab-inspired CSS
• minimal ES6 JavaScript
• WordPress REST API only where async UX genuinely helps
• WP-Cron for periodic accounting/settlement workflows

No WooCommerce, ACF, required theme, React, Next.js, shadcn, Tailwind, microservices, Temporal, or generic cloud-provider framework is part of the MVP baseline.

Security baseline

No real credential or secret may be committed, logged, documented, screenshotted, or embedded in demo artifacts.

Runtime/development secrets must remain outside source control. Reseller Arvan API keys use reversible authenticated encryption at rest, while encryption key material remains outside both the database and repository.

Financial formula note

The original challenge video contains an example consistent with:

customer charge = Arvan base cost + reseller share

The implemented and frozen customer charge formula is final_charge = base_cost + reseller_share_amount, with reseller share enforced server-side in the configured 0%..20% range.

Workflow

Development is stage-based and evidence-driven. External Arvan mutations, destructive actions, Git push, deployment, and other sensitive mutations require explicit approval at their relevant stage.

Stage 1 frozen decisions

• MVP product: ArvanCloud Cloud Server
• Live API family: https://napi.arvancloud.ir/ecc/v1
• Billing dimension: Cloud Server price_per_hour
• Financial formula: final_charge = base_cost + reseller_share_amount
• Reseller share: server-side 0%..20%
• Suspend mapping: Cloud Server power-off
• Terminate/cleanup mapping: controlled server deletion
• No real Arvan state-changing mutation was executed during Stage 1 research.

See docs/requirements/ and docs/decisions/0001-cloud-server-mvp.md for the frozen contracts.

Stage 2 foundation

Stage 2 adds the minimal WordPress plugin bootstrap, isolated Domain/Application/Infrastructure directories, and the requirement-derived Custom Table migration definition.

Important: committing the migration source does not activate the plugin or mutate a WordPress database. Database execution remains an explicitly approved later validation step.

See docs/requirements/stage-02-foundation.md.

Stage 3 reseller security boundary

Stage 3 adds reseller eligibility verification, server-side 0–20% share enforcement, admin configuration, and authenticated encryption for the Arvan API key.

Secret inputs are intentionally external to the repository:

• STARCOACH_ARVAN_RESELLER_ACCESS_TOKEN_HASHES
• STARCOACH_ARVAN_RESELLER_ENCRYPTION_KEY

Plaintext Access Tokens and Arvan API keys must not be committed, logged, or rendered back.

See docs/requirements/stage-03-reseller-security.md.

Stage 4 customer wallet

Stage 4 uses WordPress users as customer identities and adds the first functional customer money flow:

• requirement-scoped wallet,
• mock top-up payments with pending/successful/failed lifecycle,
• idempotent wallet credit,
• immutable-style ledger credits,
• customer-isolated payment/ledger history,
• minimal [starcoach_wallet] shortcode.

Authoritative money input is normalized as a decimal string and wallet arithmetic remains on database DECIMAL fields.

See docs/requirements/stage-04-wallet-payments-ledger.md.

Stage 5 Cloud Server provisioning source

Stage 5 adds the one-product provisioning vertical slice for ArvanCloud Cloud Server:

• live catalog adapters,
• server-side price_per_hour quote,
• frozen reseller-share formula,
• idempotent persisted order state,
• exactly-one create attempt after order claim,
• ambiguous-outcome reconciliation state,
• exact Resource ID -> WordPress customer mapping,
• minimal [starcoach_cloud_server] customer surface.

No real Cloud Server is created by the repository mutation script. The first real Arvan mutation remains a separate explicit safety checkpoint.

See docs/requirements/stage-05-cloud-server-provisioning.md.

Stage 5 real-provider contract validated

A controlled real ArvanCloud Cloud Server create returned HTTP 201 and a Resource ID, and the resource was subsequently verified ACTIVE by GET. The WordPress provisioning adapter is aligned with that proven provider contract.

See docs/requirements/stage-05-cloud-server-provisioning.md for the exact request contract and mutation safety rules.

Stage 6 hourly billing

Stage 6 implements the Cloud Server hourly consumption/billing path on the existing Custom Tables:

• completed UTC hourly periods,
• deterministic duplicate-resistant billing_key,
• persisted frozen rate/share audit fields,
• atomic billing row + wallet debit + ledger debit,
• bounded WP-Cron catch-up,
• separation between customer billing and Stage 7 settlement.

Local PHP/Docker tooling is not required. Automated PHP lint/regression validation is executed by GitHub Actions. Database-backed WordPress Cron/runtime behavior was validated on the Liara integration environment before final release/demo.

See docs/requirements/stage-06-hourly-billing.md.

Stage 7 settlement simulation

Stage 7 adds a separate periodic settlement process that consumes immutable Stage 6 billing rows without recalculating historical money.

Each hourly settlement batch freezes its exact billing source set, persists aggregate base/share/final totals, links source billing rows through settlement_id, and crosses a deterministic secret-free mock settlement boundary. Failed mock batches have controlled retry state.

No real bank payment or Arvan financial settlement is performed.

See docs/requirements/stage-07-settlement-simulation.md.

Stage 8 wallet protection

Stage 8 adds a configurable wallet warning threshold, customer low-balance email, and the Cloud Server restriction adapter.

When balance is zero or negative, the plugin persists a unique power_off service action before calling the ArvanCloud power-off endpoint. Ambiguous outcomes are reconciled with provider GET state and are never blindly retried.

The customer Cloud Server surface renders the persisted restricted/suspended state. Stage 9 polished and validated this state across desktop, mobile, explicit English/LTR, and a second WordPress theme.

The source/CI stage itself does not execute a real restriction. The approved Liara runtime evidence later proved one-attempt Power-Off, provider SHUTOFF, local suspended, and the customer restricted state; that real-provider mutation is not repeated for release/demo.

See docs/requirements/stage-08-wallet-protection.md.

Stage 8 provisioning reconciliation hardening

Source 0.7.4 persists the requested Cloud Server server_name before the provider create request and adds a formal GET-only reconciliation path for reconciliation_required orders.

The recovery path never retries CreateServer. It requires exactly one exact provider name match in ACTIVE state and reuses the order's persisted frozen quote while creating the local Service mapping.

Schema version 2 includes a boot-time migrate_if_needed() path for already-active plugin replacement.

The Liara runtime evidence window subsequently proved natural hourly billing, settlement, wallet-zero restriction, one-attempt Power-Off, provider SHUTOFF, local suspended, and the customer restricted state.

See docs/requirements/stage-08-provisioning-reconciliation.md.

Stage 8 closure hardening

Source 0.7.5 closes two runtime integration gaps without changing the proven business rules.

SMTP remains WordPress wp_mail(), with PHPMailer configured only from external runtime constants. No SMTP credential belongs in the repository or database.

A targeted request-path reliability fallback handles only StarCoach recurring hooks that are at least five minutes overdue. It respects a live WordPress doing_cron lock, ignores a stale lock, executes overdue StarCoach jobs in Billing -> Settlement -> Wallet Protection -> Provisioning Reconciliation order, and reschedules only those StarCoach hooks. It never invokes generic wp-cron.php.

The real Power-Off test is not repeated for 0.7.5; existing idempotency and provider reconciliation evidence remain authoritative.

See docs/requirements/stage-08-closure-hardening.md.