Overall Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Kodus Runtime is a comprehensive event processing system built as a monorepo. It leverages a polyglot architecture, combining the performance of Rust for its core processing engine, the flexibility of Node.js for its API layer, and the modern UI capabilities of React for its dashboard. This design allows for a clear separation of concerns, where each component is optimized for its specific task.
The system is designed for durable event persistence using Sled, a high-performance embedded database. It features a typed event system, a workflow engine for complex processing, and a REST API for interaction and management. The entire project is managed using turbo and yarn workspaces to streamline development across the different applications and shared packages.
Sources: README.md, package.json
System Components
The architecture is composed of three primary, decoupled applications: the React Dashboard (frontend), the Node.js API (backend), and the Rust Runtime (core engine). The API acts as an intermediary, exposing the powerful features of the Rust core to the web dashboard and other clients through a Node.js native addon.
This diagram illustrates the high-level interaction between the main components.
Component Summary
| Component | Path | Technology | Description |
|---|---|---|---|
| API | apps/api/ | Node.js, Elysia | Exposes the Rust core's functionality via a REST API. Handles authentication and requests. |
| Dashboard | apps/dashboard/ | React, Vite, TailwindCSS | A web-based user interface for monitoring events and system statistics. |
| Runtime | apps/runtime/ | Rust, Tokio, Sled | The core event-driven engine responsible for event persistence, queuing, and workflow execution. |
Sources: README.md, apps/api/package.json, apps/dashboard/package.json, apps/runtime/crates/core/Cargo.toml
Monorepo Structure
The project is organized as a monorepo, which simplifies dependency management and cross-component development. The main directories are apps for runnable applications and packages for shared code.
This structure is defined in the root package.json and managed by turbo.
Sources: README.md:57-69, package.json:2-6
Detailed Component Breakdown
Rust Core & Workflow Engine
Sources: apps/runtime/crates/core/src/workflow.rs, README.md:10-16, apps/runtime/crates/ts-addon/src/lib.rs:4-10
The heart of the system is the Rust runtime, which is composed of several crates. The kodus-core crate contains the primary business logic.
DurableStore: Provides durable event persistence using theSledembedded database. It handles asynchronous operations likepersist_eventand batch processing.WorkflowEngine: Manages the registration and execution of complex event processing pipelines. It uses aWorkflowDefinitionto define a series ofWorkflowStepitems.Event: A richly typed data structure for events, including metadata, priority, and tracking information.
The workflow engine is capable of executing a series of steps, such as transforming, filtering, or routing events based on predefined logic.
Node.js Native Addon (kodus-runtime)
Sources: apps/runtime/crates/ts-addon/src/lib.rs, apps/runtime/crates/ts-addon/Cargo.toml
To make the high-performance Rust core available to the Node.js environment, a native addon is created using napi-rs. This addon exposes a KodusRuntime class that can be instantiated in JavaScript/TypeScript.
This class acts as a bridge, wrapping the Rust DurableStore and WorkflowEngine and exposing their functionality as asynchronous methods.
The methods exposed by the KodusRuntime class are listed below.
| Method | Description |
|---|---|
persist_event | Persists a simple event with a payload and source. |
persist_event_with_metadata | Persists an event with full metadata, including priority, user ID, and tags. |
find_events_by_source | Retrieves all events associated with a given source. |
get_stats | Returns statistics from the DurableStore, such as the total number of events. |
create_workflow | Registers a new workflow definition in the WorkflowEngine. |
execute_workflow | Executes a registered workflow with a given event. |
Sources: apps/runtime/crates/ts-addon/src/lib.rs:14-156
Node.js API (apps/api)
Sources: apps/api/examples/express-app.js, apps/api/src/routes/workflows.ts, README.md:21-49
The apps/api application is a Node.js server built with Elysia that consumes the kodus-runtime native addon. It provides a RESTful interface for interacting with the event system. All critical routes are protected and require JWT-based authentication.
The following sequence diagram shows the flow for persisting a new event via the API.
Key API endpoints include:
| Endpoint | Method | Description |
|---|---|---|
/api/auth/login | POST | Authenticates a user and returns JWT tokens. |
/api/events | POST | Persists a new event. Requires authentication. |
/api/events/:source | GET | Finds events by their source. Requires authentication. |
/api/events/stats | GET | Retrieves statistics about the event store. |
/api/workflows | POST | Creates a new workflow. Requires authentication. |
/api/workflows/:id/execute | POST | Executes a workflow with a given event. Requires authentication. |
/api/health | GET | Public health check endpoint. |
Sources: README.md:21-49, apps/api/examples/express-app.js:13-112, apps/api/src/routes/workflows.ts:7-60
React Dashboard (apps/dashboard)
Sources: apps/dashboard/src/pages/Dashboard.tsx, apps/dashboard/package.json, apps/dashboard/index.html
The dashboard is a single-page application built with React and Vite. It provides a user-friendly interface for monitoring the Kodus Runtime. It uses @tanstack/react-query to fetch data from the Node.js API, such as the total number of events, and displays it in a series of cards. The dashboard is set up to periodically refetch data to provide near real-time monitoring.
For example, the main dashboard page fetches from the /api/events/stats endpoint every 5 seconds to keep the "Total Events" card updated.
Sources: apps/dashboard/src/pages/Dashboard.tsx:7-18, apps/dashboard/package.json:14-21
Data Structures
EventData
The EventData object is the primary data structure used for transferring event information between the Rust core and the Node.js environment.
| Field | Type | Description |
|---|---|---|
id | String | The unique identifier of the event (UUID). |
payload | Vec<u8> (Buffer) | The binary payload of the event. |
source | String | The source service or application that generated the event. |
priority | u8 | The event priority (0=Low, 1=Normal, 2=High, 3=Critical). |
user_id | Option<String> | Optional ID of the user associated with the event. |
correlation_id | Option<String> | Optional ID to correlate multiple events. |
tags | Vec<(String, String)> | A list of key-value pairs for metadata. |
timestamp | String | The ISO 8601 timestamp of when the event was created. |
retry_count | u32 | The number of times processing has been retried for this event. |
Sources: apps/runtime/crates/ts-addon/src/lib.rs:159-169, apps/api/examples/README.md:121-132
Summary
The overall architecture of Kodus Runtime is a well-defined, multi-layered system that effectively separates concerns. It uses Rust for its performance-critical core, a Node.js native addon to bridge the gap to the JavaScript ecosystem, a Node.js API server to provide a standard web interface, and a React frontend for user-facing monitoring. This polyglot approach, managed within a monorepo, creates a powerful and maintainable platform for durable event processing.
Sources: README.md