@reventlessdev/online-shop-hybrid-catalog

Reventless Core

Alpha release. Reventless is under active development on the alpha branch. APIs, package layouts, and on-disk formats can change without notice, and releases may include breaking changes between versions. Pin exact versions and expect churn.

Reventless is a spec-driven, event-sourced CQRS platform for serverless applications. You describe your domain as commands, events, and projections in type-safe ReScript; the framework provisions and wires the infrastructure — queues, tables, functions, event routing, serialization, and the GraphQL and MCP APIs — with Pulumi.

Full documentation: docs.reventless.dev.

It is a holistic approach for building event-based business applications, consisting of:

• A Methodology (Event Storming–based) which covers the full delivery cycle
• A Programming Model which focuses on business value
• A Domain Independent reusable Framework to optimize operational costs

It enables developers to focus on business value and ship fast by providing a hierarchical component model that guides towards best-practice architectural patterns, with everything evolving around commands & events that are part of a ubiquitous language shared across all stakeholders.

Core Technologies & Patterns

Reventless leverages modern architectural patterns and technologies:

• Domain-Driven Design (DDD) - Aligns software design with business domains and ubiquitous language
• Event-Driven Architecture - Asynchronous message-based communication between components
• Event Sourcing - Stores application state as a sequence of events (source of truth)
• CQRS - Separates read and write operations for optimized performance and scalability
• ReScript - Type-safe functional programming language compiling to JavaScript, see here
• AWS Serverless - Cloud-native deployment using Lambda, DynamoDB, SQS, SNS, and more
• Infrastructure as Code (IaC) - Automated infrastructure provisioning and management using Pulumi
• Hierarchical Component Model - Modular, reusable architectural components with built-in infrastructure definitions (via Pulumi)

Packages

This is a pnpm + Lerna monorepo. Packages are grouped by type into four workspace folders:

Folder	Purpose
reventless/	Reventless framework + extension packages
rescript/	ReScript bindings for JS/npm libraries
examples/	Example applications
packages/	Build tooling and documentation only

Framework (reventless/)

• reventless-spec — type specifications and interfaces
• reventless-core — core framework (provider-agnostic)
• reventless-aws — AWS adapters (DynamoDB, Lambda, SQS, SNS, S3)
• reventless-postgres — Postgres storage backend (classic + DCB event logs, query DB, change feed); connection-string only (RDS/Aurora, any managed provider, or a local container)
• reventless-local — local platform for dev and testing (in-memory or SQLite)
• reventless-infra — infrastructure types shared across adapters
• reventless-interop — versioned cross-plugin contract types and compatibility validation
• reventless-gwt — Given-When-Then test DSLs and CLI runner for slice testing
• reventless-domain-protocol — shared NDJSON contract between the reventless-gwt CLI and the VS Code extension
• reventless-conventional-changelog — custom conventional-changelog preset
• reventless-layer-builder — AWS Lambda layer builder (private)

ReScript bindings (rescript/)

Bindings for JS/npm libraries used across the framework:

• AWS / infra: rescript-aws-sdk, rescript-pulumi-pulumi, rescript-pulumi-aws, rescript-pulumi-docker-build, rescript-pulumi-kubernetes, rescript-ssh2
• APIs / SDKs: rescript-graphql-yoga, rescript-mcp-sdk, rescript-anthropic, rescript-effect
• Utilities / testing: rescript-uuid, rescript-fast-csv, rescript-hash-object, rescript-node-streams, rescript-node-zlib, rescript-jest, rescript-moment (shared with the UI repo)

Examples (examples/)

• online-shop-hybrid — the canonical end-to-end example (aggregates and DCB slices); runs locally in-memory and deploys to AWS
• online-shop-aggregates, online-shop-dcb — single-style variants

---

Getting Started

Prerequisites

• Node.js v22.17.1 — see .node-version. fnm / nvm will pick it up automatically.
• pnpm 10 — this repo enforces pnpm via packageManager + corepack. Enable with corepack enable. Do not use npm.
• Git.
• OCaml toolchain (opam + dune) — only if there is no prebuilt ReScript PPX binary for your platform (see PPX binary below). Prebuilt binaries cover Linux x64 and macOS arm64; other platforms build the PPX from source during setup.

Quick start (clone → running example)

git clone <repo-url> reventless-core
cd reventless-core
corepack enable          # ensures the pinned pnpm version

pnpm run setup           # one-command bootstrap (see below)

# Run the hybrid example backend (GraphQL + MCP; SQLite stores by default,
# or `pnpm run serve:memory` for in-memory):
cd examples/online-shop-hybrid/platform-local
pnpm run serve

Then log in to the Domain GraphQL server as admin / admin:

curl -s -X POST http://localhost:4000/__inmemory/login \
  -H 'content-type: application/json' \
  -d '{"username":"admin","password":"admin"}'

Endpoints once serve is running:

Service	URL
Domain GraphQL (+ /__inmemory/login, /sdl)	http://localhost:4000/graphql
Platform GraphQL (+ graphql-ws subscriptions)	http://localhost:4001/graphql
Domain MCP	http://localhost:3001/mcp
Platform MCP	http://localhost:3002/mcp

See examples/online-shop-hybrid/README.md for the full example (including the host-shell UI via pnpm run dev:full) and AWS deployment.

What pnpm run setup does

scripts/setup.mjs is idempotent and runs, in order:

1. Creates pnpm-workspace.yaml — it is gitignored (a symlink to pnpm-workspace.base.yaml, so the cross-repo dev overlay used by pnpm link:on / link:off can swap it). A fresh clone has none, so plain pnpm install would fail with ERR_PNPM_WORKSPACE_PKG_NOT_FOUND. (Manual equivalent: node scripts/workspace-setup.mjs.)
2. pnpm install — from the repo root.
3. Ensures the ReScript PPX binary for your platform (prebuilt, or built from source — see below).
4. Seeds examples/.../platform-local/.reventless/users.yaml from the committed users.example.yaml so local login works (admin/admin, user/user).
5. Builds the hybrid in-memory example (skip with pnpm run setup --no-build).

To build everything instead of just the example: pnpm run build. To run the full test suite: pnpm test.

PPX binary

Reventless uses a native ReScript PPX (@reventlessdev/reventless-ppx). Prebuilt per-platform binaries are published to the public npm registry as optional dependencies (@reventlessdev/reventless-ppx-<platform>) for macOS arm64 and Linux x64, so they install automatically with pnpm install — no authentication required.

On a platform with no prebuilt (e.g. macOS x64, Linux arm64), pnpm run setup automatically builds the PPX from source via opam exec -- dune build — this is the zero-config path and just needs the OCaml toolchain installed. Manual build:

(cd packages/reventless-ppx/src && opam exec -- dune build)
cp packages/reventless-ppx/src/_build/default/bin/bin.exe \
   packages/reventless-ppx/ppx-osx-x64.exe   # name depends on platform; see packages/reventless-ppx/bin

Windows: build and run inside WSL2 (it presents as Linux x64); there is no native Windows binary.

For detailed development workflow and contributing guidelines, see CONTRIBUTING.md.

Documentation

Full documentation is published at docs.reventless.dev.

It is a Docusaurus site under packages/doc/ — to run it locally:

pnpm --filter ./packages/doc run start   # dev server with hot reload

See CLAUDE.md for build commands and an architecture overview.

Related Repositories

• reventless-ui — a companion React component/UI library for Reventless applications, distributed separately. It consumes rescript-moment from this repo.

Architecture

Reventless is an event-sourced CQRS framework designed for serverless infrastructure, written in ReScript.

Package Hierarchy

reventless-spec (foundation)
  ↓
reventless-core (provider-agnostic framework)
  ↓
reventless-aws / reventless-postgres / reventless-local (storage & deployment adapters)

Key Components

• Aggregate - Event-sourced aggregate root with CommandTopic, EventLog, CommandGenerator
• ReadModel - Query-side projection consuming events via EventCollector
• Plugin - Deployable unit containing aggregates, read models, extension points
• Core - Application core orchestrating all components

Adapter Pattern

The framework separates deploy-time (Pulumi infrastructure) from runtime (Lambda handlers):

• src/adapter/ - Deploy-time adapter interfaces
• src/adapter/Runtime/ - Runtime builders (Single, PerAggregate, Micro)

AWS adapters implement:

• EventLog storage → DynamoDB
• CommandTopic/EventTopic channels → SQS (FIFO), SNS
• QueryDb → DynamoDB
• Task buckets → S3

License

Reventless is licensed under the Apache License 2.0.

Provenance

Reventless was originally developed (2019–2025) by Atos Austria GmbH / Eviden Austria GmbH and used in production before its open-source release. The intellectual-property rights were subsequently transferred to Martin Lorenz, who released it under the Apache License 2.0 in 2026. See NOTICE for original-author attribution.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines on:

• Setting up your development environment
• Making changes and submitting pull requests
• Commit message conventions (Conventional Commits)
• Package management with Lerna
• Publishing packages to the public npm registry

For release process documentation, see RELEASE.md.