Background Jobs & Cron
Relevant source files
The following files were used as context for generating this wiki page:
The SoulSeer platform utilizes background jobs and cron-style scheduling to manage time-sensitive spiritual reading sessions, handle financial transactions, and maintain platform health. These background processes ensure that the per-minute billing model is enforced and that sessions do not remain orphaned due to connectivity issues.
The system is architected to handle both server-side scheduled tasks and client-side heartbeats to maintain an accurate state of active readings. This includes specialized logic for "on-demand" reading sessions where real-time monitoring of user balances and connection status is critical.
Sources: server/src/index.ts:133, client/src/pages/reading/ReadingSessionPage.tsx:556-562
Core Billing Service
The billingService is a primary component of the background processing architecture. It is initialized upon server startup and is responsible for managing the continuous financial logic of the platform.
Lifecycle Management
The billing service is integrated into the main application lifecycle, starting when the HTTP server begins listening and closing gracefully during a SIGTERM or SIGINT signal.
The service ensures that active readings are monitored for insufficient balances and that funds are correctly allocated between readers and the platform.
Sources: server/src/index.ts:133-160
Reading Session Monitoring
To prevent "orphaned" sessions and ensure accurate billing, the platform employs a heartbeat mechanism and a grace-period sweeper.
Heartbeat Mechanism
Active reading sessions send a heartbeat every 30 seconds from the client to the server. This heartbeat informs the background services that the session is still live and should not be terminated by automated cleaners.
Session Termination Events
Background jobs emit WebSocket events to notify clients when a session is terminated by an automated process.
| Event | Trigger | Client Impact |
|---|---|---|
reading:ended | Triggered by insufficient balance or grace period expiration. | Renders post-session summary and provides reason (e.g., "insufficient_balance"). |
reading:insufficient_balance | Triggered when user funds drop below a threshold. | Displays a warning that the session will end shortly. |
reading:partner_disconnected | Triggered when the other party loses connectivity. | Starts a 2-minute countdown for reconnection before the job terminates the session. |
Sources: client/src/pages/reading/ReadingSessionPage.tsx:571-621
Cron Routes and Admin Tasks
The platform exposes dedicated routes for maintenance tasks that are typically triggered by external cron schedulers or administrative actions.
Automated Sweepers
The /api/cron route group handles scheduled maintenance. While the specific internal logic of these routes is abstracted in cron.ts, they typically involve:
- Cleaning up expired sessions.
- Resolving stale forum flags.
- Checking for pending payouts.
Sources: server/src/index.ts:121, server/src/routes/admin.ts:316-324
Administrative Background Controls
Admins can manually trigger background-like tasks via the Admin Dashboard, such as balance adjustments or initiating reader payouts.
| Administrative Action | Backend Logic | Impact |
|---|---|---|
| Balance Adjustment | POST /api/admin/balance-adjust | Updates users.balance and records a transaction log entry. |
| Reader Payout | POST /api/admin/payouts/:id | Triggers a Stripe Connect transfer and zeroes out the user's internal balance. |
| Refund | POST /api/admin/readings/:id/refund | Credits the client balance and updates reading paymentStatus to refunded. |
Sources: server/src/routes/admin.ts:255-290, server/src/routes/admin.ts:333-380
Production Environment Configuration
In a production environment (such as Fly.io), the server is configured to serve both API routes and static files, while maintaining the same rate-limiting and security middleware for background routes.
Sources: server/src/production.ts:10-45
Conclusion
Background Jobs & Cron in SoulSeer act as a safeguard for the platform's revenue model. By combining server-side scheduled services (billingService) with client-side heartbeats and administrative overrides, the system maintains high data integrity for reading sessions and financial ledgers.