Monorepo Structure
Relevant source files
The following files were used as context for generating this wiki page: - [README.md](https://github.com/Wellington01/kodus-runtime/blob/HEAD/README.md) - [package.json](https://github.com/Wellington01/kodus-runtime/blob/HEAD/package.json) - [Cargo.toml](https://github.com/Wellington01/kodus-runtime/blob/HEAD/Cargo.toml) - [apps/api/package.json](https://github.com/Wellington01/kodus-runtime/blob/HEAD/apps/api/package.json) - [apps/dashboard/package.json](https://github.com/Wellington01/kodus-runtime/blob/HEAD/apps/dashboard/package.json) - [packages/types/package.json](https://github.com/Wellington01/kodus-runtime/blob/HEAD/packages/types/package.json) - [apps/runtime/crates/core/Cargo.toml](https://github.com/Wellington01/kodus-runtime/blob/HEAD/apps/runtime/crates/core/Cargo.toml) - [apps/runtime/crates/ts-addon/Cargo.toml](https://github.com/Wellington01/kodus-runtime/blob/HEAD/apps/runtime/crates/ts-addon/Cargo.toml)The Kodus Runtime project is organized as a monorepo that consolidates multiple applications and shared libraries, facilitating a cohesive development workflow across different technology stacks including Rust, Node.js, and React. This structure enables code sharing, centralized dependency management, and streamlined build processes.
The monorepo is managed using a combination of Yarn workspaces for the TypeScript/JavaScript parts and Cargo workspaces for the Rust components. Turbo is used as the high-performance build system for the JavaScript/TypeScript workspace.
Sources: README.md:3, package.json:2, Cargo.toml:2
High-Level Directory Structure
The repository is divided into several top-level directories, each with a distinct responsibility.
kodus-runtime/
├── 📁 apps/ # Todas as aplicações
│ ├── api/ # API Node.js (Elysia)
│ ├── dashboard/ # Dashboard React (Vite)
│ ├── runtime/ # Runtime Rust (event-driven)
│ ├── queue-worker/ # Worker de filas
│ ├── event-processor/ # Processador de eventos
│ └── cli/ # CLI tool
├── 📁 packages/ # Pacotes compartilhados
│ ├── ui/ # Componentes React
│ ├── types/ # TypeScript types
│ ├── utils/ # Utilitários
│ └── config/ # Configurações
├── 📁 tools/ # Ferramentas de desenvolvimento
│ ├── scripts/ # Scripts de automação
│ ├── docker/ # Configurações Docker
│ ├── ci/ # CI/CD
│ └── xtask/ # Ferramentas Rust
├── 📁 docs/ # Documentação
└── 📁 config/ # Configurações globais
Sources: README.md:57-77
The following diagram illustrates the main directories and their purpose.
Sources: README.md:57-77
| Directory | Description |
|---|---|
apps/ | Contains all runnable applications, such as the API, dashboard, and the core Rust runtime. |
packages/ | Contains shared libraries and configurations used across different applications in the apps directory. |
tools/ | Holds development and operational tooling, including Docker configurations, automation scripts, and Rust xtask tools. |
docs/ | Project documentation. |
config/ | Global configuration files for the project. |
Sources: README.md:57-77
Workspace Management
JavaScript/TypeScript Workspace (Yarn & Turbo)
The Node.js-based parts of the monorepo are managed as a Yarn workspace, with Turbo orchestrating tasks like building, testing, and linting. The root package.json defines the main scripts that delegate tasks to Turbo.
Key scripts include:
dev: Runs all applications in development mode.build: Builds all JavaScript/TypeScript packages and applications.lint: Lints all relevant code.test: Runs tests across the workspace.docker:*: A set of scripts for managing Docker containers (build, up, down, etc.).
Sources: package.json:6-29
The following diagram shows how applications and packages are interconnected. The api and dashboard applications depend on shared packages like types, config, and auth.
This dependency graph is derived from the dependencies sections of the respective package.json files.
Sources: apps/api/package.json:16-19, apps/dashboard/package.json:19-21
Rust Workspace (Cargo)
The Rust components are organized into a Cargo workspace, defined in the root Cargo.toml. This allows for shared dependencies and unified build commands.
The workspace members are:
apps/runtime/crates/core: The core event processing logic.apps/runtime/crates/adapters: Adapters for external systems (e.g., Kafka, NATS).apps/runtime/crates/ts-addon: A Node.js addon to expose Rust functionality to TypeScript/JavaScript.tools/xtask: A crate for project-specific developer tasks.
Sources: Cargo.toml:2-7
// Cargo.toml
[workspace]
members = [
"apps/runtime/crates/core",
"apps/runtime/crates/adapters",
"apps/runtime/crates/ts-addon",
"tools/xtask"
]
Sources: Cargo.toml:2-7
Applications (apps/)
The apps directory contains the main, deployable components of the Kodus Runtime system.
| Application | Description | Technology Stack | Source File |
|---|---|---|---|
api | A REST API built with Elysia.js for handling events, workflows, and authentication. | Node.js, Elysia.js, TypeScript | apps/api/package.json |
dashboard | A web-based dashboard for monitoring and managing the runtime. | React, Vite, TypeScript | apps/dashboard/package.json |
runtime | The core event-driven runtime responsible for event processing and persistence. | Rust | apps/runtime/crates/core/Cargo.toml |
Sources: README.md:59-61, apps/api/package.json:3, apps/dashboard/package.json:3
ts-addon
A critical component is the ts-addon located at apps/runtime/crates/ts-addon. This is a Rust crate that compiles into a native Node.js addon, bridging the gap between the high-performance Rust core and the Node.js API. It exposes functionalities like event persistence and workflow execution to the JavaScript environment.
Sources: apps/runtime/crates/ts-addon/Cargo.toml:2, apps/api/examples/README.md:7
Shared Packages (packages/)
The packages directory hosts reusable code and configurations shared across the applications.
| Package | Description | Source File |
|---|---|---|
@kodus/types | Contains shared TypeScript type definitions for objects like events and workflows. | packages/types/package.json |
@kodus/config | Provides shared configurations, such as logging utilities. | packages/config/package.json |
@kodus/auth | Includes authentication and authorization utilities, primarily for JWT handling. | packages/auth/package.json |
@kodus/eslint-config | Shared ESLint configuration for consistent code style. | packages/eslint-config/package.json |
@kodus/prettier-config | Shared Prettier configuration for code formatting. | packages/prettier-config/package.json |
Sources: README.md:63-67, packages/types/package.json:3, packages/config/package.json:3, packages/auth/package.json:3
The dashboard application, for example, explicitly depends on @kodus/types and @kodus/config to ensure consistency with the backend API.
// apps/dashboard/package.json
"dependencies": {
...
"@kodus/types": "file:../../packages/types",
"@kodus/config": "file:../../packages/config"
},
Sources: apps/dashboard/package.json:19-21
Conclusion
The monorepo structure of Kodus Runtime is a well-organized system that leverages the strengths of both the JavaScript and Rust ecosystems. By using Yarn and Cargo workspaces, it provides a unified development experience. The clear separation between apps and packages promotes code reuse and modularity, while tools like Turbo and Docker streamline the build and deployment processes. This architecture is key to managing the complexity of a polyglot system and enabling efficient, scalable development.
Sources: README.md, package.json, Cargo.toml