UI Bridge & WebSocket Protocol
The Nanokit Bridge is the communication layer that connects the low-level CLI Core to the high-level Dashboard UI. It provides real-time visibility into the infrastructure reconciliation process.
The Event Pipeline
Nanokit uses an event-driven architecture to ensure the Dashboard is always in sync with the actual state of your deployments.
1. Activity Manager
Inside the Core Engine, the ActivityManager tracks every status change (e.g., PENDING, DEPLOYING, HEALTHY, FAILED). It acts as an internal event emitter.
2. WebSocket Server (The Bridge)
When you run the Nanokit Hub, it starts a lightweight WebSocket server. The CLI Core connects to this bridge and streams updates as they happen.
3. Dashboard Subscription
The Dashboard UI (Next.js) subscribes to these WebSocket channels. Whenever an activity occurs (e.g., a container starts), the Dashboard receives a JSON payload and updates the UI instantly without a page refresh.
Message Types
The Bridge protocol uses a set of standardized JSON messages:
| Event | Direction | Description |
|---|---|---|
status_update | Core → UI | Updates the status of a specific service or resource. |
log_stream | Core → UI | Streams real-time terminal output from a container. |
reconcile_start | Core → UI | Notifies the UI that a new reconciliation loop has begun. |
reconcile_end | Core → UI | Signals the completion of a deployment plan. |
Resilience & Consistency
To ensure the UI remains consistent even during bridge restarts or network blips:
- State Merging: The Dashboard performs incremental state merging. It doesn’t replace the entire view on every update; it only patches the modified services.
- Heartbeat: The Bridge maintains a heartbeat. If the connection is lost, the Dashboard displays a “Reconnecting” state and automatically resyncs the full state once the connection is restored.
- Deduplication: WebSocket broadcasts are deduplicated to prevent “flickering” when multiple containers report status changes simultaneously.
Security: In local environments, the Bridge uses a secure authentication token generated during project initialization. In production, it can be configured to use external identity providers for secure remote dashboard access.