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 malicious 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 & The store App

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

Multi-Platform Architecture

The system is built to support a diverse, omnichannel monetization strategy, natively tracking 10 distinct platform sources (e.g., App Store, Play Store, Stripe, LemonSqueezy, Paddle, Roku, Amazon, RevenueCat Billing, Promotional, Mac App Store).

The Entitlement Lifecycle

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.

Entitlements are highly robust, tracking: - started_at, expires_at, and grace_period_expires_at - period_type (Normal, Trial, Intro) - cancellation_reason enum (e.g., Billing Error, Voluntary Cancel) - Sandbox vs. Production environments

The model provides an is_active property that mathematically evaluates whether the entitlement is currently valid, correctly handling lifetime purchases, standard active periods, and grace periods for failing credit cards.

If the entitlement grants a recurring subscription, the system automatically deposits the monthly credit allotment into the user's wallet.

The Registration Bonus Engine

Driving user acquisition requires flexibility, but free trials attract massive bot abuse.

Our RegistrationBonusConfig dictates how many free credits new users receive, powered by a highly defensive targeting engine:

  • Complex Hardware & Localization Targeting: We use a strict evaluation engine based on the UpdateUserClientContextMiddleware. You can whitelist or blacklist based on device model (e.g. block old Android phones), OS version, country code, and language.
  • Daily Quotas: Set a maximum number of free grants per day to strictly control your marketing burn rate. (This quota uses select_for_update() row-level locking to guarantee you never exceed your limit).

Triple-Threat Deduplication

To guarantee a user cannot farm free credits by repeatedly deleting and recreating accounts, the check_targeting() engine performs a per-grant audit trail that deduplicates against: 1. The user's normalized Email Address 2. The hardware Device ID 3. The IP Address

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.
  • RevenueCat Reconciliation: A daily background task that proactively queries the RevenueCat API to synchronize entitlement states, catching any dropped webhooks or edge-case state changes.
  • 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