SSE initial implementation

Cargo.toml

@@ -6,12 +6,16 @@ edition = "2021"
 default-run = "refactor_platform_rs"
 
 [workspace]
-members = [".", "entity_api", "entity", "migration", "service", "web", "domain"]
+members = [".", "entity_api", "entity", "migration", "service", "web", "domain", "sse", "testing-tools"]
+# Exclude testing-tools from default builds - it's a development/testing tool only
+# and should not be built or deployed in production environments
+default-members = [".", "entity_api", "entity", "migration", "service", "web", "domain", "sse"]
 
 [dependencies]
 service = { path = "service" }
 entity_api = { path = "entity_api" }
 web = { path = "web" }
+sse = { path = "sse" }
 
 clap = { version = "4.5.20", features = ["cargo", "derive", "env"] }
 log = "0.4.22"

README.md

@@ -178,6 +178,8 @@ _For additional commands, database utilities, and debugging tips, check the [Con
 
 `service` - CLI flags, environment variables, config handling and backend daemon setup
 
+`sse` - Server-Sent Events infrastructure for real-time notifications. In-memory connection management (single-instance only)
+
 `src` - contains a main function that initializes logging and calls all sub-services
 
 `web` - API endpoint definition, routing, handling of request/responses, controllers

docker-compose.yaml

@@ -54,6 +54,23 @@ services:
     networks:
       - backend_network
 
+  ######################################################
+  # CRITICAL: SSE Connection Management Limitation
+  #
+  # The rust-app service MUST run as a single instance (replicas: 1)
+  # because SSE connections are tracked in-memory using DashMap.
+  #
+  # ⚠️  DO NOT SCALE HORIZONTALLY WITHOUT REDIS PUB/SUB ⚠️
+  #
+  # If you need to scale beyond 1 replica:
+  # 1. Add Redis service to docker-compose.yaml
+  # 2. Update SseManager to use Redis Pub/Sub
+  # 3. See docs/implementation-plans/sse-communication.md
+  #    "Multi-Instance Architecture" section
+  #
+  # Symptom if misconfigured: SSE events randomly fail
+  # (~50% with 2 replicas, ~67% with 3 replicas, etc.)
+  ######################################################
   rust-app:
     image: ${BACKEND_IMAGE_NAME}
     build:

docs/architecture/crate_dependency_graph.md

@@ -1,10 +1,14 @@
 
 This diagram represents the dependency structure of the crates in this project. Each arrow indicates a dependency relationship between the crates. For example, the `web` crate depends on both the `domain` and `service` crates, while the `entity_api` crate depends on the `entity` and `service` crates.
 
+The `sse` crate is standalone with no domain dependencies, using generic types to avoid circular dependencies.
+
 ```mermaid
 graph TD;
     web-->domain;
     web-->service;
+    web-->sse;
+    service-->sse;
     domain-->entity_api;
     entity_api-->entity;
     entity_api-->service;

docs/architecture/network_flow_diagram.md

@@ -38,6 +38,7 @@ flowchart TB
 4. **API Forwarding**: NextJS forwards API calls to Axum backend on port 4000
 5. **Backend Processing**: Axum backend handles API endpoints like `/api/login` with secure caching
 6. **Database Operations**: Backend connects to Digital Ocean Managed PostgreSQL
+7. **SSE Connections**: Long-lived `/api/sse` connections for real-time events (24h timeout, no buffering)
 
 ## Infrastructure Notes
 
@@ -48,4 +49,6 @@ flowchart TB
   - Axum: Internal port 4000
 - **Managed PostgreSQL**: Separate Digital Ocean managed database service, accessed over the internet with SSL
 - **SSL/TLS**: HTTPS encryption from client to Nginx using Let's Encrypt certificates managed by `certbot`, then unencrypted internal traffic within the container network
-- **Database Connection**: Axum connects to managed PostgreSQL over SSL outside the container network
+- **Database Connection**: Axum connects to managed PostgreSQL over SSL outside the container network
+- **SSE Configuration**: Nginx configured for long-lived connections (24h timeout, proxy buffering disabled) at `/api/sse` endpoint
+- **Scaling Limitation**: SSE uses in-memory connection tracking - **single backend instance only** until Redis pub/sub is implemented

docs/architecture/system_architecture_diagram.md

@@ -32,6 +32,10 @@ The Refactor Platform is a coaching management system built with Rust (Axum back
 - **Migration**: Database schema versioning and migrations
 - **Database**: PostgreSQL with `refactor_platform` schema
 
+### Real-Time Communication
+- **SSE (Server-Sent Events)**: Unidirectional push notifications from server to client
+- **Connection Management**: In-memory registry for active user connections (single-instance only)
+
 ### External Integrations
 - **TipTap**: Collaborative document editing service
 - **JWT**: Token generation and validation service
@@ -71,11 +75,13 @@ graph TB
     Router[Router<br/>Route Definitions & Middleware]
     Controllers[Controllers<br/>HTTP Request Handlers]
     Auth[Authentication Layer<br/>Session Management]
-
+    SSE[SSE Handler<br/>Real-Time Events]
+
     %% Business Logic Layer
     Domain[Domain Layer<br/>Business Logic & Models]
     EntityAPI[Entity API<br/>Database Operations]
     Service[Service Layer<br/>Configuration & Utilities]
+    SSEManager[SSE Manager<br/>Connection Registry]
 
     %% Data Layer
     Entity[Entity Layer<br/>Database Models]
@@ -96,6 +102,7 @@ graph TB
     %% Router to Controllers
     Router --> Controllers
     Router --> Auth
+    Router --> SSE
 
     %% Controllers breakdown
     Controllers --> ActionCtrl[Action Controller]
@@ -123,6 +130,11 @@ graph TB
     %% Domain to Data Access
     Domain --> EntityAPI
     Domain --> Service
+
+    %% SSE Integration
+    SSE --> SSEManager
+    Service --> SSEManager
+    Domain -.->|send events| SSEManager
 
     %% Data Access Layer
     EntityAPI --> Entity
@@ -147,8 +159,8 @@ graph TB
     classDef database fill:#ffebee
 
     class Client,Nginx external
-    class Web,Router,Controllers,Auth,ActionCtrl,AgreementCtrl,CoachingCtrl,NoteCtrl,OrgCtrl,UserCtrl,GoalCtrl,SessionCtrl,JWTCtrl,HealthCtrl web
-    class Domain,EntityAPI,Service business
+    class Web,Router,Controllers,Auth,SSE,ActionCtrl,AgreementCtrl,CoachingCtrl,NoteCtrl,OrgCtrl,UserCtrl,GoalCtrl,SessionCtrl,JWTCtrl,HealthCtrl web
+    class Domain,EntityAPI,Service,SSEManager business
     class Entity,Migration data
     class DB database
 ```