Async Mode Approaches for Guide Run

Current Implementation Analysis

Synchronous Approach (Current)

• Flow: Guidelines processed concurrently using RxJS mergeMap with controlled concurrency
• HTTP: Direct POST requests to /validate_guideline endpoints
• Timeouts: Relies on default HTTP timeouts (typically 2-5 minutes)
• User Experience: Real-time progress updates as each guideline completes
• Problem: Long-running requests can timeout, especially for complex guides with many guidelines

Proposed Async Approaches

Approach 1: Job-Based Async Processing

Backend Changes:

POST /guideline/async/validate - Submit batch job
GET /guideline/async/status/{job_id} - Check progress
GET /guideline/async/results/{job_id} - Fetch results

Flow:

1. Submit all guidelines as single batch job
2. Poll for status updates every 5-10 seconds
3. Fetch results when job completes
4. Handle partial failures gracefully

Pros:

• No timeout issues for individual guidelines
• Server can optimize processing order
• Better resource management on backend
• Can survive page refreshes (job persists)

Cons:

• Less real-time feedback during processing
• Requires backend job queue infrastructure
• More complex error handling for partial failures

Approach 2: Streaming with Server-Sent Events (SSE)

Backend Changes:

POST /guideline/stream/validate - Start streaming analysis
EventSource /guideline/stream/{session_id} - Receive updates

Flow:

1. Start analysis session
2. Receive real-time updates via SSE as guidelines complete
3. Handle connection drops and reconnection
4. Process results incrementally

Pros:

• Real-time updates like current approach
• No polling overhead
• Can handle long-running processes
• Better user experience with live progress

Cons:

• SSE not supported in all environments (see compatibility table below)
• Connection management complexity
• Requires session management

Office Add-in SSE Support Compatibility

Platform	Version / Product	Version Details / Channel	Webview for Add-ins	SSE Support?	Enterprise Usage
Windows	Office 2016 (perpetual)	Released Sep 22, 2015	IE11 (Trident)	No	Yes (legacy)
Windows	Office 2019 (perpetual)	Volume or Retail	IE11/EdgeHTML	Limited	Yes
Windows	Office 2021 (perpetual)	Released 2021+	WebView2	Yes	Yes
Windows	Microsoft 365 < 16.0.11629	Pre-mid-2019	IE11 (Trident)	No	Yes
Windows	Microsoft 365 16.0.11629–16.0.13530	Mid-2019 to ~2021	EdgeHTML	Partial	Yes
Windows	Microsoft 365 ≥ 16.0.13530 with WebView2	2021 onward + WebView2 installed	WebView2 (Chromium)	Yes	Yes
macOS	Office 2016 for Mac	Released 2015-2019	Safari WebKit (legacy)	Partial	Yes (legacy)
macOS	Office 2019 for Mac	Released 2018+	Safari WebKit	Yes	Yes
macOS	Office 2021 for Mac	Released 2021+	Safari WebKit (modern)	Yes	Yes
macOS	Microsoft 365 for Mac < 16.17	Pre-2019	Safari WebKit (legacy)	Partial	Yes
macOS	Microsoft 365 for Mac ≥ 16.17	2019 onward	Safari WebKit (modern)	Yes	Yes
Web	Office Online (all browsers)	Browser-dependent	Native browser engine	Yes*	Yes

Safari Version SSE Support:

• Safari 5.0+ (2010): Basic SSE support
• Safari 6.0+ (2012): Full SSE specification compliance
• Safari 14.0+ (2020): Enhanced SSE with better error handling
• Safari 16.0+ (2022): Modern SSE with improved performance

*Web version SSE support depends on underlying browser - Chrome/Edge/Firefox have full support, Safari has full support in modern versions

Impact on Approach Selection:

• Windows: SSE approach viable for Office 2021+ and modern M365 with WebView2; legacy versions need polling fallback
• macOS: SSE support available in Office 2019+ and M365 for Mac 16.17+; earlier versions have partial support
• Web: Full SSE support across all modern browsers including Safari 14+
• Enterprise: Mixed environments require polling-based approaches as primary with SSE enhancement for supported versions

Approach 3: WebSocket-Based Real-Time Processing

Backend Changes:

WebSocket /guideline/ws/validate - Bidirectional communication

Flow:

1. Establish WebSocket connection
2. Send guidelines for analysis
3. Receive real-time progress and results
4. Handle connection issues and reconnection

Pros:

• Bidirectional communication
• Real-time updates
• Can handle very long processes
• Most responsive user experience

Cons:

• Most complex to implement
• WebSocket infrastructure requirements
• Connection management overhead

Implementation Considerations

Frontend State Management

• Extend RunGuidelinesStore to handle async job states
• Add polling mechanism for job status updates
• Implement progress indicators for long-running jobs
• Handle page refresh scenarios (restore job state)

Error Handling

• Partial failure scenarios (some guidelines fail, others succeed)
• Job timeout handling (backend processing limits)
• Network disconnection during polling
• Retry mechanisms for failed guidelines

User Experience

• Clear indicators when switching to async mode
• Estimated completion times for long jobs
• Ability to navigate away and return to results
• Notification when async job completes