Skip to content

docs: add conceptual documentation for presence and heartbeat services - #489

Open
Samuel-21-eng wants to merge 1 commit into
codebestia:mainfrom
Samuel-21-eng:docs/presence-heartbeat-concepts
Open

docs: add conceptual documentation for presence and heartbeat services#489
Samuel-21-eng wants to merge 1 commit into
codebestia:mainfrom
Samuel-21-eng:docs/presence-heartbeat-concepts

Conversation

@Samuel-21-eng

Copy link
Copy Markdown

The new documentation apps/backend/docs/concepts-presence-heartbeat.md provides a comprehensive overview of the
backend's presence and heartbeat mechanisms:

  • Redis Key Architecture: Detailed breakdown of the Redis data structures (Hash, Set) used to track user presence,
    device sessions, and socket mappings, including their purpose and TTL logic.
  • Heartbeat Contract: Defined the operational parameters, specifically the 90-second heartbeat timeout for
    connection liveness and the 30-second throttle for database updates to balance precision with performance.
  • Multi-device & Aggregation Logic: Explained how the system aggregates multiple active devices to determine a
    user's overall "online" status and the conditions for broadcasting state transitions (user_offline).
  • System Reconciliation: Documented the gateway boot reconciliation process to ensure real-time room memberships
    remain consistent after service restarts.

This document serves as the canonical reference for understanding how client connections are maintained, timed out,
and synchronized across the distributed backend architecture.

closes #447

@drips-wave

drips-wave Bot commented Jul 29, 2026

Copy link
Copy Markdown

@Samuel-21-eng Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@codebestia

Copy link
Copy Markdown
Owner

Hello @Samuel-21-eng
Please remove the package-lock.json diffs from your PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Concepts docs: Presence, heartbeat & connection liveness

2 participants