mvcds / hubi

Humanitarian ubiquitous language helper

Hubi

Hubi is like a database migration tool but for ubiquitous language i.e. it reads some of your versioned files to write code, data schema and documents.

When to use hubi

Use it in one or more of the following situations:

1. If you want to have a documentated language for your domain, especially when it needs to be consulted by non-technical stakeholders.

2. When working on a project spread into different repositories e.g. back- and front-ends, so changes in one of them needs to be repeatead in the other ones in order to make the end-result work.

⚠️ Hubi does not connect, or tell you how to connect, the project's repositories.

3. Your repositories are modeled in a way where it is possible to share domain knowledge across them interchangeably.

4. You want to reuse a repository's slice of the domain (the way you've coded the model) in another repository from different projects. This is the least advisable scenario, as each repository generally has a slightly different perspective on how the domain looks like.

Basic Use

Declare how your domain should look like in a YAML file, refered to as domain file, and then execute hubi with the options provided by its API ⭐.

Each one of this files is responsible for a piece of the domain. Its rules can be found at hubi's domain file guide 📗.

Installation

As hubi is a development tool, it is recommended that each project have it installed by using the developer flag.

$ npm i hubi --save-dev

or

$ yarn add hubi --dev

Example

In an imaginary project, the stakeholders have decided that it is necessary to show the user's birthday in their profile page. So the file relative to the user concept is changed:

 # Domain file @ project/src/domain/user.yml
 name: User
 description: A person who has an account
 attributes:
   - name: name
     description: How to address the person
     required: true
   - name: eyes
     description: The color of the user's eyes
+    deprecated:
+    - message:
+        We've discovered that this is a useless information for us.
+        Will be deprecated soon
+    - error: false
-    required: true
+    required: false
+  - name: birthday
+    comment: This field was added later
+    type: date
+    required: false

With one command, it is possible to spread this change to the code, data schema and documentation. You decide which translations hubi writes:

$ npm run my-custom-hubi-script
> hubi save --same-folder --translator joi & hubi save --output documents --translator site

In the example below, a Joi schema and an entry into the project's site were changed to reflect that change.

Contributing

Take a look at our 📗 contributing guide to improve hubi.

How does hubi relates to domain driven design (DDD)?

The only relation is that hubi is based on the concept of “ubiquitous language”, something Eric Evans presents in his book about DDD.

I don't know if he come up with this idea or only used it as his book's initial seed. A language-to-rule-them-all is a communication tool that simply states that we should encode domain knowledge (terms, phrases, etc) into the codebase in order to bridge the gap between developers and domain experts.

But you can still use ubiquitous language regardless of DDD because it stands on its own. So, even if you don't know/use it, you can still use hubi to reap the benefits of speaking a single language - at the same time you document your domain as code.