DEV Community: Cesar Martinez

Domain driven architecture in the frontend (II)

Cesar Martinez — Mon, 06 Jun 2022 23:07:43 +0000

(This is the continuation of an article about domain driven architecture in the front. To learn what that is, why it can be important and how to implement it in your frontend code, go check out the first part.)

By now you have a domain class, it's types, and a repository. You're probably wondering how that is going to play with your application code and your framework (Vue, React, Angular, Svelte, whatever), and how you're going to use that in your components. I'm sorry to disappoint, but we're still not quite ready to touch framework code just yet, but we're getting closer.

Primary

The reason we can't talk about your framework code just yet is because your domain objects can't go directly into your components. As said in the previous article, your domain must remain protected. Allowing domain objects into the components leaves them open to manipulation of every kind, in all manner of places. That's how complexity becomes unmanageable.

Since we're not providing free access to domain objects, the architecture proposes instead to provide access to View objects.

View objects

Let's dive into the code (sauce here):



import type { Recipe } from "@/domain/recipe/Recipe";
import type { RecipeId } from "@/domain/recipe/types";
import type { Ingredient } from "@/domain/ingredient/Ingredient";

export class RecipeView {
  private constructor(
    public readonly id: RecipeId,
    public readonly name: string,
    public readonly ingredients: Ingredient[],
    public readonly instructions: string,
    public readonly portions: number,
    public readonly updatedAt: string
  ) {}

  static fromProperties(recipe: Recipe) {
    const { id, name, ingredients, instructions, portions, updatedAt } =
      recipe;
    return new RecipeView(
      id,
      name,
      ingredients,
      instructions,
      portions,
      updatedAt.toLocaleDateString()
    );
  }

  get mealSizeIcon() {
    switch (this.portions) {
      case 1:
        return "single";
      case 2:
        return "couple";
      case 3:
        return "family-one-kid";
      default:
        return "family-two-kids";
    }
  }
}

As you can see, a View is a publicly-accessible representation of a domain object. Views don't have as many rules as domain objects (nothing does actually). You have a lot more freedom to implement into Views what's most convenient for you and your team. Let's see what we can learn from this example:

You are welcome to import domain types and use them to, well, type your typescript code as you please.
The constructor is also private: it needs to be instantiated via the static fromProperties method. If your domain instance has getters required by the View, make them available in the properties object.
The properties of the View don't need to match the properties of the domain object. In this example we transform the updatedAt Date into the string that's to be displayed in the UI. Whether that's a good choice or not depends solely on the needs of the app you're developing.
You can enhance the View class with getters, or even extra properties, as needed. In this example I added the mealSizeIcon getter.

Remember that issue we mentioned in the first part of this article with regards to simplifying your component? What you place in Views is one of the things that will help you write dumber, simpler components. In many cases this might be a more convenient solution than creating smaller and smaller components (see tips and tricks below for more details).

Perhaps now you're wondering, how we're supposed to get these View objects into the components? Or even, where are these Views instantiated? If you are thinking this, then you're on the right track.

Use cases

If primary is what connects domain, secondary and UI, then use cases are the roads thanks to which that connection happens. Whenever the UI needs to access anything from the domain, there's a use case to provide it. Let's see how that looks:



import type { RecipeRepository } from "@/domain/recipe/repository/RecipeRepository";
import type { UserId } from "@/domain/user/types";
import { RecipeView } from "@/primary/recipe/RecipeView";

export class GetRecipesUseCase {
  constructor(private readonly recipeRepository: RecipeRepository) {}

  async execute(userId: UserId): Promise<RecipeView[]> {
    const recipes = await this.recipeRepository.getRecipes(userId);

    return recipes.map(RecipeView.fromDomain);
  }
}

Source.

On its most basic form, a UseCase will execute a repository method and return to the UI the Views of those domains. A few things worth noting here:

UseCases are constructed with repositories, not with the classes that implement them. (This is the D in SOLID: Depend upon abstractions, not concretions).
UseCases have a single public method "execute", but can have as many private methods as needed.
This is the only place where domain methods are allowed to be executed. Requesting the mutation of domain objects only happens within use cases.
UseCases always return Views (or void).

Even though this example doesn't show it, use cases can become quite stuffed with logic. When there are relationships between domains that need to be displayed, UseCases can be constructed with as many repositories as needed to handle it. This because you will want to design your use cases to be as convenient as possible for your UI. This is yet another way to keep your components dumb and simple.

Imagine, for example, that you want to show a list of recipes that can be cooked with the seasonal ingredients. For that we may require the IngredientRepository to get the list of ingredients of the current season, and the RecipeRepository would then be called with a filter containing only those ingredients. All that logic could reside in the corresponding GetSeasonalRecipes use case.

When having several use cases requiring several repositories, you may need to be careful to avoid circular dependencies.

Service or UseCase index

You will end-up with a good amount of use cases in each of your domains. Your use-cases directory should thus contain an index of all the use cases to provide easy access to all of the use cases of a domain. This index takes the form of a class that we have called a "Service". This is how that service could look like:



import type { RecipeRepository } from "@/domain/recipe/repository/RecipeRepository";
import type { RecipeToSave } from "@/domain/recipe/types";
import type { UserId } from "@/domain/user/types";
import type { UserRepository } from "@/domain/user/repository/UserRepository";
import { CreateRecipeUseCase } from "@/primary/recipe/use-cases/CreateRecipeUseCase";
import { GetRecipesUseCase } from "@/primary/recipe/use-cases/GetRecipesUseCase";

export class RecipeService {
  private getRecipesUseCase: GetRecipesUseCase;
  private createRecipeUseCase: CreateRecipeUseCase;

  constructor(
    private readonly recipeRepository: RecipeRepository,
    private readonly userRepository: UserRepository
  ) {
    this.getRecipesUseCase = new GetRecipesUseCase(recipeRepository);
    this.createRecipeUseCase = new CreateRecipeUseCase(
      recipeRepository,
      userRepository
    );
  }

  async getRecipes(userId: UserId) {
    return await this.getRecipesUseCase.execute(userId);
  }

  async createRecipe(form: RecipeToSave) {
    return await this.createRecipeUseCase.execute(form);
  }
}

Source.

As you can see, the Service just indexes the 'execute' functions of the use cases. This way, when you use them in your framework, you don't need to inject the use cases one by one. You can simply inject the Services. Plus, it's way nicer to be able to call recipeService.getRecipes(userId) in your components, rather than getRecipesUseCase.execute(userId).

Secondary

In many places we have used the Repositories interfaces to reference functions that are supposed to provide us with domain objects. We have yet to implement any of those repositories. We'll do that next.

Resource

All communication your application has with the external world is implemented by the Resource class. And when I say all, I mean all. When a component needs some data to display, it doesn't care whether that data comes from a REST API, a GraphQL API, local storage, the state management store, WebSockets, edge functions, firebase, supabase, cookies, IndexedDB, or anything else. The resource is the only one that needs to deal with those issues.

Your resource will implement the Repository defined in the domain. And it will do whatever it needs to do to fulfil that contract. And it's up to you, the frontend dev, to make sure that it does this in the most efficient way possible. You'll notice however, that this task becomes much simpler now that you have only one place where you need to think about it.

Let's start with a simple example:



import type { RecipeRepository } from "@/domain/recipe/repository/RecipeRepository";
import type { UserId } from "@/domain/user/types";
import type { Recipe } from "@/domain/recipe/Recipe";
import type { ApiRecipe } from "@/secondary/recipe/ApiRecipe";
import type { RestClient } from "@/secondary/RestClient";

export class RecipeResource implements RecipeRepository {
  constructor(private readonly restClient: RestClient) {}

  async getRecipes(userId: UserId): Promise<Recipe[]> {
    const apiRecipes = await this.restClient.get<ApiRecipe[]>(
      `/users/${userId}/recipes`
    );

    return apiRecipes.map((apiRecipe) => apiRecipe.toDomain());
  }

  async getFavoriteRecipes(userId: UserId): Promise<Recipe[]> {
    //
  }

  async createRecipe(userId: UserId, form: RecipeToSave): Promise<Recipe> {
    //
  }

  async updateRecipe(recipeId: RecipeId, form: RecipeToSave): Promise<Recipe> {
    //
  }

  async deleteRecipe(recipeId: RecipeId): Promise<void> {
    //
  }
}

Full source code.

What's important here is the RecipeResource implements RecipeRepository part. You'll see a Typescript error in your IDE until all the methods in the Repository are implemented in the Resource.

In the simple example shown here, the RecipeResource only fetches information from a REST API. And so it's constructed only with the RestClient (which is just a wrapper over fetch). If later we'd like to replace fetch with Axios or some other HTTP client, we'd be able to do so without interfering with the Repository. Also, if the Resource would later require to connect with a GraphQL API, for example, you can simply add your own graphQLClient to the constructor and use it.

API adapters

The response that the API provides will hardly ever match exactly with your domain in the frontend. An adapter is what will allow you to transform the response to domain objects.

Here's an example:



export class ApiRecipe {
  constructor(
    public readonly id: RecipeId,
    public readonly name: string,
    public readonly ingredients: ApiIngredient[],
    public readonly instructions: string,
    public readonly portions: number,
    public readonly updatedAt: string
  ) {}

  toDomain(): Recipe {
    const ingredients = this.ingredients.map((ingredient) =>
      ingredient.toDomain()
    );

    return Recipe.fromProperties({
      id: this.id,
      name: this.name,
      ingredients: ingredients.map((ingredient) => ingredient.properties),
      instructions: this.instructions,
      portions: this.portions,
      updatedAt: new Date(this.updatedAt),
    });
  }
}

Source.

In this example we transform the updatedAt string sent by the API into a Date instance as expected by the domain.

The client will automatically transform the API response into instances of ApiRecipe. That's why we can safely type the response with restClient.get<ApiRecipe[]>, and use it in apiRecipes.map((apiRecipe) => apiRecipe.toDomain())

Store

Your components don’t get direct access to the state management library. All data the component needs is called from a service, which calls a use case, which interacts with repositories implemented by resources. Depending on the responsibility you assign to the store, it’s likely the resource that interacts with the store on behalf of components.

It's useful when using stores to define their responsibility in advance: what do you need them for in your app? Are they a global data source for your app that will be saving the API responses? Then they belong in your secondary. Are they your solution for cross-component events and reactive properties will be saving Views and application state? Then they should go in your primary… Or you can have both, as long as they are distinct and don't share responsibilities.

Let's expand on our previous example to see how that works. Say we want to store the recipes in the store the first time we hit the API. And we also want to avoid hitting the API again if the recipes are already stored:



export class RecipeResource implements RecipeRepository {
  constructor(
    private readonly restClient: RestClient,
    private readonly store: RecipeStore
  ) {}

  async getRecipes(userId: UserId): Promise<Recipe[]> {
    const recipesInStore = this.store.recipes;
    if (recipesInStore.length !== 0) {
      return recipesInStore.map(Recipe.fromProperties);
    }

    const apiRecipes = await this.restClient.get<ApiRecipe[]>(
      `/users/${userId}/recipes`
    );
    const recipes = apiRecipes.map((apiRecipe) => apiRecipe.toDomain());
    this.store.saveRecipes(recipes.map((recipe) => recipe.properties));

    return recipes;
  }
  // ...
}

To achieve this, the RecipeStore is passed to the constructor. The getRecipes method now first checks to see if the recipes are already in the store. If they are, it returns the domain objects instantiating them from the stored data. If there are no recipes stored, then we fetch them, and then save them in the store so that the next time the function is called it returns the stored recipes. That's about it, really.

As you can see, with this approach there will never be an API call made in the actions of your store. All you will ever do with the store is save and retrieve data, just as intended.

Caveat
There is a special case in which the most convenient solution is to have your component react to changes in the store directly. This probably means that having that store hold API data wasn't the best idea, and it should've maybe been a primary store. However, in my experience, this is really the exception. In most cases, you’re good to go with getting the data once from the store and having your framework’s internal reactivity system handle the rest via props, component state, events, composables, hooks, etc.

UI

We're finally here! Now we get to talk about framework code! We have all we need to invoke the power of our domain and use it in our components. Unfortunately I won't be able to tell you the best way to do this in every frontend framework, but I'll tell you how I've learned to do it in Vue, and I'll tell you what you need to take into consideration to make the best decision in your framework of choice.

In Vue, we use the Provide / Inject mechanism to give components access to the services they need. You can either use app-level provide, or component level provide if you know where in the component tree to do so.



import { createApp } from "vue";
import { createPinia } from "pinia";

import App from "./App.vue";

import { RecipeResource } from "@/secondary/recipe/RecipeResource";
import { RestClient } from "@/secondary/RestClient";
import { useRecipeStore } from "@/secondary/recipe/RecipeStore";
import { RecipeService } from "@/primary/recipe/use-cases";
import { UserResource } from "@/secondary/user/UserResource";

// Services
const pinia = createPinia();
const restClient = new RestClient();

const userResource = new UserResource();

const recipeStore = useRecipeStore();
const recipeResource = new RecipeResource(restClient, recipeStore);
const recipeService = new RecipeService(recipeResource, userResource);

// Setup
const app = createApp(App);

app.use(pinia);
app.provide<RecipeService>("recipeService", recipeService);

app.mount("#app");

As you can see, all your components really need access to is the services.

After that, you can use them in components at your leisure:



<script setup lang="ts">
import { inject } from 'vue'  

const recipeService = inject<RecipeService>("recipeService")!;

const recipes = recipeService.getRecipes()
</script>

The injection is preferred to a simple import because it will greatly simplify testing. Like this you can easily create your own mock objects and inject them into the components while testing. This way you can easily test all possible data states being introduced into your components. For React, maybe using Context to include the services would be the way go, but I'll let you be the judge of that.

Extra

If you've made it this far, you already have all the elements you need to start your own journey in domain driven frontend architecture. Now I'll just share a few noteworthy lessons I've learned on my personal journey.

Data flow diagram

Here's a neat diagram to remember the main ideas of how data flows in architecture:

In blue the API objects, in red the view objects, and in purple the domain objects.
Data can flow both ways (incoming and sending), but should always follows the same path. Incoming data from an external source (yes, that includes the Store), takes the form of API objects. The resource receives those, instantiates domain instances, and passes them forward to the use case. The use case then returns view objects to the components.

Note that the domain takes some of the space of secondary and primary. This is to represent the influence of domain in those areas: the resource implements the domain repository, and use cases are the only places where domain methods are called.

Tips and tricks

Sometimes the hardest part of implementing this architecture will be deciding what goes in the domain, what goes in the view, and what can legitimately stay in the components. The way to think about this question with regards to your frontend code differs greatly from the way you think about it with regards to the backend.

How to know what is part of the Domain and what isn't

In the book, Scott Millett and Nick Tune ask us to think about the most important thing of the application, the part that is actually providing value. The whole point of DDD is to create the conditions in which devs can focus most of their attention into that thing.

That is great and you should definitely be doing that. On the day-to-day, however, when you receive a task to implement a new feature and you need to decide which properties and methods to include in your domain model, you will need a bit of a more concrete answer. The answer will vary from company to company and from project to project. What if what makes your solution special is the UX/UI, instead of the business intelligence powering it? Does that means that UX/UI related properties will go into the domain? 🤷 One would have to be placed in that position to be able to answer that.

The one thing I learned (the hard way) though is that I should never assume that whatever the backend provides is what needs to be in the domain model in the front. Doing this misses the point of this exercise. As a frontend developer, I encourage you to don't be afraid to rethink their decisions. See if/where/how all of the properties you receive from the back are being used. Implement in your domain model only what you need in order to accomplish your goals, and leave everything else out. If later someone needs to add other properties to the domain model to augment your functionality, let them do it, and that's a good thing, because you want that person to think about the properties he's going to need on his own. You don't need to think for him now.

Personally, I have found it useful to think that, if the decision to have it in the application comes from the Product Owner (the product person, ideally the one with the whole view of the problem and the solution), then it usually will go in the Domain. If the decision comes from the designer (or whoever decides the UI), then you can probably place it in the View.

How to know what to place into Views and what to leave for components

To answer this, we as frontend devs will have to (again) think about the application as a whole, but this time from a UX/UI perspective. The questions you may have have while thinking what to place on the domain will probably be directed to the the product person. The questions you may have while thinking what to put in the View will likely be directed to the UI/UX designer.

Pay attention to the intended design and think what information and or visual queues about the information always appear together. An example I used earlier about my cookbook app: the designer may decide that every time the difficulty of a recipe is displayed, then a specific icon is shown to represent that difficulty. If that's the case always then that's a strong argument to placing a reference to that icon next or along with the recipe difficulty property. Another good example that I see often is when displaying the status or state of a process (i.e., is a recipe a draft, is a bank transfer ongoing, is an appointment cancelled). Usually when conveying such information designers choose to always use some specific visual queues. Those could probably be included in your View. Elements that are particular to a single component can stay in the component.

Where the power of the View really comes to light is when a company has a consistent design system in place. If that's the case, you may find all the answers you need simply by going through and understanding the design system. For example, if in the system you see that dates are always displayed in one or two formats, then you can include those formats in your Views. Transforming the date into the proper format doesn't need to be done by the component in this case.

I can't speak highly enough about the value of a well-maintained design system for frontend devs that implement this architecture. The agility you and your team can achieve, even in very complex solutions, is just unmatched.

So many classes everywhere 😩 Is there a more functional way to go about implementing this?

I'm no expert in functional programming, but yes, I believe there is. Truth is, I'm not a big fan of classes myself (or at least I wasn't). The only thing I believe truly benefits a lot from having the form of a Class is the domain model. I believe it's important to show explicitly which properties are private and readonly, and which ones aren't. You can probably figure out compliant ways to implement the rest of the architecture with pure functions, if that's your thing. And if you do, hit me up, I'd love to take a look!

Conclusion

I’ve never been as happy coding as I am when I'm implementing this architecture (or at least its most valuable lessons). To me, it has meant the difference between randomly writing commands in the screen until it works, and actually feeling in control over what's happening. That's the reason I'm writing this long-ass article. If I can help anyone feel the same joy, I've done my part.

That being said, this architecture, and indeed DDD in general, is not for everybody and every project. Millett and Tune say that if you're building another todo list app, then you probably don't need DDD. I think this is because there's no complexity to be managed in a todo list. Any developer can come to the code and understand everything, because everyone knows how todo lists work. However, if you're building a unique todo list, with features that make it special to the users, then perhaps the teachings of DDD will prove useful to you.

For me, the main teachings are:

No time is wasted when thinking about how to manage the increasing complexity of your codebase. The discussions I've had with my team around the subject (all of which have informed the views I've expressed in this article) have been the most enriching of my career, and are at the base of the best code I've been able produced so far.
No time is wasted that is spent thinking about the domain. Under domain-driven architecture, a day at work of implementing a new, complex feature looks quite different for me from a day without it. In the former, follow me for a day and you’ll see me, after reading the requirements, discussing with the product owner, talking to the designer, and talking to other team members, not writing a single line of code for 5 hours, just thinking… and then come back and write a (tested) solution I can feel proud of in under 2 hours. In the latter, you’ll probably see me writing code for 2 days, hitting inexplicable errors, not talking to anyone, and providing a (not tested) solution for which I just feel glad I don’t have to deal with anymore, but it's a short-lived relief because I will likely have to come back to it to solve bugs.
In your codebase, define clear responsibilities, and when you spot new responsibilities popping up, set them apart as well.
Protect the model. Just like how in the flux design pattern any change to the store is constrained to a particular way, in the same way changes to domain objects should also be constrained. Use the language features available to you to inform the dev about these (useful) constraints.
Write tests. I don't have the occasion to discuss testing here, but it's a big, inseparable part of DDD, (and should be the same for the coding of any serious application using no matter which design). Listen to Uncle Bob discuss himself this here.
All projects have an architecture. Not choosing an architecture is an architecture decision. Such decision should always be made consciously, weighing the pros and cons, and making the reasoning behind the final decision known to everyone.

Speaking of pros and cons...

Pros and cons of this architecture

To finish, here's a quick rundown of the pros and cons I've been able to gather from my experience.

Pros

Places devs in a position in which they have to think about the domain, which is just another way of saying "think about the best solution possible to the business problem at hand".
Produces maintainable, organized, robust, testable (and hopefully, tested) code.
More rewarding coding experience, and thus a more rewarding working experience (personally at least).

Cons

Increased entry cost. This is particularly new for most frontends. It took me quite some time to get a decent grasp of the how's and why's of all the architecture decisions that I suddenly needed to start considering while coding.
Increased boilerplate. That's been for a while my biggest issue with this particular flavour of domain-driven architecture for the frontend. In my personal projects I have made certain decisions that would help decrease the boilerplate, but I've since learned that what I save from writing less boilerplate doesn't make up for the inconsistencies that get introduced into the codebase due to these decisions. Currently, the way I tackle the boilerplate issue is by creating as many snippets and file templates as I need that would write the boilerplate for me so I don't have to.

Domain driven architecture in the frontend (I)

Cesar Martinez — Mon, 06 Jun 2022 22:30:57 +0000

This is the Part I of the article. If you're looking for Part II about Primary and Secondary the link is right here

This article is about what domain driven architecture is, why it could help you, and how I've learned to implement it in the frontend.

What

This one goes out to any frontend developer that has ever found himself dreading the thought of working on a codebase because it's just too hard to follow what anything is doing anymore.
I'm writing this because I've been there myself: you start working on a project and in the beginning everything is a breeze, but as it grows it becomes harder and harder to get anything done on it. Over time, something that was exciting becomes a hassle, and the motivation to work suffers because of it. This can happen even if you follow best practices and the recommended style guide to the letter. If you can relate, then domain driven architecture can help you.

The domain driven architecture I propose here is one implementation of some of the principles of domain driven design (DDD), the development philosophy defined by Eric Evans in "Domain-Driven Design: Tackling Complexity in the Heart of Software" (2003).

Why

One of the main reasons this architecture is put in place is to help developers manage the complexity which increases over time in the codebase. Another reason is to enable developers to focus most of their attention and intelligence in thinking about the problem the business is solving (its domain).
In other words, we tell devs:

"Focus on figuring out the best solution possible. When you need to implement it just follow the architecture".

Architecture decisions are usually limits we impose on our liberty as devs, but which in return increase the organization, predictability, readability, and testability of the project. Domain driven architecture increases the initial cost of building a project, but greatly reduces the cost of maintaining it. Domain driven architecture is thus justified for any solution projected to exist (and evolve) in the long-term.

One of the main reasons software becomes complex and difficult to manage is due to the mixing of domain complexities with technical complexities. Evans describes this problem as "code that does something useful, but without explaining how".
(Patterns, Principles, and Practices of Domain-Driven Design. Scott Millett, Nick Tune, 2015)

How

Before going over the particular architecture decisions I have learned to follow and how they've helped me and my team, let's go over how a typical frontend application looks like.

The "problem"

Check this representation of a typical frontend architecture design taken straight from Huy Ta Quoc (link to the resource below). Does it looks familiar?

(Check out Huy Ta Quoc's very well-written article on the topic: https://dev.to/huytaquoc/a-different-approach-to-frontend-architecture-38d4)

Imagine we're building an application to store and share cooking recipes. Under this design the code may resemble something like this:

<template>
  <h1>Add Recipe</h1>
  <form>
    <div class="form-group">
      <label for="name">Name</label>
      <input type="text" v-model="name" />
    </div>
    <div class="form-group">
      <label for="ingredients">Ingredients</label>
      <textarea v-model="ingredients"></textarea>
    </div>
    <div class="form-group">
      <label for="instructions">Instructions</label>
      <textarea v-model="instructions"></textarea>
    </div>
    <button @click="save">Save</button>
  </form>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { useRecipeStore } from '@/stores/recipeStore'

const name = ref()
const ingredients = ref()
const instructions = ref()

const recipeStore = useRecipeStore()

async function save() {
  recipeStore.saveRecipe(name.value, ingredients.value, instructions.value)
}
</script>

(Even though I'm showing a Vue app, these teachings apply to any modern frontend framework)

I'm sure you've seen it though: the saveRecipe action would then make an API call with those parameters to save it in the backend, and probably also save the new recipe in the store.
Here's what the code displaying all the recipes may look like:

<template>
  <h1>Recipes</h1>
  <RecipeCard v-for="recipe in store.recipes" :key="recipe.id" />
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import RecipeCard from '@/components/recipe'
import { useRecipeStore } from '@/stores/recipeStore'

const store = useRecipeStore()

onMounted(async () => {
  // If we have the recipes in store, don't refetch
  if (store.recipes.length) return
  await store.fetchRecipes()
})
</script>

For a time, this is probably fine for many projects. But after a while, as complexity grows, the flaws of this design will begin to surface.

State management is tightly coupled to the components.
It took me a while to understand why this is a problem. After all, that's exactly how the official documentation showcases the usage of the library. How can this design pattern be wrong if the people writing the library display it like that? Well, it may or may not be wrong for you. The trick is in spotting the difference.

As said in the beginning, it all depends on the project. What's important is to make a conscious decision about the architecture the devs are choosing for the project, instead of following blindly what's shown in the docs and tutorials.

If, for whatever reason the team decides to change the state management library, this tight coupling will make such a task pretty difficult. "But we would never do that!" you may be thinking. You may be right... but you do want to update to newer versions of the same library, don't you? Well, Kia King said it himself, "... consider Pinia as Vuex 5 with a different name". For me, when the time came to make that upgrade, I was happy state management was loosely coupled.

Loose coupling with your state management can also greatly simplify components. If there’s something we can all agree on as frontends is that the dumber the components, the better. By dumb components, we mean simple components. Those that don’t have to do lots of things; they focus on one thing and do it correctly. Ideally, a component should just receive some data and display it, and that’s it, right?

I couldn't agree more! Looking at our code, however, what's happening in the onMounted hook of the "Recipes" component? In that piece of code the component is basically deciding its caching strategy... that shouldn't be there. We want our components to call the data it needs, and it shouldn't care at all whether the data is coming from cache, or from the API, or from LocalStorage, or whatever.
Indeed, to fix this you can have that check in the action itself and remove it from the component... but there may be a better, more comprehensive solution.

Something I used to like but now I find it to be an issue, is that it allows you to call an action to fetch data in the component and then "magically" have that data available via the getters. Now I'd much prefer a more descriptive way of coding, for example, calling fetch and assigning its results to a data property of the component directly. No magic involved, just easy-to-follow code. This makes it so that you don't need to know Vue to understand what's happening.

Let's take a look at another example of code you've probably seen before:

<template>
  <div class="recipeCard">
    <div class="h2">{{ name }}</div>
    <div
      :class="{
        danger: difficulty === 'hard',
        warn: difficulty === 'intermediate',
        success: difficulty === 'easy',
      }"
    >
      <span>{{ difficulty }}</span>
      <RecipeTutorial
        v-if="difficulty === 'hard'"
        class="recipeTutorial"
        :steps="steps"
      >
        {{ tutorial }}
      </RecipeTutorial>
    </div>
    ...
  </div>
</template>

The idea here is that the component behaves differently depending on the state of the data it receives (the recipe difficulty level in this case). You probably see similar code every day.

The issue here is that the knowledge regarding how the recipe state affects the application is hidden away in the component. This code does something useful but it's not explaining how. On one hand it's adding complexity to the component, which ideally should remain as dumb and simple as possible. On the other hand, that knowledge hidden away in the component is not reusable.
This would be ok if the behaviour is particular to that component only (which is not necessarily the case here because one can imagine that every time a recipe's difficulty is referenced it needs to use that particular class or icon). So you may decide to create an even smaller component that accepts the recipe difficulty and displays it as it should in every case. This is definitely a plausible solution, but still new devs will need to dig into the component tree to find the relevant application knowledge. There may be a better solution...

Before we talk about the solution, let's go over one final piece of code you've probably seen countless times:

export const useRecipeStore = defineStore({
  id: "recipes",
  state: () => ({
    recipes: [] as Recipe[],
  }),
  actions: {
    async fetchRecipes() {
      const { data: recipes } = await axios.get<ApiRecipe[]>("/recipes");
      this.recipes = fromApiToRecipes(recipes);
    },
  },
});

Here the state management library (Pinia in this case, but it can be Vuex, Redux, XState or any other) is used to interact with the api to fetch the data, adapting that data to whatever the application needs (with fromApiToRecipes), and also saving the result in the store.

The issue here is that the state management library is taking in more responsibility than it has to. The state management library should ideally only be used for state management. This effectively means that all the code in your stores should only pertain to the issue of state management. It shouldn't be the store's responsibility to run unrelated side-effects, format the data for components, make API calls... All of which you can find throughout store actions in many codebases. This leads to stores growing to immense complexity even for relatively simple apps (I have certainly been guilty of this in the past).

I have also seen actions being used as containers for api calls, bypassing the store altogether!

actions: {
    async fetchRecipes() {
      const { data: recipes } = await axios.get("/recipes");
      return recipes;
    },
  },

And I have also seen multiple components calling actions on created or mounted without anyone ever checking to see if this data is already available in the store. If you open the network tab in these apps and use it, you'll find the same api calls with the same parameters being made over and over again... Oh, the wastefulness!

All of these problems have, in my experience, a single root cause: lack of defined responsibilities in the code. Just like with people, when some code has too many responsibilities at the same time, it's bound to handle them poorly.

The A solution (the Hexagon)

Let's start then, by separating and defining some responsibilities.

The first thing you see (and probably the most important) is the decision to separate (and protect) the domain from the rest of the application (primary), and from its infrastructure (secondary). Let's see what's the deal with these new directories.

(The reason I personally prefer the naming primary instead of application is that the latter can be confused with the "application domain" or "application service" that some apps contain. And I prefer secondary instead of infrastructure (or infra) because the word may refer to a directory reserved for DevOps where they place configs for Docker, Terraform, Ansible.)

Domain

The first and most important new directory in this proposed architecture is domain. The domain is the core of the application; the engine that solves the business problem. You should be able to swap the whole domain out from the application and place it in a different context (in Svelte, ReactNative, electron, anything), or connect it to any external provider (GraphQL, Firebase, REST), and nothing in the domain would need to change for it to do its job. In other words, our goal here is to write domain code that would be easily interchangeable with a different application (primary) or a different infra (secondary).

Note that, even if you're certain that you won't ever need to make such a change in your application, just having this goal opens the path to a more maintainable, more testable, better organized codebase.

The domain directory will contain directories that reference the main data models used throughout the application. And inside those there will be a file with the same name as the directory containing a Class, also with the same name (with the uppercase). The domain directory will also be shared by whatever exceptions, types, enums or constants are referenced in the domain model.

Domain and business go hand in hand. Ideally, business experts should be able to read domain code and understand what it's doing. Indeed, the origin of the language used in domain code should be their business expertise. This because the wording should be common among everyone working in the project, not just the devs. The domain language should be shared between the experts, everyone working in the solution (usually the product team), and the code. In other words, domain language should be ubiquitous.

Note that there's no single person who is "the domain or business expert". It's just a catch-all concept for anyone that provides domain knowledge to the team implementing the solution. Could be a Product Owner, the CEO, a business dev, a customer service agent, an advisor, another dev...

Sometimes the hardest part of all this is deciding what is part of the domain and what isn't. I will be giving my tips on how to tackle this later. I can already say, however, that in my personal experience, whenever I get to implement a new feature or augment an existing one under this architecture, the fact that I have to think about this puts me in a better position than I would've been otherwise as a dev. It forces me to listen, to ask more questions, and to care about understanding the Domain, because that understanding directly informs the code that goes in the domain directory.

The better your understanding of the business (domain), the better the code you'll be able write.

This is probably the biggest advantage of domain driven architecture in the front: it forces devs to think about the domain for themselves, instead of blindly inheriting it from the backend. Truth is, in many cases, backend and frontend teams may have different considerations in mind when they make their decisions. As we'll see, not all the properties that exist in a Domain object as defined by the backend are necessarily required in the Domain object as implemented by the front. Considering each data property and thinking if/how it's going to be used by the front is part our responsibility as frontend devs.

Domain rules

All change to domain objects is encapsulated and happens in a controlled manner. There is only one way to create domain objects, only one way to access them, only one way that it can mutate. The goal of the architecture decisions with regards to domain objects is to protect it from manipulation anywhere outside this controlled manner. That's how the increasing complexity is managed. Let's see some code and discuss a few of these architecture decisions.

import { Unit } from "@/domain/ingredient/enums";
import type { IngredientProperties } from "@/domain/ingredient/types";
import { InvalidUnitForConversionException } from "@/domain/ingredient/exceptions/InvalidUnitForConversionException";
import { OUNCE_IN_GRAMS } from "@/domain/ingredient/constants";

export class Ingredient {
  private constructor(
    private readonly id: string,
    private readonly name: string,
    private quantity: number,
    private unit: Unit,
    private readonly updatedAt: Date
  ) {}

  static fromProperties(properties: IngredientProperties) {
    const { id, name, quantity, unit, updatedAt } = properties;
    return new Ingredient(id, name, quantity, unit, updatedAt);
  }

  get properties(): IngredientProperties {
    return {
      id: this.id,
      name: this.name,
      quantity: this.quantity,
      unit: this.unit,
      updatedAt: this.updatedAt,
    };
  }

  changeGramsToOunces() {
    if (this.unit !== Unit.g) {
      throw new InvalidUnitForConversionException(
        this.unit,
        Unit.oz,
        this.changeGramsToOunces.name
      );
    }

    const quantityInOunces = this.quantity / OUNCE_IN_GRAMS;
    this.unit = Unit.oz;
    this.quantity = quantityInOunces;
    return this;
  }
}

I tried to think of an example domain class with a useful method that uses a bit of all the ingredients I showed in the screenshot above (exceptions, types, enums, constants). Here is the codebase source. There's quite a few things to unpack here.

Domain properties are domain Types which represent the current state of the data in a domain object.
The constructor is private. We use domain properties to instantiate domain objects via a static method: static fromProperties(properties: IngredientProperties): Ingredient.
All properties in a domain class begin as private readonly. Only when it becomes apparent that a property needs to be able to change, then only that property is allowed to be editable.
The domain classes can throw exceptions. These exceptions tell developers "if you are seeing this, you screwed up somewhere else". They may also teach the developer something about the domain (like you can't convert mass to volume). Normally, if the method changeGramsToOunces is to be used in a form, for example, then the UI code is expected to include its own validation before passing it to the domain.
A domain method is the only place where the properties of a domain object can ever be mutated.
The way to access data from a domain instance is via the getter get properties(): IngredientProperties. However, as we'll soon see, your components will never access the properties of a domain object.

So how then, do components get access to the information in domain objects? This is where primary comes in. Primary is the tunnel that connects your components (UI), to the domain, and to your API and other external sources (secondary). We'll talk about all of that in the next article, this one is already too long as it is.

Repository

Before we go though, there's one last simple (yet important) piece of the domain puzzle I'd like to share with you now: the Repository.

All the data that your application handles is represented by domain repositories. Here's an example:

import type { Recipe } from "@/domain/recipe/Recipe";
import type { RecipeId, RecipeToSave } from "@/domain/recipe/types";
import type { UserId } from "@/domain/user/types";

export interface RecipeRepository {
  getRecipes(userId: UserId): Promise<Recipe[]>;

  getFavoriteRecipes(userId: UserId): Promise<Recipe[]>;

  createRecipe(userId: UserId, form: RecipeToSave): Promise<Recipe>;

  updateRecipe(recipeId: RecipeId, form: RecipeToSave): Promise<Recipe>;

  deleteRecipe(recipeId: RecipeId): Promise<void>;
}

The repository is simply an interface in which you define the contract that will be implemented by your infrastructure (secondary).

This contract is part of what allows you to copy your whole domain directory and paste in any other app or infra (from a Vue web app to an Electron desktop app, for example). Everything should continue to work as expected as long as the contract is implemented (almost, we'll discuss a caveat later).

The repository also provides developers new to the codebase an easy-to-parse overview of all the ways the domain can interact with external sources.

These are the rules of the repository:

It's an Interface of methods. It's not a Type because it will be implemented by a class (which we'll discuss in the second article).
Its methods may receive primitives, domain properties, and domain types as arguments.
Most importantly, they always return domain objects (or void);

This is as far as I'll go about the domain now. Next, on to the second article to discuss how the rest of your application can take advantage of this domain we've created.