camel-ops-platform/docs/ui_tech_implementation.md

UI Technology Implementation

This document maps the PM's UX vision (as defined in the UX update) to concrete React components and modern frontend technologies. The goal is to deliver a slick, modern user experience that is fast, context-aware, and built on robust industry standards.

1. Command Palette ('Cmd+K')

Vision: A fast, keyboard-centric way to navigate, search for specific business entities (e.g., order IDs), or trigger actions without navigating through deep menu structures.

Implementation:

• Library: cmdk (often wrapped by shadcn/ui's <Command> component).
• Structure:
  • A global listener binds to Cmd+K (macOS) and Ctrl+K (Windows/Linux).
  • An overlay/modal opens with a search input focused by default.
  • Results are grouped logically: Recent Searches, Business Entities (Orders, Customers), Actions (Restart Flow, View Logs), and Navigation (Go to Settings).
• Integration: Hooked into the global state and router (e.g., React Router or Next.js App Router) to perform instant client-side navigation.

2. Visual Flow Diagrams

Vision: Business-Entity First visual representation of Apache Camel integration flows, allowing users to see the path of a message, bottlenecks, and failure points at a glance.

Implementation:

• Library: React Flow (xyflow).
• Structure:
  • Custom Nodes: Implement custom node types for different Camel components (Endpoints, Processors, Splitters, Choice blocks). These nodes will display status icons (success, error, processing) and metrics (processing time, message count).
  • Custom Edges: Animated edges to simulate message flow or highlight specific paths taken by a specific business entity (e.g., tracing a specific Order ID).
  • Interactivity: Clicking a node triggers a contextual slide-out (see below) to show detailed logs, payload data, or configuration for that specific step in the flow.

3. Contextual Slide-outs

Vision: Keep the user in the context of their primary task (e.g., viewing a flow) while providing deep-dive details. Avoid full page reloads and context switching.

Implementation:

• Library: Radix UI Dialog/Sheet or shadcn/ui Sheet.
• Structure:
  • Rendered as an overlay that slides in from the right side of the screen.
  • Can be stacked or replaced depending on the user's drill-down path.
• Usage: Clicking a node in the React Flow diagram, or a row in a data table, opens the slide-out displaying detailed metadata, logs, and payload traces for that specific element.

4. State Management and Data Fetching (SaaS Proxy to Local Runner)

Vision: The UI must feel snappy and responsive, fetching data from local Runners via the SaaS proxy without causing full page reloads or blocking the UI.

Implementation:

• Library: React Query (@tanstack/react-query) combined with a robust global state solution like Zustand for client UI state.
• Architecture:
  • React Query: Handles all asynchronous data fetching, caching, synchronization, and background updates.
    • When a user opens a slide-out for a specific node, React Query fetches the logs/data for that node. If they close and reopen it, the cached data is shown instantly while a background re-fetch occurs (stale-while-revalidate).
    • Polling or WebSockets/Server-Sent Events (SSE) can be integrated with React Query to provide real-time updates of flow statuses from the Runners.
  • Zustand: Manages transient UI state, such as which slide-out is currently open, the state of the Cmd+K palette, or the current zoom/pan level of the React Flow diagram.
  • SaaS Proxy Communication: API calls are made from the frontend to the SaaS backend, which securely proxies the request down to the specific local Runner. React Query manages the loading states (spinners/skeletons) while waiting for the proxy response, ensuring the rest of the application remains interactive.