Skip to content

Monetization System (The Engine)

The Root System was built explicitly to make money. It features a robust, immutable virtual ledger that securely tracks and spends credits across complex AI operations.

The Wallet Architecture

Every User in the system has an associated Wallet.

Row-Level Locking

The wallets application guarantees mathematical accuracy by utilizing row-level locking (select_for_update()) during every transaction. This absolutely prevents race conditions where a user might fire multiple concurrent requests to bypass their available balance.

Immutable Transaction Log

Credits are never merely added or subtracted from an integer column. Every deduction or addition spawns an immutable Transaction record, keeping a perfect historical audit trail for customer support and financial reconciliation.

Credit Deductions & Costs

AI endpoints don't have hardcoded costs. We use a dynamic ProviderFeatureCost database model.

When a user calls an endpoint (e.g., Image-to-Image Generation):

  1. The endpoint queries the ProviderFeatureCost for the requested feature.
  2. The cost is evaluated based on the configuration (e.g., 5 credits).
  3. The Wallet executes an atomic transaction. If insufficient, a standard error is returned.
  4. The generation task begins.

Dynamic Margin Adjustment

This model allows administrators to adjust profit margins directly from the Django Admin panel without redeploying code.

Handling Refunds (Automated Logic)

AI APIs are inherently unreliable. Generation tasks occasionally fail due to timeouts, NSFW filters, or vendor outages.

Root System features automated partial-failure refund protocols. If a Celery Task catches an exception or receives a FAILED state from a vendor, the ai_core immediately initiates a compensating transaction, returning the exact deducted credits back to the user's wallet automatically.

Webhooks & Subscriptions (The store App)

The store application is responsible for interfacing with payment processors, primarily acting as a webhook receiver.

Turnkey Integrations

We provide out-of-the-box endpoints designed to catch webhooks from:

  • RevenueCat (for Mobile iOS/Android)
  • Lemon Squeezy (for Web/SaaS)

Entitlements

When a webhook arrives (e.g., INITIAL_PURCHASE), the system validates the cryptographic signature, extracts the customer ID, and maps it to a database Entitlement. If the entitlement grants a recurring subscription, the system automatically deposits the monthly credit allotment into the user's wallet.

Promotional & Geospatial Ledger

Driving user acquisition requires flexibility.

The RegistrationBonusConfig dictates how many free credits new users receive. It uses intelligent geospatial tagging based on IP geolocation and device IDs.

Geotargeting Growth

This allows you to aggressively acquire users in high-value countries (e.g., US/UK) with generous sign-up bonuses, while preventing automated bot farms from abusing free trials in other regions.

Automated Ledger Maintenance

Using django-celery-beat, the system runs distributed cron jobs to perform necessary ledger maintenance.

This includes:

  • Expiring old subscription credits at the end of a billing cycle.
  • Reconciling delayed RevenueCat receipts.
  • Purging deleted accounts following app-store compliance regulations.

Wallet Analytics & Insights

The centralized Django Administration panel has been meticulously customized to act as a financial command center. Operators can easily track real-time wallet analytics to understand how credits are flowing through the system:

  • Net Movement (Outstanding Credits): The exact net change in circulating credits during a specific time window.
  • Utilization & Expiration Rates: Insights into what percentage of issued credits are actively being spent versus expiring unused. A utilization rate over 100% indicates users are burning through older hoarded balances.
  • Credit Breakdowns: Trace exactly what percentage of issued credits originated from Top-ups, Refunds, or Registration bonuses.

Wallet Summary Dashboard