Sse initial implementation

[calebbourg]

Description

This PR implements the foundational infrastructure for Server-Sent Events (SSE) to enable real-time, one-way communication from
the backend to authenticated users. This establishes the core architecture needed for future real-time features like action
notifications, coaching session updates, and system announcements.

GitHub Issue: [Closes|Fixes|Resolves] #your GitHub issue number here

Changes

• New sse crate: Standalone crate with generic types (String IDs, JSON payloads) to avoid circular dependencies
  • ConnectionRegistry: Dual-index architecture using DashMap for O(1) concurrent lookups by connection_id and user_id
  • Manager: High-level API for connection lifecycle and message routing
  • Message types: Event enum with action, agreement, goal, and system event variants
  • MessageScope: User-targeted and broadcast message delivery
• SSE HTTP endpoint (web/src/sse/handler.rs): GET /sse endpoint for establishing long-lived SSE connections
  • Async streaming using async_stream::stream! and Tokio channels
  • Automatic connection cleanup on disconnect
  • One connection per authenticated user, persisting across page navigation
• AppState integration: Added sse_manager: Arc<sse::Manager> to service layer's AppState
  • Enables controllers to send SSE events via app_state.sse_manager.send_message()
  • Manager initialized at application startup in main.rs and seed_db.rs
• Infrastructure configuration:
  • Nginx configuration for /api/sse endpoint (24h timeout, no buffering, chunked encoding)
  • Docker Compose warning about single-instance limitation (in-memory connection tracking)
• Testing tool (sse-test-client): CLI tool for integration testing SSE functionality
  • Connection stability testing
  • Force logout scenario
  • Multiple test scenarios with varying permission requirements
• Architecture documentation updates: Updated crate dependency graph, system architecture diagram, and network flow diagram
  to reflect SSE components

Testing Strategy

1. Manual testing with sse-test-client:

   cd sse-test-client
   cargo run
   # Select "Connection Test" to verify basic SSE connectivity

2. Unit tests: Updated auth middleware tests to include SSE manager initialization
3. Integration testing: Use sse-test-client scenarios to verify:
   - Connection establishment and stability
   - Multiple concurrent user connections
   - Graceful connection cleanup on disconnect

Concerns

• Single-instance limitation: SSE connections are tracked in-memory using DashMap, which means the application cannot scale
  horizontally without implementing Redis Pub/Sub for cross-instance event distribution
  • Warning added to docker-compose.yaml
  • Symptom if violated: events randomly fail to deliver with multiple replicas
• No event persistence: All SSE events are ephemeral - offline users miss events and see fresh data on next page load
• No message delivery guarantees: If channel send fails, events are dropped (logged but not retried)
• Generic types in SSE crate: Using String for IDs and serde_json::Value for payloads to avoid circular dependencies - type
  safety enforced at web layer boundaries