Maintenance & Cron Jobs

Relevant source files

The following files were used as context for generating this wiki page:

• convex/crons.ts
• convex/cleanup.ts
• convex/_generated/api.d.ts
• src/state/ConvexSync.tsx
• convex/userPreferences.ts
• AGENTS.md

The Dreamcats maintenance system ensures the health and responsiveness of the game backend by managing room lifecycles and player states. It utilizes Convex's scheduling capabilities to automate database cleanup and handle stalled game states caused by inactive players.

Scheduling Architecture

The project uses a centralized cron definition to manage automated tasks. These tasks are registered using the cronJobs() builder and reference internal backend functions.

Job Definitions

Job Name	Frequency	Target Function	Purpose
cleanup old rooms	Hourly (minute 0)	internal.cleanup.cleanupOldRooms	Garbage collection for abandoned or stale game rooms.
auto-advance AFK	Every 10 seconds	internal.cleanup.autoAdvanceAFKPeeking	Prevents game stalls by forcing turn progression for inactive players.

Sources: convex/crons.ts:5-23, convex/_generated/api.d.ts:16

The following diagram illustrates how the cron scheduler triggers internal maintenance functions:

Room & State Cleanup

Maintenance logic is primarily concerned with data retention and game flow integrity.

Room Lifecycle Management

The system periodically identifies and removes "old" or "abandoned" rooms to prevent database bloat. This is critical for maintaining performance in a real-time multiplayer environment where many rooms may be created but never finished.

Sources: convex/crons.ts:8-12, convex/cleanup.ts

AFK Mitigation

A high-frequency check (every 10 seconds) is performed to catch stalled "peeking" phases. If a player is deemed AFK (Away From Keyboard) during this initial game phase, the system triggers an automatic advancement to ensure other players are not blocked.

Sources: convex/crons.ts:18-21, convex/cleanup.ts

Client-Side Maintenance & Sync

While the server handles automated cleanup, the client maintains connectivity and session health through heartbeat mechanisms and local state synchronization.

Presence Heartbeat

The client transmits a heartbeat to the server every 10 seconds while in an online game. This updates the lastSeenAt timestamp for the player, which the server uses to determine connectivity status.

Session Persistence

To handle accidental refreshes or network drops, the system maintains session data across storage layers:

• Local/Session Storage: Stores playerId, roomId, and playerName to allow "silent rejoins".
• Database Preferences: The userPreferences module stores active session data including activeRoomId and activePlayerId for authenticated users.

Sources: src/state/ConvexSync.tsx:43-52, convex/userPreferences.ts:251-274

Data Retention Parameters

Maintenance functions interact with several key data entities to manage the system state.

Entity	Maintenance Action	Relevant Module
rooms	Hourly cleanup of stale entries	cleanup.ts
userPreferences	Update/Clear active session data	userPreferences.ts
presence	Continuous heartbeat updates	presence.ts
gameState	Forced phase advancement for AFK players	cleanup.ts

Sources: convex/crons.ts:11, convex/userPreferences.ts:276-297, src/state/ConvexSync.tsx:96-103

Summary

The maintenance system in Dreamcats combines high-frequency AFK checks with hourly database cleanup to provide a stable gaming environment. By offloading room garbage collection and player presence monitoring to automated cron jobs and heartbeats, the architecture ensures that the real-time state remains performant and that abandoned sessions do not block active gameplay.