Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 3

Ubiquitous Language Extraction for B2B SaaS Billing

Recommended resources

Hello! In our last lesson, we focused on the crucial partnership between developers and domain experts, establishing it as the collaborative engine that drives Domain-Driven Design. We saw that through a process of "knowledge crunching," we can distill deep business knowledge into a shared understanding.

Today, we're taking the next logical step. We will put that theory into practice by performing the first, foundational act of modeling for our project. Using a set of business requirements for our B2B SaaS subscription billing system, we will begin extracting the core terminology that will form our Ubiquitous Language. This isn't just an academic exercise; it's a critical system design activity that lays the groundwork for all the code we will write.

What is a Ubiquitous Language?

In the previous lesson, we touched on the Ubiquitous Language as the goal of our collaboration with domain experts. Now, let's define it more rigorously. It is a shared, unambiguous language, crafted by the team (developers, domain experts, product managers), that is used to talk about the software. This language must be used consistently in all communication, from team meetings to user stories, and most importantly, in the code itself.

Creating a Project Template? Go With Domain-Driven Design

This article from STRV offers a concise and effective definition of the Ubiquitous Language.

Please read the section Ubiquitous Language. Pay close attention to the idea that this language "unites the team by ensuring there is no ambiguity" and that it "should even be used in the source code itself." The 'Pro tip' about maintaining a glossary is a practical piece of advice we'll be following.

The cost of not having a Ubiquitous Language is what DDD practitioners call "translation debt." This is the hidden cost incurred when developers and business stakeholders use different terms for the same concept, or the same term for different concepts, leading to constant mental translation, miscommunication, and ultimately, flawed software.

For example, imagine one department talks about a customer "claim," another talks about a "support ticket," and a third talks about a "case." If all three refer to the same core idea, building three separate software concepts creates immense complexity. The Ubiquitous Language forces us to resolve these ambiguities early.

Our Source of Knowledge: The Subscription Lifecycle

In a real project, we would extract this language through conversations, workshops, and by studying business documents. For our course, we will use the following diagram as our primary source of domain knowledge. Imagine a product manager has handed this to you to explain the high-level flow of the business.

This diagram illustrates the lifecycle of a subscription in a B2B SaaS company, showing the different stages and the teams responsible for them.

Our task is to act as software engineers and "knowledge crunch" this diagram. We will scrutinize every label and every arrow to identify the core concepts and processes of the subscription billing domain.

The Extraction Process: Finding the Words

A powerful technique for discovering a domain's language, inspired by workshops like EventStorming, is to look for specific types of words in the business process.

  1. Events (Past-Tense Verbs): Look for things that have already happened, which represent significant state changes in the system. For example, if there's an action called "Create subscription," the corresponding event is Subscription Created.
  2. Commands (Verbs/Actions): These are the user- or system-initiated actions that trigger events. In the diagram, these are represented by the boxes like Create order and Activate subscription.
  3. Concepts (Nouns): These are the "things" in the domain. They are the subjects and objects of the commands and events. Look for terms like Customer order, Subscription, and Invoice. These often become the primary data structures in our code.

Let's walk through a few examples from the diagram:

  • The box labeled Create subscription is a Command.
  • This command likely operates on a Concept we can call a Subscription.
  • When this command is successful, it produces an Event, Subscription Created.
  • The box Bill/Invoice is another Command. It acts on the Subscription concept and produces an Invoice concept.

This process of identifying events, commands, and the concepts they relate to is a way to shift the focus from static data structures to the dynamic behavior of the system—a core principle of DDD.

Composing Complex Systems with Domain-Driven Design

The Salesforce blog has a great article that discusses this process. It introduces EventStorming as a formal technique for this kind of discovery.

Read the subsection Use EventStorming. Notice how it describes the process of listing events, identifying commands that trigger them, and the actors involved. This is precisely the mindset we are applying to the subscription lifecycle diagram.

Your Turn: Building the Initial Glossary

Now it's your turn to be the domain modeler. Carefully examine the "Subscription lifecycle" diagram again. Go through each swim lane and each box. Your goal is to extract a list of terms that form our initial Ubiquitous Language glossary. Don't worry about getting it perfect; this is the first draft.

...

Finished? Here is a potential first draft of the glossary based on the diagram. Compare it with your own list.

Core Concepts (Nouns)

  • Customer Order: A request from a customer, which could be for a new product or a change to an existing one. It seems to be the entry point into the system.
  • Subscription: The central concept. It represents the ongoing service provided to the customer. It can be created, activated, and amended.
  • Invoice: A formal request for payment sent to the customer. It is generated from a subscription.
  • Revenue Contract: An internal concept used by the "Revenue management" team to track the financial obligations associated with a subscription.

Key Actions (Commands/Verbs)

  • Plan: An initial step in "Order and supply chain," possibly related to resource allocation before an order is created.
  • Create Order: The action of formally capturing a customer's request.
  • Fulfill Order: The process of preparing the service or product for delivery.
  • Deliver/Receive Order: The point at which the customer gains access to the product/service.
  • Create Subscription: The action of instantiating a subscription based on an order.
  • Activate Subscription: The action of making a subscription "live" for a customer.
  • Amend Subscription: The action of modifying an existing subscription, likely triggered by a Change order.
  • Bill/Invoice: The action of generating an invoice for a billing period.
  • Collect/Recognize: The process of receiving payment and recognizing the revenue in accounting terms.
  • Refund/Exchange/Fix: Actions to correct issues with billing or service.
  • Create Revenue Contract: The action of establishing the internal financial record for a subscription.
  • Update Revenue Contract: The action of modifying the financial record, likely after a subscription is amended or payment is recognized.
This diagram shows how our new glossary, the Ubiquitous Language, becomes the central artifact that connects all parts of the project—from conversations with experts to the application code itself.

From Glossary to Living Document

This glossary is our first victory. We've taken a complex business process and distilled it into a set of precise, shared terms. In a real project, the next step would be to review this list with our domain experts. We'd ask clarifying questions:

  • "What is the exact relationship between a Customer Order and a Subscription? Is it always one-to-one?"
  • "What's the difference between Fulfill Order and Activate Subscription? Do they ever happen at the same time?"
  • "You used the term Bill/Invoice. Are 'Bill' and 'Invoice' perfect synonyms, or is there a subtle difference we should know?"

This feedback loop refines the language further. The final step is to make this language persistent and visible. As suggested in the articles, this could be a simple GLOSSARY.md file in our Git repository or a page in a shared Confluence or Notion space. The important thing is that it is a living document, owned by the entire team.

Conclusion

In this lesson, we transitioned from the theory of collaboration to the practical work of domain modeling. We've taken a business artifact and applied a structured approach to extract the initial terms of our Ubiquitous Language.

Here are the key takeaways:

  • The Ubiquitous Language is a shared, precise vocabulary used by the entire team in all forms of communication, including the source code.
  • It combats "translation debt" by eliminating ambiguity between business and technical terminology.
  • We can extract the language by analyzing business processes, looking for key nouns (concepts), verbs (commands), and the events they produce.
  • The output is a living glossary, a documented source of truth that is co-owned by developers and domain experts.

We now have a list of well-defined terms like Subscription, Order, and Invoice. In our next lesson, we will bridge the final gap between language and implementation. We will take these very words and begin to represent them as placeholder types in Go, making our Ubiquitous Language truly tangible in our codebase.