Contributing Guide

Relevant source files

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

• README.md
• package.json
• packages/eslint-config/index.js
• packages/eslint-config/react.js
• packages/prettier-config/package.json
• apps/api/package.json
• apps/dashboard/package.json
• .github/pull_request_template.md

This guide provides instructions for setting up the development environment, running services, and contributing to the Kodus Runtime project. Kodus Runtime is a complete event processing system with durable persistence, developed as a monorepo using Rust, Node.js, and React. Following these guidelines helps maintain code quality and a streamlined development process.

Sources: README.md

Getting Started

This section covers the prerequisites and installation steps required to get the project running on your local machine.

Prerequisites

Before you begin, ensure you have the following tools installed:

• Node.js: Version 22.0.0 or higher
• Rust: Version 1.70 or higher
• Docker and Docker Compose

Sources: README.md, package.json:39-41

Installation

There are two primary methods for setting up the project: using Docker for a quick setup or a manual installation for more control over the development environment.

Docker (Recommended)

The easiest way to get started is by using Docker Compose, which manages all the services, including the API, Dashboard, and Rust runtime.

1. Clone the repository.

2. Run the startup command:

   # For production-like environment
   npm run docker:up
   
   # For development with hot-reloading
   npm run docker:dev
   

Once running, the services will be available at:

• Dashboard: http://localhost
• API: http://localhost:3201

Sources: README.md, package.json:29-32

Manual Local Setup

For developers who prefer to run services directly on their host machine.

This diagram illustrates the manual setup process.

Step-by-step instructions:

1. Clone the repository: git clone <repository-url>
2. Navigate to the project directory: cd kodus-runtime
3. Set up environment variables: cp config/environment.example .env and edit the .env file as needed.
4. Install Node.js dependencies: yarn install
5. Build the Rust runtime: cargo build --release
6. Run all services in development mode: yarn run dev:all

Sources: README.md, package.json:17,21,24

Environment Configuration

The project uses a .env file for environment-specific configurations. You can create one by copying the example file.

# Copy the example file
cp config/environment.example .env

Key variables to configure include:

• PORT
• JWT_ACCESS_SECRET
• OTEL_EXPORTER_OTLP_ENDPOINT

Sources: README.md

Development Workflow

The project is a monorepo managed with Yarn Workspaces and Turbo.

Monorepo Structure

The repository is organized into several key directories:

kodus-runtime/
├── 📁 apps/              # All applications (API, Dashboard, Rust runtime)
├── 📁 packages/         # Shared packages (UI, types, config)
├── 📁 tools/            # Development tools (Docker, scripts)
├── 📁 docs/             # Documentation
└── 📁 config/           # Global configurations

This structure separates applications from shared libraries, promoting code reuse and maintainability.

Sources: README.md

Running Services

You can run all services together or individually.

This diagram shows the process of running development services.

Run all services concurrently*: yarn dev:all

• Run only the API: yarn dev:api (available at http://localhost:3201)
• Run only the Dashboard: yarn dev:dashboard (available at http://localhost:5173)

Sources: README.md, package.json:22-24

Key Development Scripts

The root package.json contains several scripts managed by Turbo to streamline development tasks across the monorepo.

Script	Description
build	Builds all apps and packages.
dev	Runs all applications in development mode.
lint	Lints all code in the monorepo.
format	Formats all code using Prettier.
type-check	Runs the TypeScript compiler to check for type errors.
check	Runs lint, format check, and type-check in sequence.
fix	Automatically fixes linting and formatting issues.
clean	Removes build artifacts and node_modules.

Sources: package.json:10-26

Coding Standards

To ensure code consistency and quality, the project enforces strict linting and formatting rules.

Linting (ESLint)

The project uses a shared ESLint configuration from the @kodus/eslint-config package. The base configuration extends eslint:recommended, @typescript-eslint/recommended, and prettier.

Key rules include:

• @typescript-eslint/no-unused-vars: Flags unused variables, ignoring those prefixed with _.
• import/order: Enforces a consistent order for import statements.
• no-console: Warns on usage of console.log.
• prefer-const: Requires const for variables that are not reassigned.

// packages/eslint-config/index.js
module.exports = {
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended',
    'prettier'
  ],
  plugins: ['@typescript-eslint', 'import'],
  rules: {
    // ...
    'import/order': [
      'error',
      {
        groups: [
          'builtin',
          'external',
          'internal',
          'parent',
          'sibling',
          'index'
        ],
        'newlines-between': 'always'
      }
    ],
    'no-console': 'warn',
    'prefer-const': 'error',
    // ...
  },
  // ...
};

For React-based packages like the dashboard, an additional configuration (@kodus/eslint-config/react) is used, which includes rules for React Hooks and JSX accessibility.

Sources: packages/eslint-config/index.js, packages/eslint-config/react.js, packages/eslint-config/package.json

Formatting (Prettier)

Code formatting is handled by Prettier. A shared configuration is defined in the @kodus/prettier-config package. You can format the entire codebase by running:

yarn format

This command is configured in the root package.json to run Prettier across all relevant files.

Sources: package.json:14, packages/prettier-config/package.json, apps/api/package.json:13

Testing

The project includes tests for both the Rust core and the Node.js applications.

• Rust Tests: Run all Rust tests using cargo test.
• Node.js/TypeScript Tests: Run tests for all packages and apps using turbo test or yarn test.

Sources: README.md, package.json:11

Submitting Contributions

Contributions are welcome. Please follow this process to ensure a smooth review.

Contribution Flow

This diagram outlines the standard process for contributing code.

Pull Request

When you open a Pull Request, please ensure you follow the guidelines outlined in the pull request template. This typically includes a description of the changes, how to test them, and any relevant context for the reviewer.

Sources: .github/pull_request_template.md

Conclusion

This guide covers the essential steps for contributing to Kodus Runtime. By following these development, coding, and submission standards, you help ensure the project remains robust, maintainable, and easy to work with for all contributors. If you have questions, feel free to open an issue on GitHub.

Sources: README.md