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
| Operation | Method | Description |
| :--- | :--- | :--- |
| Stream Management | listStreams(), createStream(sql) | Manage data sources and schemas. |
| Rule Control | startRule(id), stopRule(id) | Control the execution of processing logic. |
| Observability | getRuleStatus(id), getRuleTopology(id) | Retrieve real-time metrics and execution graphs. |
| Debugging | getRuleTraceIds(id), getTraceDetail(tId) | Access detailed execution spans for troubleshooting. |
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
| Endpoint | Function | Use Case |
| :--- | :--- | :--- |
| /api/ai/master-chat | Global Assistant | System-wide troubleshooting and architectural advice. |
| /api/ai/rule-gen | Rule Generator | Generates SQL and Sink configurations from natural language. |
| /api/ai/analyze | Topology Analysis | Maps complex graph nodes to plain-English explanations. |
| /api/ai/explain-plan | Query Optimizer | Explains eKuiper execution plans and identifies bottlenecks. |
Data Persistence
The manager supports two persistence modes for storing connection details (Server URLs, names, and descriptions):
- Browser Storage (Default): Uses
localStoragefor zero-configuration setups. Ideal for quick testing. - Server Persistence (SQLite): Uses a local
.data/connections.jsonor 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
EKuiperClientexecutes 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).