feat(perf): implement performance optimizations for session handling

- Introduced a new configuration file `config.yaml` for specifying project context and artifact rules.
- Added `.openspec.yaml` files for tracking changes related to performance improvements.
- Created design documents outlining the context, goals, decisions, and migration plans for optimizing session performance.
- Proposed changes include batching database queries, debouncing event refreshes, purging old events, and implementing loading states for better user experience.
- Added tasks and specifications to ensure proper implementation and validation of the new features.

These enhancements aim to improve the scalability and responsiveness of the application during collaborative sessions.

openspec/changes/perf-realtime-scale/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-09

openspec/changes/perf-realtime-scale/design.md

@@ -0,0 +1,65 @@
+## Context
+
+Chaque route `/api/*/subscribe` crée un `setInterval` à 1s qui poll la DB pour les événements. Si 10 utilisateurs ont le même workshop ouvert, c'est 10 requêtes/seconde sur la même table. Le pattern weather utilise déjà une `Map` de subscribers in-process pour broadcaster les événements sans re-poll, mais ce pattern n'est pas généralisé. Les Server Actions appellent `revalidatePath('/sessions')` qui invalide tous les sous-segments, forçant Next.js à re-render des pages entières même pour une mutation mineure.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Réduire le nombre de requêtes DB de polling proportionnellement au nombre de clients connectés
+- Fournir un module de broadcast réutilisable pour tous les workshops
+- Réduire la surface d'invalidation du cache Next.js avec des tags granulaires
+- Limiter le volume de données chargées sur la page sessions avec pagination
+
+**Non-Goals:**
+- Passer à WebSockets ou un serveur temps-réel externe (Redis, Pusher)
+- Modifier le modèle de données Prisma pour les événements
+- Implémenter du SSE multi-process / multi-instance (déploiement standalone single-process)
+
+## Decisions
+
+### 1. Module broadcast.ts : Map<sessionId, Set<subscriber>>
+
+**Décision** : Créer `src/lib/broadcast.ts` qui expose :
+- `subscribe(sessionId, callback)` → retourne `unsubscribe()`
+- `broadcast(sessionId, event)` → notifie tous les subscribers
+
+Les routes SSE s'abonnent au lieu de poller. Les Server Actions appellent `broadcast()` après mutation.
+
+**Alternatives** : EventEmitter Node.js → rejeté car moins typé ; BroadcastChannel → rejeté car limité à same-origin workers, pas adapté aux route handlers Next.js.
+
+### 2. Polling de fallback maintenu mais mutualisé
+
+**Décision** : Garder un seul polling par session active (le premier subscriber démarre l'interval, le dernier le stoppe). Le broadcast natif est prioritaire (appelé depuis Server Actions), le polling est le fallback pour les clients qui rejoignent en cours de route.
+
+### 3. revalidateTag avec convention de nommage
+
+**Décision** : Convention de tags :
+- `session:<id>` — pour une session spécifique
+- `sessions-list:<userId>` — pour la liste des sessions d'un user
+- `workshop:<type>` — pour tout le workshop
+
+Chaque query Prisma dans les services est wrappée avec `unstable_cache` ou utilise `cacheTag` (Next.js 15+).
+
+**Alternatives** : Garder `revalidatePath` mais avec des paths plus précis → moins efficace que les tags.
+
+### 4. Pagination cursor-based sur sessions page
+
+**Décision** : Pagination par cursor (basée sur `createdAt` DESC) plutôt qu'offset, pour la stabilité des listes en insertion fréquente. Taille de page initiale : 20 sessions par type de workshop. UI : bouton "Charger plus" (pas de pagination numérotée).
+
+**Alternatives** : Virtual scroll → plus complexe, dépendance JS côté client ; offset pagination → instable si nouvelles sessions insérées entre deux pages.
+
+## Risks / Trade-offs
+
+- **Broadcast in-process** → ne fonctionne qu'en déploiement single-process. Acceptable pour le cas d'usage actuel (standalone Next.js). Documenter la limitation.
+- **unstable_cache** → API marquée unstable dans Next.js, peut changer. Mitigation : isoler dans les services, pas dans les composants.
+- **Pagination** → change l'UX de la page sessions (actuellement tout visible). Mitigation : conserver le total affiché et un indicateur "X sur Y".
+
+## Migration Plan
+
+1. Créer `src/lib/broadcast.ts` sans toucher aux routes existantes
+2. Migrer les routes SSE une par une (commencer par `weather` qui a déjà le pattern)
+3. Mettre à jour les Server Actions pour appeler `broadcast()` + `revalidateTag()`
+4. Ajouter `cacheTag` aux queries services
+5. Ajouter pagination sur sessions page en dernier (changement UI visible)
+
+Rollback : chaque étape est indépendante — revert par feature.

openspec/changes/perf-realtime-scale/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+La couche temps-réel actuelle (SSE + polling DB à 1s) multiplie les connexions et les requêtes dès que plusieurs utilisateurs collaborent. Chaque onglet ouvert sur une session déclenche son propre polling, et les Server Actions invalident des segments de route entiers avec `revalidatePath`. Ces problèmes de scalabilité deviennent visibles dès 5-10 utilisateurs simultanés.
+
+## What Changes
+
+- **Polling SSE partagé** : un seul interval actif par session côté serveur, partagé entre tous les clients connectés à cette session
+- **Broadcast unifié** : généraliser le pattern de broadcast in-process (déjà présent dans `weather`) à tous les workshops via un module `src/lib/broadcast.ts`
+- **`revalidateTag` granulaire** : remplacer `revalidatePath` dans tous les Server Actions par des tags ciblés (`session:<id>`, `sessions-list`, etc.)
+- **Pagination sessions page** : limiter le chargement initial à N sessions par type avec pagination ou chargement progressif
+
+## Capabilities
+
+### New Capabilities
+
+- `sse-shared-polling`: Polling SSE mutualisé par session (un seul interval par session active)
+- `unified-broadcast`: Module de broadcast in-process réutilisable par tous les workshops
+
+### Modified Capabilities
+
+- `sessions-list`: Ajout de pagination/limite sur le chargement des sessions
+
+## Impact
+
+- `src/app/api/*/subscribe/route.ts` — refactoring du polling vers le module broadcast partagé
+- `src/lib/broadcast.ts` — nouveau module (Map de sessions actives + subscribers)
+- `src/actions/*.ts` — remplacement de `revalidatePath` par `revalidateTag` + `unstable_cache`
+- `src/app/sessions/page.tsx` — ajout pagination
+- `src/services/` — ajout de `cache` tags sur les requêtes Prisma fréquentes

openspec/changes/perf-realtime-scale/specs/sessions-list/spec.md

@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Paginated sessions list
+The sessions page SHALL load sessions in pages rather than fetching all sessions at once, with a default page size of 20 per workshop type.
+
+#### Scenario: Initial load shows first page
+- **WHEN** a user visits the sessions page
+- **THEN** at most 20 sessions per workshop type SHALL be loaded
+- **THEN** a total count SHALL be displayed (e.g., "Showing 20 of 47")
+
+#### Scenario: Load more sessions on demand
+- **WHEN** there are more sessions beyond the current page
+- **THEN** a "Charger plus" button SHALL be displayed
+- **WHEN** the user clicks "Charger plus"
+- **THEN** the next page of sessions SHALL be appended to the list

openspec/changes/perf-realtime-scale/specs/sse-shared-polling/spec.md

@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: Single polling interval per active session
+The SSE infrastructure SHALL maintain at most one active DB polling interval per session, regardless of the number of connected clients.
+
+#### Scenario: First client connects starts polling
+- **WHEN** the first client connects to a session's SSE endpoint
+- **THEN** a single polling interval SHALL be started for that session
+
+#### Scenario: Additional clients share existing polling
+- **WHEN** a second or subsequent client connects to the same session's SSE endpoint
+- **THEN** no additional polling interval SHALL be created
+- **THEN** the new client SHALL receive events from the shared poll
+
+#### Scenario: Last client disconnect stops polling
+- **WHEN** all clients disconnect from a session's SSE endpoint
+- **THEN** the polling interval for that session SHALL be stopped and cleaned up

openspec/changes/perf-realtime-scale/specs/unified-broadcast/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Centralized broadcast module
+The system SHALL provide a centralized `src/lib/broadcast.ts` module used by all workshop SSE routes to push events to connected clients.
+
+#### Scenario: Server Action triggers broadcast
+- **WHEN** a Server Action mutates session data and calls `broadcast(sessionId, event)`
+- **THEN** all clients subscribed to that session SHALL receive the event immediately without waiting for the next poll cycle
+
+#### Scenario: Broadcast module subscribe/unsubscribe
+- **WHEN** an SSE route calls `subscribe(sessionId, callback)`
+- **THEN** the callback SHALL be invoked on every subsequent `broadcast(sessionId, ...)` call
+- **WHEN** the returned `unsubscribe()` function is called
+- **THEN** the callback SHALL no longer receive events
+
+### Requirement: Granular cache invalidation via revalidateTag
+Server Actions SHALL use `revalidateTag` with session-scoped tags instead of `revalidatePath` to limit cache invalidation scope.
+
+#### Scenario: Session mutation invalidates only that session's cache
+- **WHEN** a Server Action mutates a specific session (e.g., adds an item)
+- **THEN** only the cache tagged `session:<id>` SHALL be invalidated
+- **THEN** other sessions' cached data SHALL NOT be invalidated

openspec/changes/perf-realtime-scale/tasks.md

@@ -0,0 +1,36 @@
+## 1. Module broadcast.ts
+
+- [ ] 1.1 Créer `src/lib/broadcast.ts` avec une `Map<string, Set<(event: unknown) => void>>` et les fonctions `subscribe(sessionId, cb)` et `broadcast(sessionId, event)`
+- [ ] 1.2 Ajouter la logique de polling mutualisé : `startPolling(sessionId)` / `stopPolling(sessionId)` avec compteur de subscribers
+- [ ] 1.3 Écrire un test manuel : ouvrir 2 onglets sur la même session, vérifier qu'un seul interval tourne (log côté serveur)
+
+## 2. Migration des routes SSE
+
+- [ ] 2.1 Lire toutes les routes `src/app/api/*/subscribe/route.ts` pour inventorier le pattern actuel
+- [ ] 2.2 Migrer la route weather en premier (elle a déjà un pattern partiel) pour valider l'approche
+- [ ] 2.3 Migrer les routes swot, motivators, year-review, weekly-checkin une par une
+- [ ] 2.4 Vérifier que le cleanup SSE (abort signal) appelle bien `unsubscribe()` dans chaque route migrée
+
+## 3. revalidateTag dans les Server Actions
+
+- [ ] 3.1 Définir la convention de tags dans `src/lib/cache-tags.ts` (ex: `session(id)`, `sessionsList(userId)`)
+- [ ] 3.2 Ajouter `cacheTag` / `unstable_cache` aux queries de services correspondantes
+- [ ] 3.3 Remplacer `revalidatePath` par `revalidateTag` dans `src/actions/swot.ts`
+- [ ] 3.4 Remplacer `revalidatePath` par `revalidateTag` dans `src/actions/motivators.ts`
+- [ ] 3.5 Remplacer `revalidatePath` par `revalidateTag` dans `src/actions/year-review.ts`
+- [ ] 3.6 Remplacer `revalidatePath` par `revalidateTag` dans `src/actions/weekly-checkin.ts`
+- [ ] 3.7 Remplacer `revalidatePath` par `revalidateTag` dans `src/actions/weather.ts`
+- [ ] 3.8 Vérifier que les mutations se reflètent correctement dans l'UI après revalidation
+
+## 4. Broadcast depuis les Server Actions
+
+- [ ] 4.1 Ajouter l'appel `broadcast(sessionId, { type: 'update' })` dans chaque Server Action de mutation (après revalidateTag)
+- [ ] 4.2 Vérifier que les mises à jour collaboratives fonctionnent (ouvrir 2 onglets, muter depuis l'un, voir la mise à jour dans l'autre)
+
+## 5. Pagination sessions page
+
+- [ ] 5.1 Modifier les queries dans `src/services/` pour accepter `cursor` et `limit` (défaut: 20)
+- [ ] 5.2 Mettre à jour `src/app/sessions/page.tsx` pour charger la première page + afficher le total
+- [ ] 5.3 Créer un Server Action `loadMoreSessions(type, cursor)` pour la pagination
+- [ ] 5.4 Ajouter le bouton "Charger plus" avec état loading dans le composant sessions list
+- [ ] 5.5 Vérifier l'affichage "X sur Y sessions" pour chaque type de workshop