💳 OneBalance Processing

📖 Overview

The OneBalance module handles balance reload and charge processing for the unified balance system.

Environment Flags:

• QM_ONEBALANCE_BALANCE_RELOAD=true - Balance reload via cron
• QM_ONEBALANCE_BALANCE_RELOAD_STREAM=true - Balance reload via change streams
• QM_ONEBALANCE_BALANCE_CHARGE=true - Balance charge via cron
• QM_ONEBALANCE_BALANCE_CHARGE_STREAM=true - Balance charge via change streams

Source Location: queue-manager/crons/onebalance/ and queue-manager/streams/onebalance/

🗄️ Collections Used

onebalance-account

• Operations: Read/Update
• Model: shared/models/onebalance-account.js
• Usage: OneBalance account records

onebalance-transaction

• Operations: Create
• Model: shared/models/onebalance-transaction.js
• Usage: Transaction history

onebalance-reload-request

• Operations: Read/Update
• Model: shared/models/onebalance-reload-request.js
• Usage: Balance reload requests

onebalance-charge-request

• Operations: Read/Update
• Model: shared/models/onebalance-charge-request.js
• Usage: Balance charge requests

🔧 Jobs in This Module

Balance Reload (Cron)

Cron Schedule: Every 30 seconds

Key Features:

• Request Processing: Processes pending reload requests
• Payment Validation: Validates payment methods
• Balance Update: Updates account balances
• Transaction Recording: Creates transaction records
• Stripe Integration: Processes payments via Stripe

Balance Reload (Change Stream)

Trigger: MongoDB change stream on reload requests

Key Features:

• Real-Time Processing: Instant processing on new requests
• Event-Driven: Responds to database changes
• High Priority: Faster than cron-based processing

Balance Charge (Cron)

Cron Schedule: Every 30 seconds

Key Features:

• Usage Deduction: Deducts usage from balances
• Threshold Monitoring: Tracks low balance warnings
• Auto-Reload: Triggers auto-reload if configured
• Service Usage: Records service-specific charges

Balance Charge (Change Stream)

Trigger: MongoDB change stream on charge requests

Key Features:

• Real-Time Charging: Instant charge processing
• Usage Tracking: Real-time usage monitoring
• Immediate Response: Quick balance updates

🔄 Processing Patterns

Cron-Based Processing

• Polling Frequency: Every 30 seconds
• Batch Processing: Processes multiple requests per run
• Fallback Method: Ensures no request is missed

Change Stream Processing

• Event-Driven: Triggered by database changes
• Lower Latency: Faster than polling
• Real-Time: Immediate processing
• Requires: MongoDB replica set

---

Module Status: Active
Execution Pattern: Dual (Cron + Change Streams)
Last Updated: 2025-10-10