---
description: "Real-time feature conventions for {{PROJECT_NAME}}"
alwaysApply: true
---

# Real-time Features — {{PROJECT_NAME}}

## Connection management
- Always expose a `connectionState` stream — UI must show "offline" indicator
- Implement exponential backoff for reconnection (1s, 2s, 4s, 8s, max 60s)
- Cancel all subscriptions in `dispose()` — memory leaks are the #1 bug in real-time apps

## Offline-first strategy
- Cache last known state locally (Hive, Drift, or Isar)
- Show stale data with a "last updated" timestamp while reconnecting
- Queue mutations offline, replay on reconnect (use `connectivity_plus`)

## WebSocket / SSE
- Use `web_socket_channel` for WebSocket — never raw `dart:io` WebSocket
- Implement heartbeat/ping to detect dead connections
- Parse and validate all incoming messages — never trust raw server data

## UI indicators
- Show a persistent banner when offline: "You're offline — changes will sync when reconnected"
- Animate the banner away on reconnection — don't just hide it abruptly