SSE Frontend Implementation

[calebbourg]

Description

Implements Server-Sent Events (SSE) infrastructure for real-time updates across coaching sessions. Users now see changes automatically
when their coach or coachee creates/updates actions, agreements, or overarching goals - no manual refresh required.

The implementation leverages SWR cache invalidation for automatic UI updates, requires zero changes to existing components, and follows
established codebase patterns (Zustand, SWR, hooks, providers).

Changes

SSE Infrastructure:

• Add SSE event type definitions with discriminated unions matching backend serialization
• Create SSE connection state management with Zustand
• Implement native EventSource connection with automatic reconnection
• Add type-safe event handler hook with date transformation
• Integrate SSE cleanup with logout registry

Real-time Cache Invalidation:

• Implement SWR cache invalidation for all SSE events (actions, agreements, goals)
• Handle both string and array SWR cache keys
• Add force logout system event handler

Provider Integration:

• Add SSE provider to root application providers
• Use idiomatic Zustand pattern with useState for store initialization
• Fix unstable useEffect dependencies causing connection instability

Security & Code Quality:

• Remove sensitive data logging (user IDs, session IDs, content) from console
• Add comprehensive SSE implementation documentation
• Standardize OverarchingGoal date fields to DateTime

Testing Strategy

Manual Testing (Two Browser Sessions):

1. Log in as User A in one browser, User B in another (both in same coaching session)
2. User A creates an overarching goal → User B should see it appear automatically
3. User A updates an action → User B should see the update without refresh
4. User A creates an agreement → User B should see it immediately
5. Verify no sensitive data appears in browser console (F12 → Console)

Connection Stability:

1. Open browser DevTools → Network tab
2. Filter for EventSource connections
3. Verify single SSE connection remains open (not repeatedly closing/reconnecting)
4. Navigate between pages → connection should persist

Backend Logs:

• Should see "Sent [event_type] event to N user(s)"
• Should NOT see "channel closed" warnings during normal operation

Concerns

• SWR cache invalidation is intentionally broad (all caches with backendServiceURL) for simplicity - could be optimized to specific
  endpoints if performance becomes an issue
• SSE connections are ephemeral - offline users miss events (by design, they see fresh data on next page load)
• Using provider: () => new Map() in SWRConfig creates isolated cache per provider instance - ensures clean state but breaks cross-tab
  cache sharing

[jhodapp]

This is looking great. We came up with one suggestion yesterday to handle the following event scenarios:

• To have an event that's just a signal for the client to do something (e.g. simple action like force logout)
• To have an event that the client just consumes the payload passively (e.g. simple event with a text message like a notification)
• To have an event that the client uses to update a component that display an Entity type via the payload (e.g. a specific action was added to the list of actions, or a specific action was updated)

I think I got these right, but my memory was a little fuzzy. Hope your written notes from our sync call yesterday captured it and can more accurately reflect what we discussed.

And here are some more general things to consider about the design and as you implement with Claude:

Connection State During Auth Transitions

useEffect(() => {
if (!isLoggedIn) {
eventSourceRef.current?.close();
// ...
return;
}
// Create new connection...
}, [isLoggedIn, ...]);

Circular Import Risk

Looking at the imports:

use-sse-connection.ts
→ imports useSseConnectionStore from sse-provider.tsx

sse-provider.tsx
→ imports useSseConnection from use-sse-connection.ts

This is a circular dependency. It may work due to how the exports are structured, but:

• Could cause issues with hot module reloading
• Could cause issues with tree-shaking
• Makes the code harder to reason about

Possible fix: Extract useSseConnectionStore and context to a separate file (sse-connection-context.ts).

Scenarios to consider:

Scenario	What happens?
Page load while logged in	Connection created immediately? Or after hydration?
Login completes	Does isLoggedIn update synchronously trigger connection?
Token refresh	Does auth state flicker? Could cause disconnect/reconnect?
Logout while reconnecting	Race between cleanup and reconnection?

The logoutCleanupRegistry integration helps, but the interplay with React's effect timing deserves attention.

Missing Reconnection State

Phase 2 mentions Reconnecting as a state:

States: Disconnected, Connecting, Connected, Reconnecting, Error

But the actual enum only has four states:

export enum SseConnectionState {
  Disconnected = "Disconnected",
  Connecting = "Connecting",
  Connected = "Connected",
  Error = "Error",  // No Reconnecting!
}

Native EventSource auto-reconnects silently. How do you know if you're in a reconnection vs. first connection? The onerror fires, but then... does onopen fire again on successful reconnect?

If you want accurate UI states, this needs clarification.

[jhodapp]

Provider Dependency Chain

The nesting order in providers.tsx:

<AuthStoreProvider>           // 1. Auth state
  ...
    <SWRConfig>               // 2. SWR cache
      <SseProvider>           // 3. SSE (needs both auth AND SWR)
        {children}
      </SseProvider>
    </SWRConfig>
  ...
</AuthStoreProvider>

The concern: SseProvider calls useAuthStore() and useSWRConfig().

• Does useAuthStore work correctly when called from inside SseProvider during initial render?
• What's the initialization sequence when the app first loads?

It's worth tracing through the mount sequence mentally or with a quick prototype.

[calebbourg]

I added a note on this to the plan in b6c963a

I worked with Claude for a while on it and decided that I didn't want to touch auth logic as part of this effort as I was afraid that it would lead to regression and potentially just a headache of scope creep. Let me know what you think

[calebbourg]

@jhodapp I updated the plan to remove the circular dependency and add a reconnection state bc8cb85

[jhodapp]

Looking great Caleb, thanks. I've got a fresh round of suggestions and questions for you on this PR.

[jhodapp]

Please rename all Sse names instances across this entire changeset to SSE to follow other acronym letter capitalization patterns like SWRConfig.

[calebbourg]

Good call eb82c7d

[jhodapp]

I'm curious about the lifetime of the EventSource instance. I believe the useSseConnection hook gets used in the overarching goal component right now, and so as long as this component is still rendered on the coaching session page and isLoggedIn doesn't change to false, there should be a single instance of this EventSource then for this component. Am I understanding this correctly?

[jhodapp]

I'd love to see some integration tests that can validate the lifetime correctness of these things, like the lifetime of a single EventSource instance and its events like onopen and onerror.

Especially before we start using this all over the place since we could run into more obscure and tricky bugs to trace down if we don't ensure this is very solid in this single simple use case with overarching goals.

[calebbourg]

Yes you're correct except that the connection is maintained at the root layer so it persists across page navigation, re-renders, etc.

[calebbourg]

Working on adding tests for this now!

[calebbourg]

Tests added 66131d0

[jhodapp]

@calebbourg Ok great, and you're using a reference to get at the same instance with the return on line 64, so it should be passing around the location of this one instance. Perfect.

[jhodapp]

The tests look great.

[jhodapp]

So the purpose of this is to create a single global SSE connection state manager instance that gets shared? And this is in-memory only, correct? I don't see any persistence of the store to local storage.

[jhodapp]

Looks like you were anticipating adding some tests but didn't quite get to it?

[jhodapp]

Not that these events aren't obvious what they do already, but can you set a pattern of documenting each event type with a code comment above each explaining its purpose and an example of when it gets used? Claude should be able to write these comments very well.

[jhodapp]

I'd like to see SWR cache invalidation sharpened up. When we currently receive an SSE event that causes an invalidation, every component on the coaching session page re-renders and this is kind of a jarring user experience. I asked Claude about this and here's what it recommends:

Root Cause: Overly Broad Cache Invalidation

The problem is in use-sse-cache-invalidation.ts (lines 12-24).

When any SSE event (including overarching_goal_updated) is received, it invalidates ALL SWR caches that contain the backend URL. This triggers refetches for:

│              Hook              │          Cache Key          │         Re-renders          │
├────────────────────────────────┼─────────────────────────────┼─────────────────────────────┤
│ useCurrentCoachingSession      │ /coaching_sessions/...      │ Page header, title          │
├────────────────────────────────┼─────────────────────────────┼─────────────────────────────┤
│ useCurrentCoachingRelationship │ /coaching_relationships/... │ Session selector, title     │
├────────────────────────────────┼─────────────────────────────┼─────────────────────────────┤
│ useOverarchingGoalBySession    │ /overarching_goals?...      │ Goal component ✓ (intended) │
├────────────────────────────────┼─────────────────────────────┼─────────────────────────────┤
│ Actions hooks                  │ /actions?...                │ Actions tab                 │
├────────────────────────────────┼─────────────────────────────┼─────────────────────────────┤
│ Agreements hooks               │ /agreements?...             │ Agreements tab              │
├────────────────────────────────┼─────────────────────────────┼─────────────────────────────┤
│ Notes hooks                    │ /notes/...                  │ Notes tab                   │
└────────────────────────────────┴─────────────────────────────┴─────────────────────────────┘

All these components re-render even though only the overarching goal changed.

A Way to Fix This Issue

Scope cache invalidation to only the relevant endpoint:

useSseEventHandler(eventSource, 'overarching_goal_updated', () => {
  mutate(
    (key) => {
      const keyStr = typeof key === 'string' ? key : key?.[0];
      return keyStr?.includes('/overarching_goals') ?? false;
    },
    undefined,
    { revalidate: true }
  );
  console.log('[SSE] Revalidated overarching_goals cache');
});

[calebbourg]

yeah I totally agree. Excellent suggestion.

d36a443

[jhodapp]

@calebbourg Looks good, one issue right now is that I have to refocus the window before the pending OverarchingGoal update renders. Here's a fix that I tried locally that works and according to Claude, still maintains a single instance of eventSource.

In use-sse-connection.ts, the EventSource is stored in a useRef, but refs don't trigger re-renders when they change. Here's the problem flow:

1. SSEConnectionManager renders with isLoggedIn = true
2. useSSEConnection returns eventSourceRef.current (which is null at render time)
3. useSSECacheInvalidation(null) receives null, so all the useSSEEventHandler effects early-return
4. The effect creates the EventSource and sets eventSourceRef.current = source
5. But no re-render occurs because ref changes don't trigger re-renders
6. The event handlers are never attached to the actual EventSource

The fix is to use useState instead of useRef for the EventSource:

⏺ Update(src/lib/hooks/use-sse-connection.ts)
⎿  Added 8 lines, removed 6 lines

       1  "use client";
       2
       3 -import { useEffect, useRef } from 'react';
       3 +import { useEffect, useState } from 'react';
       4  import { siteConfig } from '@/site.config';
       5  import { useSSEConnectionStore } from '@/lib/contexts/sse-connection-context';
       6  import { logoutCleanupRegistry } from '@/lib/hooks/logout-cleanup-registry';
       7
       8  export function useSSEConnection(isLoggedIn: boolean) {
       9 -  const eventSourceRef = useRef<EventSource | null>(null);
       9 +  const [eventSource, setEventSource] = useState<EventSource | null>(null);
      10
      11    // Get store instance directly - Zustand actions are stable and don't need to be in dependencies
      12    const store = useSSEConnectionStore((state) => state);
      13
      14    useEffect(() => {
      15      if (!isLoggedIn) {
      16 -      eventSourceRef.current?.close();
      17 -      eventSourceRef.current = null;
      16 +      setEventSource((prev) => {
      17 +        prev?.close();
      18 +        return null;
      19 +      });
      20        store.setDisconnected();
      21        return;
      22      }
     ...
      47        }
      48      };
      49
      48 -    eventSourceRef.current = source;
      50 +    setEventSource(source);
      51
      52      const unregisterCleanup = logoutCleanupRegistry.register(() => {
      53        console.log('[SSE] Cleaning up connection on logout');
     ...
      63      // eslint-disable-next-line react-hooks/exhaustive-deps
      64    }, [isLoggedIn]);
      65
      64 -  return eventSourceRef.current;
      66 +  return eventSource;
      67  }

⏺ Now when setEventSource(source) is called, it triggers a re-render of SSEConnectionManager, which passes the actual EventSource to useSSECacheInvalidation, and the event handlers get attached properly.

[calebbourg]

Updated to use your suggestion thank you! 4745cc9

[jhodapp]

One more change to make so that changes to an OverarchingGoal in one browser window automatically causes a re-render in the other without first having to refocus the window.

Approving so you can merge and land after the fix is applied. Then feel free to deploy when you're ready.