What is RIDDL Based On?

The RIDDL specification language borrows concepts from:

RIDDL aims to capture business concepts, system designs and architectural details in a way that is consumable by business professionals yet can also be directly translated into various technical and non-technical artifacts, including:

a documentation web-site
various architectural diagrams (context maps, sequence diagrams, and so on)
design input to code generators (e.g. Kalix, protobuffers)
Kubernetes deployment descriptors
code scaffolding and templates that implement the design captured in the RIDDL specification
and more; please see the future projects section

Using these outputs, delivery teams are well-equipped to quickly begin the task of implementation. Regeneration of the model in subsequent iterations of the design are accommodated and continue to provide value through the evolution of the design without interrupting the implementation.

Domain Driven Design (DDD)

RIDDL is based on concepts from DDD. This allows domain experts and technical teams to work at a higher level of abstraction by co-creating a ubiquitous language for the target domain enabling them to develop a system specification that is familiar and comprehensible by business and technical leaders alike.

For best comprehension of the RIDDL language, it is best to be familiar with DDD concepts. For a four-minute overview watch this video. For a more in depth understanding we recommend reading Vaughn Vernon’s more concise book Domain Driven Design Distilled, or Eric Evans’ original tome Domain Driven Design: Tackling Complexity in the Heart of Software

Reactive System Architecture (RSA)

The Reactive Manifesto was authored in 2014 by Jonas Bonér, David Farley, Roland Kunh, and Martin Thompson. As the computing landscape evolved and companies began to operate at “internet scale” it became evident that the old ways of constructing systems were not adequate. We needed an approach to system architecture back then that was fundamentally different in order to meet user expectations.

The central thesis of reactive architectures is that the overriding objective in any system must be responsiveness. Users are conditioned to expect systems that perform well and are generally available. If these conditions are not met, users tend to go elsewhere to get what they want. That, of course, is clearly unacceptable for any business endeavor. To maintain responsive to users, a system must deal with various responsiveness challenges:

system or component failure (resiliency)
increasing work load (scalability)
high operational cost (efficiency)
slow responses (performance) A reactive system aims to be responsive in the face of all of these challenges.

Without going into too much detail here, among the key means of achieving responsiveness is to decompose the concerns of a domain into well isolated blocks of functionality (DDD), and then, establishing clear non-blocking, asynchronous, message-driven interfaces between them. Together, the concepts of, Responsiveness, Elasticity, Resiliency, and Message-Driven form the basis of a Reactive Architecture.

To get more information on Reactive Architecture please refer to the excellent 6 part course by Lightbend. You can find the first course in that series here.

Unified Modeling Language (UML)

One of the key insights brought forward by UML is that it is far easier for humans to comprehend the intended design of a system by communicating these ideas with pictures. UML is a language of very precise graphical symbols that communicate different concerns of a system design.

This idea has been further leveraged by other design artifacts and activities. For example, a very common DDD exercise is called Event Storming. In this exercise a group of experts brainstorms about the things that happen, concrete events, within a system. Event Storming uses a very low fidelity tool to capture the details of the exercise. In this exercise, traditionally events are captured first on orange sticky notes. The commands that generate those notes are then captured on blue stickies. And the actors that initiate those commands are captured on yellow stickies. And so on. More information on event storming can be found here and here

RIDDL uses many of the design artifacts detailed under the UML specification to help communicate the design and intent of a system. For example, Sequence Diagrams are used extensively to document the interactions between bounded contexts in a system. A State Machine Diagram may be used to document the lifecycle of an entity or user in a system, and so on. However, RIDDL’s diagram output is not limited to UML diagrams. Peter Chen’s 1971 invention of the entity relationship diagram is very well adapted to the concept of entity in DDD. DDD also has its own diagrams:

the System Context Diagram provides a depiction of the actors, internal systems, external systems, and how they interact (use cases).
the Context Map is a high level diagram that portrays the general relationships between bounded contexts.
Business Use Case Diagram - same idea as the UML version but simpler

Jacobsen Use Cases 2.0

TODO: write this section

Agile User Stories

Agile user stories are used to capture the requirements of various components within a system. In RIDDL, user stories are part of an
epic definition

As a [persona], I [want to], [so that]…

In other words, it provides WHO (persona), WHAT (want to), and WHY (so that).

Behavior Driven Design (BDD)

Behavior-driven development was pioneered by Daniel Terhorst-North. It grew from a response to test-driven development (TDD), as a way to help programmers on new agile teams “get straight to the good stuff” of knowing how to approach testing and coding, and minimize misunderstandings. BDD has evolved into both analysis and automated testing at the acceptance level. Cucumber Documentation

BDD provides a simple specification language named Gherkin which is used heavily in RIDDL. Even if you are not familiar with the Gherkin language, it is simple enough and intuitive enough to be grasped quickly.

Gherkin scenarios follow a simple structural pattern, like this:

SCENARIO: <scenario description>
- GIVEN <a precondition>
- WHEN <an event occurs>
- THEN <take an action>

RIDDL uses this structure to define the processing that should occur when defining how an event should be handled, when a function is invoked. Most of it is free-form natural language. Consequently, RIDDL is not a precise programming language.

agile circles or considered BDD as a tool for testing, you have likely encountered Gherkin language. It follows the familiar, Given - When - Then format of capturing a user story.