Spec: Match Progress SSE (Gap #10)¶
Status: Deferred — UX improvement, not blocking Issue: #167 Effort: 1-2 days Tier: Sonnet
Problem¶
Matching takes 8-10 seconds with no progress feedback. The user sees a black box while the system queries Qdrant, Neo4j, PostgreSQL, and generates LLM explanations.
Design¶
SSE Event Stream¶
Reuse the existing SSE pattern from document processing (/documents/stream).
Endpoint: GET /api/v1/cases/{case_id}/match/stream
Events:
| Step | Event | Payload | Duration |
|---|---|---|---|
| 1 | match.started |
{strategy, provider_count} |
0s |
| 2 | match.semantic_search |
{candidates_found} |
~1-2s |
| 3 | match.graph_traversal |
{relationships_checked} |
~1-2s |
| 4 | match.scoring |
{providers_scored} |
~1s |
| 5 | match.explaining |
{provider_name} (per provider) |
~3-5s |
| 6 | match.completed |
{total_matches, top_score} |
0s |
Frontend¶
Add step indicators to the match_results RichCard, similar to the document processing card's 6-step progress display.
Implementation¶
matching_engine.py— emit events to Redis pub/sub at each stagecases.py— new SSE endpoint that subscribes to match channel- Frontend — new progress state in ConversationApp for match_results
Edge Cases¶
- Match completes before SSE connection established — return completed event immediately
- Match fails mid-stream — emit error event with stage info
- Timeout (>30s) — emit timeout event, return partial results if available