business4s/workflows4s

Workflows4s is a Scala library for defining, executing, and managing long-running stateful workflows using a composable, effect-polymorphic DSL. It provides a flexible runtime architecture that supports in-memory execution, database persistence via Doobie, and distributed coordination through Apache Pekko. The system includes built-in visualization tools for generating Mermaid and BPMN diagrams, alongside a web-based UI and REST API for monitoring instance states and delivering signals.

31 changes.

This period focused on establishing the foundational Workflows4s engine, introducing a polymorphic WIO DSL, effect-agnostic runtimes, and a unified wakeup scheduling abstraction. It also delivered concrete backend implementations for Pekko, Doobie, filesystem, and Quartz, alongside a comprehensive documentation site and a detailed withdrawal example to demonstrate these capabilities.

22 changes.

This period focused on building a comprehensive web interface and REST API to manage and visualize workflow instances, including search, signaling, and diagram rendering. The core runtime was refactored to support a composable, effect-polymorphic engine and a new registry system, while extensive test coverage was added for PostgreSQL, SQLite, and Pekko backends.

4 changes.

This period focused on enhancing workflow safety and testability by introducing static analysis rules to detect common design issues like busy loops and clashing events. It also added an in-memory concurrent runtime for Cats Effect, enabling fiber-safe execution without external dependencies, alongside comprehensive end-to-end and unit tests for both the new runtime and the Web UI.

The web UI now includes a dedicated HTTP client (Http.scala) that handles communication with the backend API. This client supports fetching workflow instances, listing definitions, sending signals, searching workflows, and loading feature configurations, enabling the UI to interact with the workflow engine.

workflows4s-web-ui/src/main/scala/workflows4s/web/ui · high confidence

The workflows4s-example project now includes a complete Pekko-based example for managing withdrawal workflows. This addition introduces a new HTTP API (served on localhost:8989) that allows users to list existing workflows, start new withdrawals, and query their current state. The example demonstrates integration with Pekko Persistence JDBC for state management, utilizes a dummy withdrawal service for business logic, and includes custom serialization support via PekkoCirceSerializer to handle workflow data.

workflows4s-example/src/main/scala/workflows4s/example/pekko · high confidence

Introduced a new SQLite runtime for workflows4s-doobie that stores each workflow instance in a separate embedded database file. This runtime automatically initializes the schema on first access and handles concurrent access by acquiring a write lock (BEGIN IMMEDIATE) before writing events, making it suitable for single-node or embedded deployments without requiring an external database server.

workflows4s-doobie/src/main/scala/workflows4s/doobie/sqlite · high confidence

The UI now includes a new \ReusableViews\ component that provides standardized views for common states: a loading spinner with customizable text, an error notification view with a dismiss button, and an inline field display for label-value pairs. These components allow for consistent styling and behavior across the application when displaying loading states, errors, or simple data fields.

workflows4s-web-ui/src/main/scala/workflows4s/web/ui/components · high confidence

The website now includes a new HomepageFeatures component that displays three key value propositions for Workflows4s: that it requires no dedicated servers or complex features like macros, that workflows are built through composition similar to IOs and streams, and that it includes built-in diagram rendering to solve business problems. This section is styled with a flexbox layout and is now visible on the site's homepage.

website/src/components/HomepageFeatures · high confidence

The workflows4s-doobie module now includes SQL schema files for its supported database runtimes. For Postgres, a \workflow\_journal\ table stores event data with a composite index on template and instance IDs, while a \workflow\_registry\ table tracks workflow status, wakeup scheduling (including a new \wakeup\_claimed\_at\ column for claim tracking), and tags, with specific indexes for wakeup and running-state queries. For SQLite, a simpler \workflow\_journal\ table is provided to store event data. These schemas define the persistent storage structure for workflow events and registry state.

workflows4s-doobie/src/main/resources · high confidence

The workflows4s example application now includes essential resource files to support running and testing the system. An \application.conf\ file configures the Pekko runtime with cluster settings, JDBC persistence for journals, and custom serialization bindings for withdrawal events, alongside an embedded H2 database configuration. A \logback.xml\ file sets up logging to output TRACE-level details for the workflows4s library to the console. Additionally, an \api.http\ file is provided with pre-defined HTTP requests to interact with the example's withdrawal endpoints.

workflows4s-example/src/main/resources · high confidence

The repository has been bootstrapped with essential configuration files to support development and CI/CD workflows. This includes setting up \.gitignore\ for IDE and build artifacts, configuring \.scalafmt.conf\ and \.scalafix.conf\ for code formatting and linting (targeting Scala 3), and defining \.scala-steward.conf\ for automated dependency updates. CI automation is introduced via \.mergify.yml\ to handle Scala Steward PRs, while \.sdkmanrc\ and \.sbtopts\ standardize the Java environment (SDK 21.0.5-tem) and build memory settings. Documentation is initialized with a \README.md\ describing Workflows4s as a library for long-running stateful processes, and a \CONTRIBUTING.md\ guide.

(repo-wide) · high confidence

The Workflows4s documentation site is now available, built on Docusaurus. This release enables Mermaid diagram rendering in documentation, adds GitHub source links for code snippets to improve traceability, and integrates Algolia search. The site also features a custom dark/light theme and syntax highlighting for Scala, Java, and JSON.

website · high confidence

This change introduces the core pages for the documentation website, including a new home page that displays the project logo, tagline, and a SBT dependency snippet, alongside a dedicated API reference page. The API page embeds the Scaladoc documentation in an iframe and synchronizes the browser URL with the documentation's internal navigation state, allowing users to bookmark and share specific API sections directly. A basic markdown page template is also added for simple content.

website/src/pages · high confidence

Added a new database-backed runtime for workflows4s using Doobie, enabling event-sourced workflow instances to be persisted in a shared database (e.g., PostgreSQL). This includes a DatabaseRuntime that manages workflow instances via a Transactor, a WorkflowStorage trait for event persistence and advisory locking, a ByteCodec trait for serializing events, and a DbWorkflowInstance implementation that handles concurrent access through database-level locks.

workflows4s-doobie/src/main/scala/workflows4s/doobie · high confidence

Users can now visualize workflow execution progress as Mermaid flowcharts via the new MermaidRenderer, which correctly renders execution paths including explicit End nodes and error handling. Additionally, a Cats Effect-specific SleepingKnockerUpper implementation is provided to manage workflow wakeups using Async.sleep, replacing previous runtime-specific mechanisms.

repository · high confidence

This change adds a new runtime implementation for workflows4s backed by Apache Pekko. It introduces PekkoRuntime, which leverages Pekko Cluster Sharding to manage persistent workflow actors, and PekkoWorkflowInstance, which exposes workflow operations (state queries, signal delivery, wakeups, progress tracking, and expected signals) via Pekko Ask patterns. Additionally, it provides PekkoKnockerUpper, a scheduler-based component for managing workflow wakeups using Pekko's Classic Scheduler. These components together enable users to run workflows with Pekko's actor model and persistence capabilities.

workflows4s-pekko/src/main · high confidence

Added a new PostgresWorkflowStorage class that implements the WorkflowStorage interface using Doobie. This component enables persisting workflow events to a PostgreSQL database, supporting event retrieval, event saving, and transaction-level exclusive locking via PostgreSQL advisory locks. The implementation uses a configurable table name (defaulting to 'workflow\_journal') and SHA-256 hashing to generate unique lock keys from workflow instance IDs.

workflows4s-doobie/src/main/scala/workflows4s/doobie/postgres · high confidence

The web UI now includes utility modules to handle runtime configuration and diagram rendering. A new UIConfig component automatically detects the application's base path and fetches a config.json file to determine settings such as the API URL, falling back to a default localhost address if the fetch fails. Additionally, Mermaid.js integration has been added to support rendering workflow diagrams, and a helper for converting JavaScript promises to Cats Effect IO has been introduced to support these asynchronous operations.

workflows4s-web-ui/src/main/scala/workflows4s/web/ui/util · high confidence

The workflow engine now uses a new WIO-based DSL that allows workflows to be defined with effect polymorphism, meaning they can run on any effect type (such as IO or Thunk) configured via a WorkflowContext. This change introduces a lazy, synchronous Thunk type for side effects like logging, adds a LiftWorkflowEffect mechanism to bridge effect types, and exposes a retry builder for handling transient failures. Users can now define workflows that are decoupled from a specific runtime effect while retaining support for checkpointing, interruption, and progress tracking.

workflows4s-core/src/main/scala/workflows4s/wio · high confidence

The filesystem runtime now supports scheduling workflow wakeups and triggering them via the filesystem. A new \FilesystemKnockerUpper\ component manages this by delegating to a \PollingFsScheduler\, which stores scheduled wakeups as timestamped files in a specified work directory. The scheduler periodically polls this directory for files whose scheduled time has passed, triggering the corresponding workflow instances and cleaning up the files upon consumption. This change provides a concrete, file-system-backed implementation for the generic \KnockerUpper\ and \Scheduler\ abstractions, allowing workflows to be woken up based on file system events rather than in-memory timers.

workflows4s-filesystem/src/main · high confidence

The runtime now uses a new \WorkflowInstanceEngine\ trait that is polymorphic over the effect type \F\[\_\]\, allowing workflows to run in different effect contexts. A \WorkflowInstanceEngineBuilder\ provides a step-by-step API to compose engines with optional features such as wakeup scheduling (\WakingWorkflowInstanceEngine\), registry integration (\RegisteringWorkflowInstanceEngine\), greedy evaluation (\GreedyWorkflowInstanceEngine\), and logging (\LoggingWorkflowInstanceEngine\). Two pre-configured defaults are provided: \default\, which includes all features, and \basic\, which excludes wakeup and registry integrations. This change shifts the engine from a fixed implementation to a flexible, stackable architecture.

workflows4s-core/src/main/scala/workflows4s/runtime/instanceengine · high confidence

A new Component trait has been added to the UI components utility package, defining a standard interface for self-typed components with message handling and view rendering. This trait includes a ReadOnly sub-trait for components that do not handle updates, providing a foundational structure for building consistent UI elements within the application.

workflows4s-web-ui/src/main/scala/workflows4s/web/ui/components/util · high confidence

The runtime now includes a KnockerUpper component to manage scheduled wakeups for workflows with pending timers. This feature introduces a Process trait to bridge scheduling backends with actual wakeup calls on workflow instances, and an Agent trait for the engine to register or cancel wakeups after state changes. A NoOpKnockerUpper implementation is also provided for scenarios where timer-based wakeups are not required.

workflows4s-core/src/main/scala/workflows4s/runtime/wakeup · high confidence

A new workflow registry system has been added to track running instances and their execution status, enabling the web UI to list and search for workflows. This includes a core \WorkflowRegistry\ trait with an \Agent\ for updating status and a \Tagger\ for extracting user-defined tags, alongside a \NoOpWorkflowRegistry\ implementation that provides a no-operation default behavior.

workflows4s-core/src/main/scala/workflows4s/runtime/registry · high confidence

The shared API module now exposes a set of REST endpoints under the /api/v1 prefix, enabling the web UI to interact with workflow data. Users can list and retrieve workflow definitions, fetch specific instance details, and send signals to running instances. Additionally, a new search endpoint allows filtering and paginating through workflow instances, while a features endpoint provides configuration data to the frontend to determine available capabilities.

workflows4s-web-api-shared · high confidence

The workflows4s-web-api-server module now exposes a new REST API layer (built on Tapir) that allows clients to list and retrieve workflow definitions (including Mermaid diagrams), fetch detailed workflow instance states, deliver signals to running instances, and search/filter workflows by status, time, and sort order. This change introduces the server-side implementation and endpoint wiring for these capabilities, enabling external tools and the web UI to interact with the workflow engine programmatically.

workflows4s-web-api-server · high confidence

Added three new React components to the website to improve the documentation experience. OperationOutputs renders workflow diagrams using Mermaid, optional BPMN SVGs, JSON models, and debug logs in a tabbed interface. SbtDependency and SbtDependencies generate formatted SBT dependency strings for workflows4s modules, automatically pulling the current version from the site configuration.

website/src/components · high confidence

The Cats Effect integration now includes an in-memory concurrent runtime (InMemoryConcurrentRuntime) and its associated workflow instance implementation. This runtime leverages Cats Effect primitives like Ref and Semaphore to provide fiber-safe and cancellation-safe execution of workflows entirely in memory, allowing users to run and test workflows without external persistence or distributed coordination.

workflows4s-cats-effect/src/main · high confidence

Added three new Node.js scripts to the tools directory to support manual maintenance of website documentation. The \autolayout.mjs\ script applies automatic layout to BPMN diagrams using the \bpmn-auto-layout\ library, while \render-docs.mjs\ recursively converts BPMN files into SVG images via \bpmn-to-image\. A new \README.md\ provides instructions for installing dependencies and running these scripts to keep website visuals in sync with source diagrams.

tools · high confidence

Added StringUtils.scala, a new utility object providing two helper methods: randomAlphanumericString(n) generates a random alphanumeric string of length n using SecureRandom, and stringToLong(s) converts a string to a Long by taking the first 8 bytes of its SHA-256 hash. This enables callers to easily create unique identifiers or hash strings for use as workflow IDs or keys.

workflows4s-core/src/main/scala/workflows4s/utils · high confidence

The withdrawal workflow now includes a dedicated ChecksEngine that automates the execution of withdrawal checks with support for retry logic, timeouts, and manual intervention. The engine iterates through pending checks, handling errors by falling back to manual review, and allows operators to approve or reject withdrawals via a signal. It features checkpointing to persist state across restarts, ensuring that check results and decisions are preserved. The system automatically decides approval or rejection based on check outcomes, or enters a review state if a check requires human oversight or times out.

workflows4s-example/src/main/scala/workflows4s/example/withdrawal/checks · high confidence

Added a new example workflow for handling fund withdrawals that includes automatic retry logic for execution initiation. The workflow defines a sequence of steps including validation, fee calculation, holding funds, running checks, and execution, with specific handling for cancellations and error recovery. It introduces a configurable retry delay of 2 minutes for the execution initiation step, allowing the system to automatically retry failed attempts before failing the workflow.

workflows4s-example/src/main/scala/workflows4s/example/withdrawal · high confidence

The linter in workflows4s-core now includes four new static analysis rules to catch common workflow design issues at compile time. The busy-loop rule flags loops that lack progress signals, timers, or time waits, preventing infinite tight loops. The clashing-events rule detects when the same event type is expected in multiple recovery paths (such as base vs. checkpoint or base vs. interruption), which would cause non-deterministic behavior. The clashing-signals rule identifies duplicate signal definitions across parallel branches or interruption triggers. Finally, the unnecessary-error-handler rule warns when error handling is applied to code paths that cannot fail, helping to simplify workflow definitions.

workflows4s-core/src/main/scala/workflows4s/wio/linter · high confidence

The Quartz runtime now includes a concrete \QuartzKnockerUpper\ that manages workflow wakeups using the Quartz Scheduler. This implementation schedules, reschedules, or deletes Quartz jobs and triggers based on workflow instance IDs, bridging Quartz's synchronous execution model into the application's effect system via a dispatcher. This change provides the underlying mechanism for the Quartz runtime to handle scheduled workflow executions.

workflows4s-quartz/src/main · high confidence

The web UI bundle now correctly handles client-side routing for Single Page Applications. A new \UiEndpoints\ module introduces a dedicated endpoint for static assets (\/ui/assets/\\) that properly returns 404s for missing files, preventing them from incorrectly falling back to \index.html\. Additionally, a catch-all endpoint for \/ui/\\ routes non-asset requests to \index.html\ to enable client-side navigation, while explicitly checking for the assets prefix to ensure asset requests that miss the dedicated endpoint still result in a 404 rather than serving the HTML page.

workflows4s-web-ui-bundle · high confidence

The build system has been upgraded to sbt 2.0.8, which includes built-in cross-platform support, allowing the removal of the sbt-scalajs-crossproject plugin in favor of the native projectMatrix feature. A new BundleIt tooling component has been added to the project directory to automate the frontend build process; it executes a Vite build via npm and copies the resulting static assets into the application's resources directory, ensuring the bundled UI is available at runtime. Several build plugins have been updated to their latest versions, including sbt-scalafmt, sbt-scalafix, sbt-dynver, sbt-ci-release, sbt-tpolecat, sbt-scalajs, and sbt-native-packager, and a fork of sbt-revolver with sbt 2 support has been introduced.

project · high confidence

The workflows4s-web-ui has been rebuilt using Vite as the bundler, replacing the previous setup. This introduces a new development workflow where the Scala.js side is compiled via sbt and the web assets are served by Vite (defaulting to port 3000 with an API proxy to localhost:8081). The UI now leverages the Tyrian framework for rendering, initialized via a new \tyrianapp.js\ entry point. Key user-facing improvements include native system-level dark mode support for JSON viewers and syntax highlighting (using \json-formatter-js\, \highlight.js\, and \mermaid\), along with a new clipboard copy feature for JSON content. The build configuration (\vite.config.mjs\) handles the integration between the Scala.js output and the Vite server, ensuring seamless hot-reloading during development.

workflows4s-web-ui · high confidence

The workflow definition API has been refactored to use a new set of builder traits (such as DraftBuilder, HandleSignalBuilder, RetryBuilder, and RunIOBuilder) that provide a fluent, step-by-step interface for constructing workflows. This change introduces a unified AllBuilders trait that aggregates these components, allowing users to define signals, IO operations, retries, and control flow using a more structured and type-safe DSL rather than direct WIO case class instantiation.

workflows4s-core/src/main/scala/workflows4s/wio/builders · high confidence

The example API server code has been restructured into three distinct files: a shared \BaseServer\ trait that defines the API routes and UI integration, and two entry points (\Server\ and \ServerWithUI\) that configure the HTTP server. This change introduces a new 'Withdrawal' workflow to the example UI, alongside the existing 'Course Registration' and 'Pull Request' workflows, and updates the underlying runtime infrastructure to use \InMemoryConcurrentRuntime\ and \SleepingKnockerUpper\ for managing workflow instances.

workflows4s-example/src/main/scala/workflows4s/example/api · high confidence

The in-memory workflow runtime has been restructured to support effect polymorphism (F\[\_\]), introducing a new \WorkflowInstanceBase\ trait that centralizes signal delivery, wakeup processing, and state management logic. A new \DelegateWorkflowInstance\ trait and \MappedWorkflowInstance\ class provide flexible instance wrapping and effect mapping capabilities. The \InMemorySynchronizedRuntime\ and \InMemorySynchronizedWorkflowInstance\ implementations now use \WeakSync\ for state locking and include support for \getExpectedSignals\ with redelivery options, enabling better introspection of pending workflow signals.

workflows4s-core/src/main/scala/workflows4s/runtime · high confidence

The internal workflow execution engine has been restructured into a visitor-based architecture using dedicated evaluator components. EventEvaluator now handles incoming workflow events, RunIOEvaluator manages the execution of IO effects and timers, and Progress, State, Index, and Wakeup evaluators provide specific introspection capabilities for the workflow state. This change also introduces WorkflowEmbedding to support nested workflows and adds support for stateful retries, allowing workflows to maintain retry state across attempts.

workflows4s-core/src/main/scala/workflows4s/wio/internal · high confidence

The system now correctly identifies a loop as started only if its body has actually begun execution, preventing false positives where a loop with an unstarted body was previously considered active. This change is implemented in the new RenderUtils helper, which also centralizes logic for determining the started state of various workflow execution progress models.

workflows4s-core/src/main/scala/workflows4s · high confidence

The internal mechanism for converting workflow models into BPMN diagrams has been replaced. The previous \BPMNConverter\ is now deprecated and delegates to the new \BpmnRenderer\, which directly generates Camunda BPMN model instances from the internal WIO model. This change ensures that workflow visualizations are rendered using the updated rendering logic, supporting features like parallel flows, loops, and signal handling in the generated BPMN XML.

workflows4s-bpmn · high confidence

Added Pekko runtime integration tests and test infrastructure; Added PostgreSQL integration test infrastructure; Added SQLite testing infrastructure for workflow runtime; Added comprehensive test suite for workflows4s-core; Added end-to-end tests for the Web UI; Added integration and unit tests for the Withdrawal workflow example; Added test coverage for Postgres workflow runtime and registry; Added test resources for workflow examples; Added test utilities for database integration and workflow testing; Added testing utilities for workflow simulation; Added tests for InMemoryConcurrentRuntime and SleepingKnockerUpper; Added tests for QuartzKnockerUpper wakeup scheduling; Added tests for SQLite runtime adapter; Added tests for WorkflowSearchResponse serialization; Added tests for the ChecksEngine workflow across multiple runtime adapters; Added tests for the filesystem-based workflow wakeup scheduler.

The project now includes explicit dependency manifests for its core build, web interface, and documentation infrastructure. The Scala build (\build.sbt\) defines the library versions for the multi-module workflows4s project, including core libraries (Cats, Circe), Pekko runtime support, Doobie database access, Tapir for the web API, and Tyrian for the web UI. The web UI module (\workflows4s-web-ui\) introduces a Node.js dependency set managed by \package.json\ and \package-lock.json\, adding Vite for bundling, FontAwesome for icons, Bulma for styling, and Mermaid for diagram rendering. Additionally, the documentation site (\website\) is configured with Docusaurus 3, Algolia search, and Mermaid support, while a separate \tools/package.json\ adds BPMN layout utilities.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 66.

• Code Health 90
• Architecture 84
• Maturity 60
• Readiness 61
• Security 74
• Event Sourcing 100

• 300 commits — 266 feature/other, 34 fixes

• (root) — 113 commits
• workflows4s-core/src — 66 commits
• (repo) — 59 commits
• project/build.properties — 15 commits
• project/plugins.sbt — 15 commits
• workflows4s-doobie/src — 9 commits
• workflows4s-example/src — 8 commits
• .github/workflows — 7 commits
• workflows4s-cats-effect/src — 3 commits
• workflows4s-pekko/src — 2 commits
• website/docs — 1 commit
• website/src — 1 commit
• workflows4s-filesystem/src — 1 commit

• fix: Failed Scalafix rule(s) https://raw.githubusercontent.com/jatcwang/doobie-package-rename-scalafix/refs/tags/v0.1.2/rules/src/main/scala/fix/DoobiePackageRenameScalafix.scala
• fix: Fix Scala Steward config to ignore all Scala 3 library variants
• fix: Merge branch 'main' into bugfix/sleeping-knocker-upper-too-eager-cancellation
• fix: Merge branch 'main' into fix-interruption-sequence-dropped-step
• fix: Merge pull request #222 from business4s/fix-release-pipeline
• fix: Merge pull request #247 from business4s/fix-invisible-error-handler-behavior
• fix: Merge pull request #250 from business4s/bugfix/sleeping-knocker-upper-too-eager-cancellation
• fix: Merge pull request #264 from SAY-5/fix-loop-hasstarted-unstarted-history
• fix: Merge pull request #265 from SAY-5/fix-interruption-sequence-dropped-step
• fix: Merge pull request #267 from business4s/fix-postgres-registry-dispatch
• fix: Merge pull request #271 from business4s/fix-deploy
• fix: Merge pull request #276 from business4s/fix-website-version-extraction
• fix: Merge pull request #281 from business4s/fix/scala-steward-ignore-scala3-variants
• fix: More review fixes
• fix: Revert sbt to 1.12.12
• fix: Review fixes
• fix: fix cancelation logic in SleepingKnockerUpper and add test for reentrant wakeup
• fix: fix compilation
• fix: fix compilation
• fix: fix foreach builder
• …and 280 more

• 0 containers · 1 bounded contexts · 0 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

business4s/workflows4s was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.