Home

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• apps/runtime/crates/ts-addon/src/lib.rs
• apps/runtime/crates/core/src/workflow.rs
• apps/api/examples/README.md
• apps/api/examples/express-app.js
• apps/api/src/routes/workflows.ts
• package.json
• packages/auth/package.json

Kodus Runtime is a comprehensive event processing system featuring durable persistence. It is architected as a monorepo, integrating technologies like Rust for the high-performance core, Node.js for the API layer, and React for the user dashboard. The system is designed for handling events with rich metadata, managing them through configurable queues, and executing complex processing logic via a built-in workflow engine.

The project provides a full-stack solution, from the event persistence layer up to the API and user interface. It includes features like typed events, advanced search capabilities, batch processing for performance, and a complete JWT-based authentication system with role-based access control.

Sources: README.md:3-4

System Architecture

The Kodus Runtime is structured as a monorepo containing several distinct applications and shared packages. The core logic is implemented in Rust, which is then exposed to a Node.js API. A React-based dashboard provides a user interface for interacting with the system.

Sources: README.md:53-54

This diagram illustrates the high-level interaction between the main components of the Kodus Runtime.

Monorepo Structure

The project is organized into applications, shared packages, and development tools.

kodus-runtime/
├── 📁 apps/
│   ├── api/
│   ├── dashboard/
│   ├── runtime/
│   └── ...
├── 📁 packages/
│   ├── auth/
│   ├── types/
│   ├── config/
│   └── ...
└── 📁 tools/
    ├── docker/
    └── ...

Sources: README.md:53-70

The key components within the monorepo are:

Component	Path	Description
API	apps/api/	A Node.js API built with Elysia that serves as the main entry point for interacting with the runtime.
Dashboard	apps/dashboard/	A React-based dashboard for managing and monitoring the system.
Runtime	apps/runtime/	The core event-driven runtime written in Rust, responsible for persistence and processing.
Auth Package	packages/auth/	Shared package for JWT-based authentication and authorization utilities.
Types Package	packages/types/	Shared TypeScript types used across the API and dashboard.

Sources: README.md:55-66, apps/api/package.json:4, apps/dashboard/package.json:4, packages/auth/package.json:4

Core Features

Kodus Runtime implements several key features to provide a robust event processing platform.

Sources: README.md:9-21

Event Processing & Persistence

The system is built around a typed event system. Events contain a payload and rich metadata, including source, priority, correlation ID, user ID, and custom tags. This allows for detailed tracking and advanced search capabilities. Persistence is handled by a durable store using Sled, with support for asynchronous and batch operations to enhance performance.

Sources: README.md:11, 12, 18, apps/runtime/crates/ts-addon/src/lib.rs:37-76

The following diagram shows the lifecycle of an event from creation to retrieval.

EventData Structure

Events exposed through the Node.js bridge follow this structure:

Field	Type	Description
id	string	Unique event identifier.
payload	Buffer	The main data of the event.
source	string	The origin of the event (e.g., 'payment-service').
priority	number	0=Low, 1=Normal, 2=High, 3=Critical.
userId	string (optional)	ID of the user associated with the event.
correlationId	string (optional)	ID to correlate multiple events.
tags	[string, string][]	Key-value pairs for custom metadata.
timestamp	string (ISO 8601)	Timestamp of event creation.
retryCount	number	Number of processing retries.

Sources: apps/api/examples/README.md:128-139, apps/runtime/crates/ts-addon/src/lib.rs:200-210

Authentication System

The API is secured with a complete JWT-based authentication system. It supports user registration, login, and session renewal via refresh tokens. Access to critical routes is protected and controlled by roles (Admin, User, Service).

Sources: README.md:23-28, packages/auth/package.json:14-15

Authentication Flow

The login process involves exchanging user credentials for an access token.

Protected vs. Public Routes

Route	Method	Protection	Description
/api/auth/login	POST	Public	User login.
/api/auth/register	POST	Public	New user registration.
/api/auth/refresh	POST	Public	Renew access token.
/api/health	GET	Public	System health check.
/api/events	POST	Protected	Create a new event.
/api/events/*	GET	Protected	Search for events.
/api/workflows/*	POST	Protected	Create or execute a workflow.
/api/auth/me	GET	Protected	Get current user details.

Sources: README.md:44-51

Workflow Engine

A core feature is the workflow engine, which allows for complex, multi-step event processing. Workflows are defined as a series of steps that can transform, filter, route, or perform other actions on events. The engine is implemented in Rust and exposed through the Node.js API.

Sources: README.md:19, apps/runtime/crates/core/src/workflow.rs, apps/api/src/routes/workflows.ts

Workflow Step Types

Workflows are composed of steps, each with a specific function.

Step Type	Description
Transform	Modifies the event data or metadata.
Filter	Filters events based on certain criteria.
Route	Routes events, for example by adding a routing tag.
ExternalCall	Makes a call to an external system.
Delay	Introduces a delay in processing.
Condition	Proceeds based on a conditional check of the event.

Sources: apps/runtime/crates/core/src/workflow.rs:27-34

Workflow Execution and Retry Logic

The engine includes robust error handling, with support for retry policies and dead-letter queues.

This diagram shows the execution flow, including the retry mechanism.

Node.js Integration

The core Rust logic is compiled into a native Node.js addon, allowing seamless integration with JavaScript and TypeScript applications. The KodusRuntime class provides an interface to the underlying Rust functions.

Sources: README.md:20, apps/runtime/crates/ts-addon/src/lib.rs, apps/runtime/crates/ts-addon/Cargo.toml:14

KodusRuntime Class

This class is the primary entry point for interacting with the runtime from Node.js.

Example Usage

The runtime can be used to build custom applications, such as a REST API with Express.js.

// File: apps/api/examples/express-app.js
const express = require('express');
const { KodusRuntime } = require('../crates/ts-addon');

const app = express();
const runtime = new KodusRuntime('./data');

// Persist an event
app.post('/events', async (req, res) => {
    const { payload, source } = req.body;
    const eventId = await runtime.persistEventWithMetadata(
        Buffer.from(JSON.stringify(payload)),
        source,
        // ... other metadata
    );
    res.json({ success: true, eventId });
});

// Find events
app.get('/events/:source', async (req, res) => {
    const { source } = req.params;
    const events = await runtime.findEventsBySource(source);
    res.json({ success: true, events });
});

// Get stats
app.get('/stats', async (req, res) => {
    const stats = await runtime.getStats();
    res.json({ success: true, stats });
});

Sources: apps/api/examples/express-app.js:1, 4, 10, 13-26, 39-42, 61-64

Configuration

The runtime's behavior can be customized via a config.json file. This includes settings for the executor, store, queue, and telemetry.

{
  "runtime": {
    "executor_type": "Tokio",
    "max_concurrent_tasks": 1000,
    "shutdown_timeout_secs": 30
  },
  "store": {
    "data_dir": "data",
    "batch_size": 1000,
    "compression_enabled": false
  },
  "queue": {
    "capacity": 10000,
    "priority_enabled": true,
    "dead_letter_queue_enabled": true,
    "retry_policy": {
      "max_retries": 3,
      "initial_delay_ms": 1000
    }
  },
  "telemetry": {
    "enabled": true,
    "endpoint": "http://localhost:4318"
  }
}

Sources: README.md:315-356

Summary

Kodus Runtime is a powerful and flexible event processing system that leverages the performance of Rust for its core operations and the versatility of the Node.js ecosystem for its API and integrations. Its monorepo structure, rich feature set including a workflow engine and durable persistence, and comprehensive authentication make it a solid foundation for building scalable, event-driven applications.

Sources: README.md:3-4, 9-21