Repository navigation
[Good First Issue] Implement WebSocket real-time run status updates #11
Description
Overview
The dashboard currently polls for run status. We need a WebSocket endpoint so the frontend can receive real-time push updates when a prediction job completes or fails.
Scope
- Implement
/ws/runs/{run_id}WebSocket endpoint in FastAPI - Emit status updates:
running→completed/failed - Include result payload (or error message) in the final
completed/failedevent - Handle client disconnections gracefully
- Update frontend
useRunPollinghook to prefer WebSocket, falling back to polling - Update
NewAnalysisandRunHistorypages to listen for WebSocket events
Acceptance Criteria
- Opening a WebSocket connection to
/ws/runs/{run_id}receives status updates in real time - Frontend replaces polling with WebSocket when supported
- Connection gracefully degrades to polling if WebSocket is unavailable
- All changes covered by at least basic tests
Resources
src/climatevision/api/main.py— existing FastAPI appfrontend/src/— React dashboardteam_docs/PM_ROLE_UPDATES_FOR_GAPS.md— gap [Good First Issue] Add frontend unit tests with Vitest + React Testing Library #9 details
Difficulty: Intermediate
Labels: help wanted, backend, frontend, real-time
Activity
[-][Help Wanted] Implement WebSocket real-time run status updates[/-][+][Good First Issue] Implement WebSocket real-time run status updates[/+]sonakshigupta29 commentedon May 10, 2026
Hello @Oshgig, I looked into this issue and traced it to
src/climatevision/api/main.py, and i saw that the predict endpoint alreadytracks status as
completedorfailedinternally.So, my approach would be to add a WebSocket endpoint that broadcasts
these status updates in real time, so the frontend doesn't need
to poll. I'll also handle case of client disconnection gracefully.
Happy to open a PR if this looks right. Open to feedback on the
approach.
Ayomipo18 commentedon Aug 18, 2026
I'd like to work on this.
Planned approach, so it can be corrected before I build:
Backend — add a
/ws/runs/{run_id}WebSocket. Since/api/predictruns inference inline, status changes happen in-process, so I plan a small in-process pub/sub hub that the predict paths publish to and the socket subscribes to. On connect the socket sends the current status straight from the DB (so a client attaching late to an already-finished run still gets a terminal event), then streams transitions untilcompleted/failed, including the result payload or error on the final event.Frontend — a
useRunWebSockethook thatuseRunPollingprefers, falling back to the existing 5s polling when the socket cannot connect or errors.One question: frontend tests need the Vitest runner from #125, which is green but not yet merged. I will write the frontend tests to that setup and keep this PR free of
package.jsonchanges, so they simply start running once #125 lands — no conflict either way.Add: WebSocket endpoint for real-time run status (Climate-Vision#11) (C…