Skip to content

FastAPI + WebSocket File watching pattern

The FastAPI + WebSocket file watching pattern is an architectural approach used to build real-time monitoring dashboards. It combines backend file system observation with WebSocket communication to push state changes to a frontend instantly, without requiring manual refreshes^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md].

This pattern is particularly useful for applications that visualize data from local files or processes, such as system monitors or agent observability tools^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md].

Architecture Overview

The system relies on a continuous data flow composed of four distinct stages^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]:

  1. File Change: A target file or directory is modified on disk.
  2. Detection: A file watcher detects the modification event.
  3. Broadcast: The server clears its stale cache and pushes a notification via a WebSocket connection.
  4. Revalidation: The frontend receives the event and silently re-validates its data (e.g., using SWR) to update the UI^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md].

Implementation Components

Backend: FastAPI

The backend typically utilizes Uvicorn as the web server^[001-TODO__Hermes_HUD_Web_UI_-Agent_意识监控仪表盘.md]. * File Watcher: Libraries like watchfiles are used to monitor specific directories (e.g., ~/.hermes/) for changes^[001-TODO__Hermes_HUD_Web_UI-Agent_意识监控仪表盘.md]. * Caching: To avoid unnecessary disk reads, a caching layer (often implemented as a decorator like @cache_with_mtime()) checks file modification times before reading data^[001-TODO__Hermes_HUD_Web_UI-Agent_意识监控仪表盘.md]. * Data Collectors: Modular collectors fetch data for specific domains (memory, skills, logs) to serve via REST API or WebSocket^[001-TODO__Hermes_HUD_Web_UI-_Agent_意识监控仪表盘.md].

Communication: WebSocket

The WebSocket protocol enables full-duplex communication^[001-TODO__Hermes_HUD_Web_UI_-Agent_意识监控仪表盘.md]. * Real-time Updates: Instead of polling, the server actively broadcasts events when data changes^[001-TODO__Hermes_HUD_Web_UI-Agent_意识监控仪表盘.md]. * Event Triggers: The file watcher acts as the trigger for these broadcasts^[001-TODO__Hermes_HUD_Web_UI-_Agent_意识监控仪表盘.md].

Frontend: React & SWR

The frontend consumes the broadcasted events to update the user interface^[001-TODO__Hermes_HUD_Web_UI_-Agent_意识监控仪表盘.md]. * SWR (Stale-While-Revalidate): This data fetching strategy allows the UI to remain responsive. When a WebSocket signal is received, SWR re-validates the data in the background, updating the view automatically^[001-TODO__Hermes_HUD_Web_UI-Agent_意识监控仪表盘.md]. * Silent Refresh: The user experience involves no page reloads; changes appear seamlessly^[001-TODO__Hermes_HUD_Web_UI-_Agent_意识监控仪表盘.md].

Example Use Case: Hermes HUD

The Hermes HUD Web UI is a concrete implementation of this pattern. It monitors the ~/.hermes/ data directory to visualize the internal state of an AI Agent^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md].

  • Problem: The Agent's state (memory, skills, sessions) is stored in local files. A standard HTTP request loop would require the user to manually refresh to see updates^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md].
  • Solution: The FastAPI backend uses watchfiles to track changes in ~/.hermes/. Upon detecting a change, it clears the relevant cache and emits a WebSocket message. The React dashboard receives this message and triggers SWR to fetch the updated data, resulting in a "real-time" dashboard^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md].
  • [[WebSocket]]
  • [[FastAPI]]
  • [[SWR Pattern]]
  • [[Observer Pattern]]

Sources

  • 001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md