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.

Note.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.

Cloud Node Telemetry (AWS Fargate)

For an AWS serverless (ECS Fargate) environment, the Hub's infrastructure node card is enriched with CPU% and RAM% for the cluster. This depends on Container Insights, which Nanokit enables on the ECS cluster on create and idempotently on update — without it a Fargate-only cluster publishes no reliable cluster-level series. When the cluster-level series is empty, the bridge falls back to averaging the service-level CloudWatch metrics (CPUUtilization / MemoryUtilization).

ECS reports utilization only as a percentage, so disk usage and absolute RAM byte totals are not available for Fargate and are omitted (byte fields report 0; the card renders the percentages). This is enrichment only — the node's online state derives from the bridge's environment status, not from these numbers — and is fully resilient: any telemetry error is swallowed so it can never break the bridge loop.

Decentralized & Client-Side Architecture

A key feature of the Nanokit Hub Dashboard is its fully decentralized, client-side architecture.

Even if you access the Dashboard via our centrally hosted SaaS servers (e.g., hub.nanokit.com or custom staging/production environments), your code and configuration files (nanokit.yml) never touch our servers.

How it Works:

1. Static UI Distribution: The central Dashboard server only distributes static HTML, CSS, and React assets. These run entirely within your web browser (on your computer, tablet, or smartphone).
2. Local Loopback Bridge: By default, the Dashboard client in the browser discovers and connects directly to the local daemon running on your computer at http://127.0.0.1:3006.
3. Secure Remote Tunneling: When accessing the Dashboard from another device (like a smartphone) or deploying to a VPS:
   • Nanokit establishes a secure, encrypted WebSocket tunnel mapping https://<workspace-id>.nanokit.io/_bridge directly to your local/VPS bridge daemon.
   • The Dashboard UI connects via this WebSocket tunnel, ensuring that only your browser is querying your local files.
4. Data Sovereignty: Since the browser speaks directly to your private bridge, your system files, container logs, and database structures are 100% private and secure.