Introduction

You are probably asking yourself, what is SoapBerry and How does it fit my stack?

Well for now, SoapBerry is a set a crates, making the foundation of a framework for building event-first applications.

For now, let me introduce this book.

This Book

This is not a book.

Well technincally, it uses mdBook. But I mean how many books you know, are added and updated daily?... (I mean except for O'Reilly's MEAP program).

Anyways. This Book contains two parts.

1. The Usage part. This is probably where you should go. This part explains everything related to the applications and libraries and crates.
2. The Development part. This part holds architectural documents, explanations and diagrams related to the development and inner-workings of the SoapBerry that cannot fit better elsewhere. (like for example docs.rs page of each crate or comments in their code base or example folders for them)

Note on grammatical and spelling mistakes

Please note that English is not my native language. So if you have seen any mistakes please open an issue or make a pull-request. I will appreciate it!

Goals

Goals of the RedMaple Crate

Broader Goals

Permanent

Redmaple is a very small crate, there is a reason for it. The smaller something is, the more chance that it is maintainable.
That's a rough rule of thumb, but permanence being the top priority of this crate, means that every rule of thumb is taken seriously.

Some signs of reaching this goal are:

1. It has very little external dependencies.
2. It is up-to-date with the latest Rust Idioms or it has documented reasons why it is not.
3. It has no bugs or obvious performance issues in the features it is offering.
4. It has a very little resource footprint.

Finished

The project aims to be finished. That means that within the scopes of the project, it has fullfilled implementing all the features, in an idiomatic way, and is only getting updated for performance, reliability or idiomacy reasons.

Some signs of reaching this goal are:

1. Fully documented within the code, using comments.
2. Fully documented within the book.
3. Has full documentation for Architectural decisions, system design and specs.
4. Tests-as-stabilization is done.
5. Has support for all of its intended targets.

Broader Anti-goals

Goals of the whirlybird Crate

Goals of the Kyushu crate

A guide for the Users

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Redmaple Project

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Features and Anti-features

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Features

Anti-Features

Maybe-Features

Presumptions

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Kyushu

Features and Anti-features

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Features

Anti-Features

Maybe-Features

Presumptions

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Kyushu

Commands

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Features and Anti-features

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Features

Anti-Features

Maybe-Features

Presumptions

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Development

Here are the documentations for development of the SoapBerry.

Sorry for the inconviniece, the documentation is still a work-in-progress.
This section will be filled in time.

Architectural Explanation

Type Semantics

Type-Driven Development (TyDe) plays a fundamental role in my development approach, where program logic predominantly relies on type transformations. However, there are instances where broader type changes go beyond business logic, aiming to comply with implementation limitations.

Consequently, architectural patterns emerge in the realm of type conversions. To provide a visual representation of these patterns, please refer to the diagram below:

Kyushu's Domain Architecture

C4

Ah, the documentation is still a work-in-progress.
This section shall be completed in due time.

Context-Level Structure

RedMaple

A RedMaple, if you will, can be conceived as a wrapper encompassing a veritable array of events. These events, residing within the library, demonstrate their versatility through the employment of generics, thereby allowing for a multitude of implementations to coexist harmoniously.

Now, let us delve into the crux of RedMaple's design, wherein lies the implementation of each event, serving as the vessel for essential business logic. To fulfill this crucial role, I have opted for the utilization of Whirlybird, a tool specifically tailored to facilitate the seamless execution of said logic.

It is worth noting that the RedMaple's domain extends further, enabling its integration within the overarching framework of a ForestElf. Functioning as both a wrapper and a diligent manager, the ForestElf takes charge of one or more RedMaples, ensuring their smooth operation within the system.

For individuals seeking to engage with the Redmaple Cluster, a meticulous search for specific RedMaples becomes imperative. By identifying and locating the desired RedMaples, users gain the means to interact fruitfully with this interconnected network.

Let us bear in mind, however, that the depiction I have presented here reflects a hypothetical architecture based on RedMaples, devoid of any prescriptive directives.

WhirlyBird

WhirlyBird can be aptly likened to a treasure trove—a crate teeming with a diverse array of event implementations and their corresponding projectors tailored explicitly for Redmaple. The essence of Redmaple lies in its inherent generality, as it gracefully embraces the events and their projectors in a generic fashion.

These events and projectors hold paramount importance, as they are not only pivotal components of Redmaple but should also be thoughtfully crafted within the framework of the domain itself. WhirlyBird generously offers a selection of distinct event implementations and projectors, serving as valuable exemplars for inspiration in devising one's own bespoke solutions.

+-------------------------------------------------------+
|                       WhirlyBird                      |
|                                                       |
|                                                       |
|                                                       |
|                                                       |
+-------------------------------------------------------+
                   |                          |          
                   |                          |          
                   |                          |          
                   |                          |          
 +-----------------|--------------------------|---------+
 | +---------------v---------+ +--------------v-------+ |
 | | +---------------------+ | | +------------------+ | |
 | | |                     | | | |                  | | |
 | | |                     | | | |                  | | |
 | | |    Domain events    | | | |  Kinds of views  | | |
 | | |                     | | | |                  | | |
 | | |                     | | | |                  | | |
 | | +---------------------+ | | +------------------+ | |
 | +-------------------------+ +----------------------+ |
 |                        RedMaple                      |
 +------------------------------------------------------+

Kyushu

Kyushu adheres to a straightforward and pragmatic local-first architecture.

 +----------------------------------------------------+
 |            Kyushu                                  |
 | +---------------------------+                      |
 | |                           |                      |
 | |                           |                      |
 | |                           |                      |
 | | A lot of  small RedMaples |                      |
 | |                           |                      |
 | |                           |                      |
 | |                           |                      |
 | +---------------------------+                      |
 |                                                    |
 +----------------------------------------------------+
      |       ^                            |      ^    
      |       |                            |      |    
      |       |                            |      |    
      |       |                            |      |    
      |       |                            |      |    
      v       |                            v      |    
  +--------------+                   +-----------------+
  |              |                   |                 |
  |              |                   |                 |
  |              |                   |                 |
  |    FileDB    |                   |      User       |
  |              |                   |                 |
  |              |                   |                 |
  |              |                   |                 |
  +--------------+                   +-----------------+

container-level structure

Ah, the documentation is still a work-in-progress.
This section shall be completed in due time.

component-level structure

Ah, the documentation is still a work-in-progress.
This section shall be completed in due time.

codes-level structure

Ah, the documentation is still a work-in-progress.
This section shall be completed in due time.

ADR

The Architectural Decision Record (ADR) is a crucial artifact within our realm, documenting pivotal decisions that shape the project's architecture. It serves as a guide, ensuring coherence and continuity throughout the development process. The ADR promotes transparency, allowing future generations to understand the reasoning behind our choices. It is an invaluable resource for navigating the ever-evolving landscape of technology.

Use Workspaces

Decision:

Using one repo, which hosts a workspace, and many crates containing binary and library crates.

Context

How should we structure different crates related to the soapberry project?

Decision drivers

• Ease of change
• Reliability of API
• Complexity of maintenance

Considered Alternatives

One repo for soapberry and submodules for each crate

• Using submodules will create complexity when updating versions
• Also this will not help with immediate feedback

one repo per crate

• This item will cause a huge amount of friction when one crate updates.
• Also this will cause a headache for maintenance of CI/CD, considering that each change needs to be replicated on all crates.

Consequences

Pros

• Increases the agility.

Cons

• History of repose that I have already created will be lost.

Use Rust

Decision:

use Rust as the main language

Context

• What should be the main language for implementation of soapberry?

Decision drivers

• Speed of development
• Type-safety
• Expressiveness
• Tooling
• Runtime-Error proneness

Considered Alternatives

Go

• Considering Go's mark-and-sweep garbage-collection strategy and the memory intensiveness of Event-Sourcing, Go potentially can cause a considerable headache in scale.
• Go's type-system is very small and lacks many features which is neccassary for a good compile-time gurantee of correctness. To be specific, lack of sum-types means type-casting at runtime.
• Go also lacks a mature generic support which makes the anything more than the most basic generic functions to be exponentially less-readable.

Other languages

• All the languages with mark-and-sweep garbage collectors are suffering from the GC problems mentioned.
• All the languages with manual memory-management (c, c++, and even zig) are making a trade-off that I would not and need not wanted to make.

Consequences

Pros

• More correctness gurantees.
• No concerns over future memory problems.
• Very expressive and condence code.

Cons

• Finding the right abstraction takes more time.
• Compilation-time and LSP speed lacks when compared to Go.