Contributing Guide

Getting Started

Thank you for your interest in contributing to eKuiper Manager. We aim to build the most robust, open-source management interface for LF Edge eKuiper, and your help is vital.

Prerequisites

To set up the development environment, ensure you have the following installed:

• Node.js: v18.17.0 or later
• npm: v9.0.0 or later
• eKuiper Instance: A running instance of eKuiper for testing (alternatively, use the mock scripts provided in the repo).

Local Development Setup

1. Clone the Repository

   git clone https://github.com/ankur-paan/ekuiper-manager.git
   cd ekuiper-manager
   

2. Install Dependencies

   npm install
   

3. Environment Configuration Create a .env.local file in the root directory. If you plan to contribute to AI features, add your OpenRouter API key:

   OPENROUTER_API_KEY=your_key_here
   NEXT_PUBLIC_DEFAULT_EKUIPER_URL=http://localhost:9081
   

4. Run the Development Server

   npm run dev
   

   Open http://localhost:3000 with your browser to see the result.

Technical Standards

Code Style

• TypeScript: All new code must be written in TypeScript. Avoid using any where possible; use the interfaces defined in src/lib/ekuiper/types.ts.
• Framework: Next.js 14 (App Router).
• Styling: Tailwind CSS for UI components.
• Linting: Ensure your code passes npm run lint before submitting a PR.

API Proxying

The project uses Next.js Route Handlers to proxy requests to eKuiper instances to avoid CORS issues.

• Client-side calls should use the internal proxy: /api/connections/[id]/ekuiper/[...path].
• Direct server-side calls should use the EKuiperClient in DIRECT mode (see src/lib/ekuiper/client.ts).

AI Logic & Prompts

When contributing to AI features (located in src/app/api/ai/):

• Robustness: Always implement "Robust JSON extraction" logic to handle AI responses that might include markdown wrappers.
• Rate Limiting: Handle 429 status codes gracefully.
• System Instructions: Keep prompts focused on "Industrial Automation" contexts as per existing patterns.

Verification & Testing

Before submitting a Pull Request, verify your changes against a live or mock eKuiper instance using the provided scripts.

Running Verification Scripts

We provide scripts to ensure your changes haven't broken the core client logic:

# Check if the OpenAPI spec is reachable and valid
npx ts-node scripts/check-openapi.ts

# Verify core API operations (Streams, Rules, Plugins)
npx ts-node scripts/verify-api.ts

Pull Request Process

1. Branching: Create a feature branch from main (e.g., feat/rule-editor-updates or fix/connection-timeout).
2. Commit Messages: Follow Conventional Commits (e.g., feat: add rule topology zoom, fix: handle empty stream lists).
3. PR Template: Your PR description should include:
   • A summary of the changes.
   • The issue number being addressed (if applicable).
   • Screenshots for UI/UX changes.
   • Confirmation that npm run lint and verification scripts pass.
4. Review: At least one maintainer must review and approve the PR before merging.

Project Structure

| Directory | Description | |-----------|-------------| | src/app/api | Next.js Route Handlers (AI logic, eKuiper proxy). | | src/components | Reusable UI components (shadcn/ui based). | | src/lib/ekuiper | Core API client and TypeScript definitions. | | src/lib/openrouter | AI provider integration. | | scripts/ | Maintenance and API verification scripts. | | .data/ | Local persistence for connection configurations (JSON-based). |

Licensing

By contributing to this project, you agree that your contributions will be licensed under the IDACS Open Source License (IOSL) included in the repository. Always ensure you are not committing code with incompatible licenses.