Getting started

It's highly recommended to follow the tutorial, which introduces all the important features of LetsFlow one at a time.

While it's not necessary to be a star developer to create scenarios, the documentation assumes that readers have at least some basic programming skills.

Base concepts

The scenario models a process as a fine-state machine. The actors are persons, organizations, or systems that are allowed to participate in the process by performing actions. Which actions can be performed depends on the current state of the process. By executing an action, the process can transition to a different state.

A scenario is a blueprint of a process. In programming terms; the scenario is instantiated to create a process, similar to how a class is instantiated to create an object.

Content type

The scenario is formatted as YAML or JSON and can be validated using JSON Schema.

The normalized JSON is convenient for processing by a computer. But is very verbose and therefore less readable by humans.

Pretty JSON collapses arrays, maps where there is only one option and omits properties that have the default value. This improves readability for humans, but is more difficult for computers are the structure and data types differ based on the data.

The YAML format is similar to pretty JSON, with the addition of custom tags for data functions. YAML is the recommended format for defining scenarios.

Event sourcing

LetsFlow uses an event-sourcing model. Every action is recorded as an event, regardless of whether it triggers a state transition. The current state of a process can always be reconstructed by replaying the sequence of events on the scenario.

Data functions within a process can only use information available within the process. If a state transition depends on external data (eg from a CMS or DB), the workflow engine must notify a (micro)service. The service can trigger an action with a response, which is stored as an event. This ensures that the system is deterministic.

Workflow engine

The LetsFlow workflow engine is a Node.js service for storing and running processes, accessible through a REST API with JWT-based access control. It integrates with your backend via a message queue (recommended) or webhooks.

The typical way to use LetsFlow is by including the engine in a Docker setup with your other services. Alternatively, you can integrate LetsFlow directly into your backend using the core library, but this requires implementing access control, storage, and service notifications yourself.

Frontend integration

LetsFlow easily integrates into your frontend, regardless if you're using React, Angular, Vue, Svelte, or any other component framework. You’ll define reusable action schemas and build components that match these schemas.

The level of abstraction for actions is flexible: more concrete actions lead to simpler, more numerous components, while abstract actions result in fewer but more complex ones. As you get started, favor concrete actions to keep things manageable.