Functional Requirements

Core Requirements

1. Developers should be able to see Robux earnings per game in near real time.
2. Developers should be able to submit a DevEx request (a minimum cashout amount and eligibility rules apply).
3. The system should convert at the rate in effect at submission, not at processing.
4. Developers should be able to track request status and full history.

Below the line (out of scope):

• The eligibility rule engine itself. We consume it as a service.
• Tax documentation and reporting.
• Multi-currency rails; the processor internals.

Non-Functional Requirements

1. The system should never allow over-withdrawal. Balance at submission: strongly consistent.
2. The system should never lose or mutate a financial record. Every decision explainable years later.
3. The system should finish payouts within 5 business days, despite processor downtime, rejections, and partial payments (paid X of a requested Y).
4. The system should serve earnings reads cheaply. Eventually consistent display is fine, labeled with a freshness timestamp (asOf).

Defining the Core Entities

• Developer Account: holds the withdrawable Robux balance and a status (ACTIVE / FROZEN).
• Earnings Ledger Entry: one leg (one half of a transfer, + or -) of a Robux movement. Double-entry. The truth.
• DevEx Request: one exchange. Carries a locked rate, an eligibility snapshot, a status.
• Exchange Rate Version: immutable (rate, valid-from) row. Requests point at one.
• Payout Attempt: one processor call and its outcome. Immutable.
• System Accounts: DEVEX_ESCROW holds in-flight Robux. ROBUX_BURN destroys it when a payout completes.

API or System Interface

POST /v1/devex-requests          Idempotency-Key: <key>   // unique per (developer + key) pair
{ "robux": 100000 }
→ 201 { requestId, PENDING, rateId, usdMinor }   // usdMinor = cents; rate + USD locked NOW
→ 422, body: { error: INSUFFICIENT_BALANCE | BELOW_MINIMUM | NOT_ELIGIBLE, reasons }
→ 409, body: { error: KEY_REUSED }   // same key, different body. same key + same body: replay the stored 201

GET    /v1/devex-requests?cursor=            // history
GET    /v1/devex-requests/:id                // status + every attempt
DELETE /v1/devex-requests/:id                // cancel; PENDING only; 409 after
GET    /v1/earnings?game=&granularity=day    // display; eventual; carries asOf

• The 201 already carries the locked rate and computed USD.
• Both are fixed inside the submission transaction. The amount can never drift after.

1) Developers should be able to see earnings in near real time

• Every purchase writes double-entry legs: minus player, plus developer share, plus platform cut.
• Legs sum to zero. The economy conserves by construction.
• Earnings displays: derived rollups off the ledger change stream (CDC: change data capture). Seconds stale, labeled asOf.
• The withdrawable balance: exact, read strongly only where it gates money, at submission.

2) Developers should be able to submit a DevEx request

• Replay check first: (developer, key) seen with matching body hash → return the stored answer, even if eligibility has since changed. Body differs → 409.
• Then the eligibility check (external call). Full result snapshotted.

Then ONE transaction:

1. Insert the request row. This is the idempotency anchor (the record a retry lands on).
2. Read the current rate version. Compute the USD. Store both on the request.
3. Debit developer, credit ESCROW. The no-overdraft guard is fused into the debit (one statement does check and change: deep dive 1).

If the guard matches zero rows (the branch of step 3):

• Re-read the account once to say WHY: frozen account or insufficient balance. One error code each.
• Mark REJECTED, commit, 422. Nothing was debited, so there is nothing to refund.
• The anchor survives for retries (unique index on developer + key makes it findable).

3) The rate is the one at submission

• A rate change is a NEW immutable row. Never an update.
• The request stores which rate row it used and the computed USD.
• Processing days later reads the request. It cannot see any other rate.
• The guarantee is a foreign key, not a convention.

4) Developers should be able to track status and history

• State machine: PENDING → PROCESSING → COMPLETED | PARTIAL | FAILED | ON_HOLD. Plus PENDING → CANCELLED.
• REJECTED is born terminal at submit (the guard said no; nothing escrowed). Lease expiry loops PROCESSING back to PENDING.
• Every processor call: one immutable attempt row.
• The history endpoint returns that table verbatim. Audit trail and UI at once.

1) How do we guarantee a developer can never over-withdraw?

• The race: two submissions, one 100K balance, 80K each. Both pass app-level checks.

UPDATE accounts SET balance = balance - :robux
WHERE id = :dev AND status = 'ACTIVE'
  AND balance - :robux >= 0

2) How is every payout decision auditable years later?

3) How do we finish in 5 business days when the processor fails, rejects, or half-pays?

• Volume check first: thousands/day. ONE worker is enough.
• The machinery below exists for crash-safety, not throughput. Saying that is the judgment signal.

4) How do we handle the scale asymmetry?

• The earnings ledger is the high-scale piece. Hundreds of writes/sec, sharded. It exists regardless of DevEx.
• The payout side is ONE Postgres and a worker. Keep it that way at 1000x volume.
• Component count is earned by the split, not by the payout path.
• The interviewer is checking: do you size the two sides separately, or reach for queues everywhere.

Final Design

• Closed double-entry Robux economy; DevEx is the one audited exit.
• Submission: one transaction, fused guard, frozen inputs (rate version, eligibility snapshot).
• Payout: leased worker, requestId as the processor idempotency key.
• Terminal states settle escrow as ledger transfers, atomic with the status change.
• Daily reconciliation + continuous escrow invariant keep it honest. CDC to WORM for compliance.

What is Expected at Each Level?