API Overview

Relevant source files

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

• apps/api/package.json
• apps/api/src/routes/auth.ts
• apps/api/src/routes/workflows.ts
• apps/runtime/crates/ts-addon/src/lib.rs
• README.md
• tools/docker/docker-compose.yml
• apps/api/examples/express-app.js

The Kodus Runtime API is a RESTful service built with Node.js and the Elysia framework. It serves as the primary HTTP interface for the underlying Rust-based event processing engine. The API is responsible for handling user authentication, event persistence, workflow management, and system health monitoring. It exposes a set of endpoints for clients to register, log in, submit events with rich metadata, and execute predefined workflows.

The API is designed as a separate application within the kodus-runtime monorepo, located at apps/api. It communicates with the core Rust logic through a native Node.js addon (kodus-runtime), ensuring high performance for data-intensive operations like event storage and retrieval. Security is managed through a complete JWT-based authentication system, protecting critical routes and ensuring role-based access control.

Architecture

The API's architecture is centered around the Elysia web framework, which handles routing and request processing. The core business logic for event and workflow management is delegated to a Rust native addon, which provides a high-performance bridge to the kodus-core library.

This diagram illustrates the high-level architecture of the API service.

Core Components

Component	Description	Source Files
Elysia.js	A fast, and type-safe web framework for Bun and Node.js used to build the REST API.	apps/api/package.json:18
@kodus/auth	A shared package providing JWT generation, verification, and middleware for authentication.	apps/api/package.json:15, packages/auth/package.json
KodusRuntime Addon	The N-API bridge to the Rust core, exposing functions for event and workflow management.	apps/runtime/crates/ts-addon/src/lib.rs:8
User Service	A service layer responsible for user creation and credential validation.	apps/api/src/routes/auth.ts:3
Docker	The API is containerized for deployment, with its configuration defined in docker-compose.yml.	tools/docker/docker-compose.yml:5-26

Authentication

Authentication is managed via a complete JWT-based system that includes access and refresh tokens. It supports user registration, login, and session renewal. Critical API routes are protected, requiring a valid Bearer token in the Authorization header.

Sources: README.md:18-22, apps/api/src/routes/auth.ts

Authentication Flow

The following diagram shows the sequence of operations for a user to log in and receive authentication tokens.

Authentication Endpoints

The API provides several public and protected endpoints for managing authentication.

Method	Endpoint	Protection	Description
POST	/api/auth/register	Public	Registers a new user. Requires email, password, and name.
POST	/api/auth/login	Public	Authenticates a user and returns JWT access and refresh tokens.
POST	/api/auth/refresh	Public	Renews an expired access token using a valid refresh token.
GET	/api/auth/me	Authenticated	Returns information about the currently authenticated user.
POST	/api/auth/logout	Authenticated	A placeholder endpoint; client is expected to discard tokens.

Sources: apps/api/src/routes/auth.ts, README.md:46-55

Event Management

The API provides endpoints for persisting and retrieving events. These operations are proxied to the high-performance Rust KodusRuntime addon.

Event Persistence Flow

This diagram shows how an event is persisted through the API to the underlying Rust store.

Event Endpoints

Method	Endpoint	Protection	Description
POST	/api/events	Authenticated	Persists a new event with its payload and metadata.
GET	/api/events/:source	Authenticated	Finds and returns all events matching a given source.
GET	/api/events/stats	Authenticated	Retrieves statistics from the event store, such as total event count.

Sources: README.md:46-48, apps/api/examples/express-app.js:10-60

Event Data Structure

Events are represented by the EventData structure when interacting with the API and the Rust addon.

Field	Type	Description
id	string	Unique identifier of the event (UUID).
payload	Buffer	The binary data of the event.
source	string	The origin of the event (e.g., 'payment-service').
priority	number	Priority level: 0=Low, 1=Normal, 2=High, 3=Critical.
userId	string (optional)	The ID of the user associated with the event.
correlationId	string (optional)	A UUID to correlate multiple events.
tags	[string, string][]	A list of key-value pairs for metadata.
timestamp	string	ISO 8601 timestamp of event creation.
retryCount	number	The number of times processing has been retried.

Sources: apps/runtime/crates/ts-addon/src/lib.rs:188-198, apps/api/examples/README.md:120-131

Workflow Management

The API allows for the creation and execution of workflows, which are sequences of processing steps handled by the Rust engine.

Sources: apps/api/src/routes/workflows.ts

Workflow Endpoints

All workflow routes require authentication.

Method	Endpoint	Protection	Description
POST	/api/workflows	Authenticated	Creates a new workflow with a given name and description.
POST	/api/workflows/:workflowId/execute	Authenticated	Executes a specified workflow on a given event payload.

Sources: apps/api/src/routes/workflows.ts:6-49, README.md:49

Configuration and Deployment

The API is configured via environment variables, which are particularly important when running inside a Docker container.

Environment Variables

The following environment variables are used to configure the API service in the Docker environment.

Variable	Description	Example Value
NODE_ENV	The runtime environment.	production
PORT	The port on which the API server listens.	3201
CORS_ORIGIN	The allowed origin for Cross-Origin Resource Sharing.	http://localhost:80
JWT_ACCESS_SECRET	The secret key for signing JWT access tokens.	dev-access-secret
JWT_REFRESH_SECRET	The secret key for signing JWT refresh tokens.	dev-refresh-secret
DATABASE_URL	The path to the directory for the embedded Sled database.	/app/data

Sources: tools/docker/docker-compose.yml:10-16

Health Check

A health check endpoint is provided to monitor the status of the API service.

• Endpoint: /health (or /api/health depending on base path)
• Method: GET
• Description: Returns a JSON response indicating the service is healthy. This is used by Docker for container health checks.

Sources: tools/docker/docker-compose.yml:19-24, README.md:56