NexusFlow Gatekeeper

NexusFlow Gatekeeper is a reference implementation for reliable distributed state synchronization in a React dashboard. It demonstrates an ACK/retry messaging loop, duplicate detection, token-authenticated WebSocket transport, and chaos controls for testing packet loss and latency.

The project is intentionally scoped as a developer-tooling prototype, not a drop-in production platform. Its value is in the architecture and verification patterns: make state changes observable, retryable, and testable across more than one browser context.

What It Demonstrates

• React + TypeScript dashboard with synchronized node state.
• Node.js Socket.IO backend for authenticated real-time transport.
• ACK loop, retry tracking, and duplicate-message handling.
• BroadcastChannel fallback for local multi-tab development.
• Chaos controls for packet loss and latency simulation.
• Playwright coverage for smoke checks and multi-context synchronization.
• Docker packaging and GitHub Actions for build, lint, and test checks.

Architecture

React dashboard
  |
  | state changes
  v
Zustand store
  |
  | ReliableMessage{id, type, payload, senderId, attempts}
  v
Transport layer
  |-- WebSocket via Socket.IO for server-mediated sync
  |-- BroadcastChannel fallback for local same-browser sync
  |
  v
ACK / retry / dedupe loop
  |-- pending message tracking
  |-- acknowledgement handling
  |-- retry limits
  |-- duplicate message suppression

Security Model

This is a demo/reference implementation, so the security model is deliberately small and inspectable:

• WebSocket clients must provide VITE_NEXUS_TOKEN during the Socket.IO handshake.
• The server fails startup when required secrets are not configured.
• Message IDs are required to be UUIDs.
• Per-client message rate limiting is enforced server-side.
• CORS is controlled through ALLOWED_ORIGINS.
• Secrets are read from environment variables and are excluded from git.

This project does not implement user identity, authorization policy, durable storage, key rotation, or production observability. Those would be required before using this pattern in a real enterprise environment.

Quick Start

npm ci
cp .env.example .env
npm run dev

In another shell, start the WebSocket server when testing server-mediated sync:

npm run server

Open http://localhost:3000.

Environment

Variable	Required	Purpose
NEXUS_SECRET	Yes	Server-side startup secret.
VITE_NEXUS_TOKEN	Yes	Client token used for WebSocket authentication.
ALLOWED_ORIGINS	No	Comma-separated CORS allowlist. Defaults to http://localhost:3000.
PORT	No	WebSocket server port. Defaults to 3001.
NODE_ENV	No	Runtime mode.

Verification

npm run build
npm run lint
npm test

The Playwright suite starts the Vite development server through playwright.config.ts and runs both smoke checks and paired-page multi-context synchronization checks.

Docker

docker build -t nexusflow-gatekeeper .

docker run -p 3001:3001 \
  -e NEXUS_SECRET=replace-with-a-strong-secret \
  -e VITE_NEXUS_TOKEN=replace-with-a-strong-token \
  -e ALLOWED_ORIGINS=http://localhost:3001 \
  nexusflow-gatekeeper

Open http://localhost:3001.

Project Structure

src/
  App.tsx                dashboard shell
  store.ts              state, ACK/retry, dedupe, metrics
  transport/            BroadcastChannel and WebSocket transport
  components/           dashboard panels and controls
server/
  index.ts              Socket.IO server, auth, rate limiting
  messageStore.ts       in-memory pending/delivered message tracking
tests/
  smoke.spec.ts         app load and basic render checks
  dashboard.spec.ts     multi-context sync checks

Current Limitations

• In-memory message state only; no durable queue.
• Token-based demo authentication only; no user or role model.
• Local/demo CORS defaults must be tightened for real deployment.
• Chaos controls are meant for local validation, not production fault injection or resilience testing.

License

ISC