Document SSE streaming in user-facing docs

Author: emersonfelipesp

docs/backend/index.md

@@ -17,6 +17,26 @@ The NetBox plugin stores and manages endpoint records, then triggers sync reques
 - **POST polling**: traditional request/response that waits for completion.
 - **GET SSE stream**: the plugin proxies the backend's streaming response to the browser, rendering granular progress (e.g., `Processing device pve01`, `Synced virtual_machine vm101`) in real time.
 
+## Sync Endpoints
+
+| Plugin Path | Backend Path | Description |
+|-------------|--------------|-------------|
+| `sync/devices/stream/` | `GET /dcim/devices/create/stream` | Stream device sync progress |
+| `sync/virtual-machines/stream/` | `GET /virtualization/virtual-machines/create/stream` | Stream VM sync progress |
+| `sync/full-update/stream/` | `GET /full-update/stream` | Stream full update progress |
+| `sync/devices/` | `POST /dcim/devices/create` | Device sync (single response) |
+| `sync/virtual-machines/` | `POST /virtualization/virtual-machines/create` | VM sync (single response) |
+| `sync/full-update/` | `POST /full-update` | Full update (single response) |
+
+## How SSE Streaming Works
+
+1. The user clicks a sync button in the NetBox UI.
+2. The plugin fetches the stream endpoint (e.g., `sync/full-update/stream/`).
+3. The plugin performs a streaming HTTP request to the backend's SSE endpoint.
+4. As the backend processes each object, it emits SSE `step` events.
+5. The plugin proxies these events back to the browser as a Django `StreamingHttpResponse`.
+6. The browser JavaScript parses each SSE frame and updates the sync log and progress bar in real time.
+
 ## Architecture
 
 ![Proxbox Architecture Image](./proxbox-architecture.png)

docs/features/synchronized-data.md

@@ -1 +1,60 @@
-# Synchronized Data
+# Synchronized Data
+
+Proxbox synchronizes data between Proxmox clusters and NetBox using a dual-mode sync architecture. The NetBox plugin triggers sync requests against the ProxBox FastAPI backend, which performs the actual object creation and updates.
+
+## Sync Modes
+
+### POST Polling (Traditional)
+
+When you click a sync button, the plugin sends a POST request to the backend and waits for a single JSON response containing the final result. This is the simplest mode and works well for quick syncs.
+
+### GET SSE Streaming (Real-Time Progress)
+
+For longer sync operations, the plugin uses Server-Sent Events (SSE) to stream progress updates in real time. When you click a sync button, the browser fetches a streaming endpoint, and the plugin proxies the backend's `text/event-stream` response back to the page. Progress updates appear immediately in the sync log without waiting for the entire operation to finish.
+
+The plugin prefers SSE streaming when available. Each sync button carries both a POST URL (`data-sync-url`) and a stream URL (`data-sync-stream-url`). The browser JavaScript uses the stream URL when present.
+
+## Stream Endpoints
+
+| Plugin Path | Backend Path | Description |
+|-------------|--------------|-------------|
+| `sync/devices/stream/` | `GET /dcim/devices/create/stream` | Stream device synchronization progress |
+| `sync/virtual-machines/stream/` | `GET /virtualization/virtual-machines/create/stream` | Stream VM synchronization progress |
+| `sync/full-update/stream/` | `GET /full-update/stream` | Stream full update (devices + VMs) progress |
+
+## Progress Messages
+
+SSE streaming provides granular per-object progress messages. For example, during a full update you might see:
+
+```
+full-update: Starting devices synchronization.
+full-update: Processing device pve01
+full-update: Synced device pve01
+full-update: Processing device pve02
+full-update: Synced device pve02
+full-update: Devices synchronization finished.
+full-update: Starting virtual machines synchronization.
+full-update: Processing virtual_machine vm101
+full-update: Synced virtual_machine vm101
+full-update: Virtual machines synchronization finished.
+full-update: Full update sync completed.
+full-update: stream completed
+```
+
+## SSE Event Format
+
+All stream endpoints return `Content-Type: text/event-stream` and emit three event types:
+
+- **step**: Progress frame with `step` (object kind), `status` (`started`, `progress`, `completed`), `message` (human-readable text), and `rowid` (object name/ID).
+- **error**: Error frame when an object fails to sync. Contains `step`, `error`, and `detail`.
+- **complete**: Final frame with `ok` (boolean) and `message`. Marks the end of the stream.
+
+## Failure Handling
+
+- If the backend returns an error during streaming, the plugin emits an SSE `error` frame with the failure details and continues with a `complete` frame.
+- If the stream proxy itself encounters an error (e.g., backend unreachable), it emits a fallback SSE error frame instead of returning a Django 500 page.
+- The browser JavaScript displays error details from both `error` frames and non-200 HTTP responses.
+
+## WebSocket Mode (Legacy)
+
+The backend also provides a WebSocket endpoint (`/ws`) for interactive sync. This predates the SSE streaming approach and sends the same per-object progress JSON over a bidirectional WebSocket channel. SSE streaming is now preferred for browser-based sync because it works with standard HTTP requests.

docs/index.md

@@ -47,7 +47,7 @@ Proxbox is split into two services:
 1. The NetBox plugin from this repository.
 2. A separate FastAPI backend service, `proxbox-api`.
 
-The NetBox plugin stores endpoint configuration and triggers sync requests. The backend talks to Proxmox and NetBox over HTTP and can optionally stream updates over WebSocket.
+The NetBox plugin stores endpoint configuration and triggers sync requests. The backend talks to Proxmox and NetBox over HTTP and streams real-time progress updates via SSE (Server-Sent Events). Legacy WebSocket streaming is also supported.
 
 ## Recommended Install Path