System Architecture

Architecture Overview

eKuiper Manager is built as a modern, high-performance management layer for LF Edge eKuiper. It utilizes a Hybrid Architecture that combines a Next.js 14 backend for secure proxying and AI processing with a robust client-side library for direct interactions.

The system is designed around three core pillars:

Multi-Instance Proxying: Centralized management of multiple eKuiper nodes.
Unified Client Library: A standardized TypeScript interface for all eKuiper REST APIs.
AI Orchestration: Context-aware AI assistants powered by OpenRouter.

The Proxy Architecture

To overcome CORS limitations and provide a secure, unified gateway, eKuiper Manager utilizes Next.js Dynamic API Routes to proxy requests to edge nodes.

Proxy Flow

When managing an eKuiper instance, the manager routes requests through the following path: Frontend → /api/connections/[id]/ekuiper/[...path] → Remote eKuiper Node

Key Benefits

Security: API keys and sensitive headers are managed server-side.
Multi-Tenancy: Easily switch between different edge locations (e.g., Factory A, Factory B) by providing their connection IDs.
Persistence: Server-side configurations are stored in a local SQLite database (via Prisma) or file-based storage.

eKuiper Client Implementation

The EKuiperClient is the primary interface for interacting with the eKuiper engine. It supports both Direct Mode (browser-to-eKuiper) and Proxy Mode (browser-to-Next.js-to-eKuiper).

Initialization

import { EKuiperClient } from '@/lib/ekuiper/client';

// Direct Mode: Communicates directly with the eKuiper REST API
const directClient = new EKuiperClient("http://localhost:9081", undefined, 5000, true);

// Proxy Mode: Routes through the manager's backend
const proxyClient = new EKuiperClient();
proxyClient.setBaseUrl("/api/connections/default/ekuiper");

Common Usage Examples

AI Orchestration Layer

The "AI Assistant" features are powered by a series of specialized API routes that inject system-level context into Large Language Models (LLMs) via OpenRouter.

System Prompting & Context Injection

The manager doesn't just send user prompts to the AI; it attaches a "Global Context" object containing:

Schema Metadata: Current stream definitions and available fields.
System Health: CPU/Memory usage and eKuiper version.
Live Trace Data: Recent log spans and message attributes for real-time analysis.

Available AI Endpoints

Data Persistence

The manager supports two persistence modes for storing connection details (Server URLs, names, and descriptions):

Browser Storage (Default): Uses localStorage for zero-configuration setups. Ideal for quick testing.
Server Persistence (SQLite): Uses a local .data/connections.json or SQLite database managed via Prisma. This mode is required for multi-user environments or persistent dashboarding.

Configuration Schema

Connections are structured using the EKuiperConnection interface:

interface EKuiperConnection {
  id: string;          // Unique identifier (UUID)
  name: string;        // Human-readable name
  url: string;         // The REST API URL of the eKuiper node
  description?: string; 
  isDefault?: boolean; // Default server to load on boot
}

Request Lifecycle

Selection: User selects a "Connection" from the UI.
Authentication: If the remote eKuiper instance requires a token, the Proxy Route injects it.
Execution: The EKuiperClient executes the request against the proxy endpoint.
Transformation: The manager parses the raw eKuiper JSON response into UI-friendly formats (e.g., transforming a flat rule list into a visual topology).