Building Enterprise-grade GraphQL APIs with Domain-Driven Design and Clean Architecture

Rate this content
Bookmark
Slides

In this talk, we will explore how to build scalable and maintainable GraphQL APIs for enterprise applications using Domain-Driven Design and Clean Architecture patterns. We will discuss the importance of modularizing your API around the business domain and better subdomain organization. We will briefly go through the main components of a GraphQL API, including resolvers, domain layer, and database layer and how we've evolved them to our new architecture.

22 min
12 Dec, 2023

AI Generated Video Summary

Today's Talk focuses on building enterprise-grade GraphQL APIs with domain-driven design and clean architecture. The speaker shares their experience and emphasizes the importance of understanding the business domain and aligning software with business requirements. They discuss the layered approach of clean architecture and the benefits it provides for separation of concerns and testing. The Talk also covers the use of GraphQL schema merging and mappers to create a unified schema. The speaker concludes by highlighting the importance of constant observation, evaluation, and improvement in software development.

1. Introduction to Building GraphQL APIs

Short description:

Today, I'm going to talk about building enterprise-grade GraphQL APIs with domain-driven design and clean architecture. I'll share my experience of building a scalable and maintainable GraphQL API by embracing TypeScript, domain-driven design, and clean architecture. You can find me on social media and check out my blog and newsletter. I work for Ant, S6, an outsourcing consulting company based in Sofia, Bulgaria.

Hello everyone. I'm Peter, and today I'm going to talk about building enterprise-grade GraphQL APIs with domain-driven design and clean architecture. So a few words about myself. So as I said, I'm Peter Ivanov. Here is my handle, so you can find me on social media with this handle. And I also consider myself as a T-shaped developer. If you're not sure what's a T-shaped developer, you can check one of my latest blog posts on my personal website, peterivanov.me. And I also have a newsletter, the T-Shaped Dev. So if you're interested, you can check it out. And yeah, here are my links to LinkedIn and my GitHub account. I'm Ant, S6 is the company that I'm working for. We are an outsourcing consulting company based here in Sofia, Bulgaria. And the purpose of my presentation is to share my experience of building a scalable and maintainable GraphQL API by embracing TypeScript, domain-driven design and clean architecture.

2. Introduction to Architecture and GraphQL API

Short description:

Don't take everything I share in this presentation as absolute. We won't go into much detail about what's GraphQL, DDD and clean architecture. We are talking about backstadium.com, think of it like DigitalOcean or AWS for Mac infrastructure. Let's start with the first version of our architecture, two web applications, one public and one internal. The second version is the current version, with the whole business logic inside the GraphQL API. The GraphQL API is the central place for all business related logic. We have a single user, the GraphQL API, which makes it easier to refactor and improve the design of the whole database.

And I would like to start with a few disclaimers. And the first one is that don't take everything I share in this presentation as absolute, because software can be built in multiple ways. And also, since we have only 20 minutes for this presentation, we won't go into much detail about what's GraphQL, DDD and clean architecture, because we will focus on how to design and build our API.

And now, a few words about it to give you some context and what kind of software and what kind of business we are talking about. So we are talking about backstadium.com, and you can think of it like DigitalOcean or AWS for Mac infrastructure. So if you don't want to buy the physical Mac, the actual hardware, but you want to run something on Mac, you can go there and you can purchase virtually the Mac and its infrastructure. So basically, we have the same things that we have in DigitalOcean or AWS. So we have billing, we have accounts, companies, users and stuff like that. So just to give you what kind of context and what kind of software we are going to be building and we are going to talk about throughout the presentation.

And now let's start with the first version of our architecture. And here it is. So we have two web applications, one public and one internal. The public one is built with React, KXPHP, and the other one is built only with KXPHP. And those two services call directly either the database or third-party services. Very, very simple one. And now let's move to the second version of the architecture, and this is the current version of the architecture. And here it is. Again, we have those two web applications, but now the whole business logic is inside the so-called the GraphQL API. And here you can see the GraphQL API. We have some account management, billing management, you'll see what it is. And here we have the API which calls the database or third-party services. Don't worry. Now we're going to drill down and explore how we actually managed to accomplish this and how we did it.

The first question that we have to answer is why we need the GraphQL API and what's its purpose. And one of the core reasons is that it's the central place for all business related logic. This is the GraphQL API. And also in this, by introducing the GraphQL API, we have in this case the database. We have a single user, in our case the GraphQL API, which will make it easier to refactor and improve the design of the whole database. As you saw in the first version of architecture, we had two clients, but most of the time they are more old. And now a few words about technologies that we decided to use.

3. Introduction to DDD and Ubiquitous Language

Short description:

Here, we have Node.js, Express, TypeScript, Apollo Server, and GraphQL. Domain-driven design (DDD) emphasizes understanding the business domain, focusing on core business logic, and aligning software with business requirements. Strategic DDD involves implementing DDD as a software development practice, starting with the ubiquitous language and bounded context. The ubiquitous language is a common vocabulary used by all stakeholders, defining terms like accounts, users, card payment profiles, and invoices. Bounded context establishes logical boundaries within the domain, enabling efficient teamwork and a shared understanding of the domain language. An example in our case is the account management context, responsible for managing accounts and users.

And here very quickly, we have Node.js, Express, TypeScript, Apollo Server and GraphQL. Now what about the domain-driven design and why we decided to use it? First, what is domain-driven and what is that? One of the key things here is that domain-driven design, or DDD, emphasizes the importance of understanding the business domain. It also helps teams to focus on the core business logic, and also by embracing all that, it makes the software to align with the business requirements.

In our case, because the domain-driven design is a very, very broad topic. But there's one key thing here, it's the so-called strategic DDD. Strategic DDD means that you start implementing the domain-driven design practice, as a software development practice. You start by figuring out two things. The ubiquitous language and the bounded context. Now let's see what are these things.

Let's start with the ubiquitous language. Ubiquitous language is a common vocabulary and language used by everyone involved in the project. And as you can see, by having this common vocabulary that's used by everyone, by everyone we mean all stakeholders, like the users, domain experts and also the technical experts. Everyone involved in the project, part of a different kind of business let's say, the business domain, they talk and they use the same language. So everyone can understand everyone basically. That's the whole thing. And in our case, we defined several things that are part of the ubiquitous language. You can think of it like a dictionary, vocabulary, something like that. So we have accounts, basically the companies that are part of the system, the users or employees that are part of the company or the account. We have card payment profiles that are part of the account. So the companies can pay for what they use in the system. And we have invoices and some other stuff. But those four things we are going to talk throughout the whole presentation. That's why I added them here.

And now what about the bounded context? First, let's answer what is this. So bounded context is basically like a logical boundary between the different parts of the domain. And by having this logical boundary, we can enable teams to work more efficiently with a shared understanding of the domain language used in a specific area of the system. And now I'm going to give you a very brief example, in our case basically. So here the first thing that we have, like a logical boundary is the account management. The account management context, or domain, is responsible for, as you can imagine, managing the account. So here inside it we have account and user.

4. Introduction to Account and Billing Management

Short description:

The account represents the company, and the user represents an employee. Billing management handles everything related to billing, including car payment profiles and invoices. Clean architecture, with its layered approach, allows for better separation of concerns and easier testing and maintenance. However, it requires additional engineering effort. Our codebase follows the clean architecture principles, with layers pointing inward. We have three layers, excluding the abstracted database. Each bounded context, such as account management and billing management, has its own structure, starting with entities as plain JavaScript objects.

The account, as I said, you can imagine it like the company, and the user, you can imagine it like the employee that's part of the company. So every company can have multiple employees. And on the other hand we have billing management, and this part of the codebase, or the software, is responsible for managing everything that's related to the billing part. And here we have car payment profile, and we have invoices, that are part of the billing.

The main. And now let's move to the second thing, and it's the clean architecture. By thinking about clean architecture, you can think of it like layered architecture. And now you see why layered. Maybe this is the most famous and popular screenshot about clean architecture. And I would like to point out two very important things here. The first one is, as you can see, we have the different layers, the different circles, and each circle or layer is in a different color. And each layer is responsible for something for basically for one thing most of the time. And the second very important thing here to mention and to point out is that each layer points inward. So you can see the blue one points inward to the green one and then the green one points to the red one, etc. So we have one flow, like one direction of how those layers are pointing inward to the most inner one circle.

And now let's see why we decided to embrace this architecture and this principle to make our codebase in this way. One of the biggest advantages of this pattern is that it allows for better separation of concerns. It's very easy to test this way, and it's also very easy to maintain the whole codebase and the whole software in the future. But on the other hand, a big disadvantage is that it takes additional engineering effort to implement. So, yeah, it depends. And now let's see how we looked through the prism of the clean architecture and how we added it into our codebase, into our software. And here we are going to... I will show you the different layers that we have. As you can see, we have only three because the database is abstracted as an infrastructure. So we won't talk about the database. And yeah, let's see. And also it's important that, as I said, we have, let's say, two bounded contexts, account management and billing management. And this structure that I'm going to share now is the structure that we have for each bounded context. And let's start with the most inner circle, the yellow one. And here we have entities, and entities are just a plain JavaScript object.

5. Introduction to Layers and Services

Short description:

They don't have state and have a unique identifier. Domain services encapsulate business logic with entities. The green layer consists of application services that handle mutations and queries. Repositories are used for loading or updating domain data.

They don't have state. And they have unique identifier, like an ID. And domain services are just an encapsulation of some business logic that is handled with entities or something similar. Then the green layer, we have application services. And this is like, again, encapsulation of some business logic that is used in our system. We have mutation that are and also queries that are mapped. Maybe if you're familiar with GraphQL, this is the same thing. It's one-to-one relation. So nothing, I would say, strange here. We also have repositories and repositories are used for, let's say, loading or updating some entities, some domain data.

6. Introduction to GraphQL Schema and Architecture

Short description:

And now we are moving to the blue layer. Here we have the GraphQL schema. GraphQL enables the currency data fetching and improves the overall performance of our application. We have the GraphQL API implemented with the Polo server. Each bounded context defines its GraphQL schema, and we use Schema Merging to have a single schema referred to by our clients. Let's now jump to the code.

And now we are moving to the blue layer. Here we have the GraphQL schema. So each context defines its schema. We have also GraphQL resolvers and these GraphQL resolvers are responsible for mapping the GraphQL types with our domain types. And most of the time, the GraphQL type should map 1 to 1 with the entities. But don't worry, we will see this in an example, because this is just like a theory, but we will see the code.

And yeah, here we have also the REST API if it's needed and we have the module API. This is the public interface, the public API that is defined by each bounded context. The other context, the other domains can use it, can refer it. And in this way, the different contexts, the different domains, can communicate and talk with each other. And now GraphQL. And the GraphQL serves like an umbrella on top of all bounded context that I share and show you.

And a few words about GraphQL, what and why. So GraphQL enables the currency data fetching. It also exposes a single HTTP endpoint that responds to queries. And this way, clients can retrieve data from multiple context like an umbrella on top of them. And basically, with GraphQL, we can improve the overall performance of our application because we reduce the number of requests. And we also reduce the transfer data that is needed from our clients. And this is how we managed to accomplish this whole architecture.

As you can see, we have the GraphQL API. It's implemented with the Polo server and our web applications calls to HTTP request this GraphQL API. And inside this GraphQL API we have two bounded contexts that can communicate with each other through the module API's that they have defined. And also, each bounded context defines its GraphQL schema. And here we use a technique called Schema Merging that through merging of those two schemas we have only one schema that is actually referred from our clients. And then the GraphQL API calls the database and the third party services. And now I'm going to share an example with you. A very simple one. It's a public repository on my GitHub account. So because maybe there was a lot of theory here, but we needed it. And now I'm going to jump to the code.

7. Introduction to Source Code and Account Domain

Short description:

And since we don't have a lot of time to see everything in the repository, you can have a look. It's public. And now let's focus on the source. Here we have modules, account, and billing. They have the API and are referred from other modules. We also have CartPayment profiles defined under the account domain. Here we define everything related to the account, including the card payment profile field.

And since we don't have a lot of time to see everything in the repository, you can have a look. It's public. And so you can spend more time looking to the code.

And now let's focus on the source. So here the source is actually the source code of our application. And here we have modules. Modules or boundary context or domains is the same thing. It's different words, but with the same for the same thing. And here we have account. And here we have billing. And now let's see what we have under the account and under the billing.

As you can see, they have the API. Here this folder holds the module API. So this is what is exposed by this domain, by this module. And this is referred from the other modules. So they can communicate to each other. Here we have the domain folder. Here we have models, mutations, queries or services. These are the application services. Here we have the GraphQL. And now I would like to actually show you the GraphQL schema. And as you can see, here we have the type account. But as I said in the presentation, we also have CartPayment profiles. And now I'm going to show you where we actually define them. So we define them under — maybe I can split it like this, so it's more easy to see. As you can see, here we have type account. And under the type account, this is under the account domain, under the account module. Here we define everything that is related to the account. On the right, we have the type account. But here we define the card payment profile field.

8. Introduction to Schema Merging and Mappers

Short description:

The billing domain handles the field responsible for the account. The account and billing are organized in separate folders. The schema merging technique combines the type definitions of the schemas into one. The models represent the entities in a simple JavaScript application. Mappers are used to map third-party object shapes to our domain object shapes. Code.gen is used to map entities to GraphQL types.

Because this field is responsible, it should be handled by the billing domain. And for this principle, we do for all the things that are part in our software. So everything that is related to the account is under the account folder. And everything that is related to the billing is under the billing folder.

And then we have a simple script. Here you can see, build schema. And here we have the schema merging technique where we merge the type definitions of those two schemas. So in the end we have only one schema. Here this schema generated GraphQL. Okay, this is about a GraphQL schema.

And another thing that I want to show you, the models, as I said, here, these are the entities. And here, this is a very simple JavaScript application. The id is the identifier. And here the other stuff. The other fields that are part of the Carpean profiles. And, yeah, the query that I shared is like the map with the GraphQL query that we know. And here we also use the repository. So what we have under the repository. Yeah, so the repository, as I said, is for loading some data. And here another interesting thing is that we can use mappers because most of the time, especially for billing, we will use a third party service. And for this third party service, they will have payment profiles in one shape. Their object that is for the payment profile will be in one shape. However, in our system, most probably we want to have another shape for the payment profile. And here we can use the so-called mappers so we can map their object to our domain object. And this way we can have this consistency so we can use our object inside our codebase. And yeah, maybe one thing to point is that we also use code.gen here so we can map our entities, our domain objects to the GraphQL types. And this is used through those two mappers. But you can have a look in the GitHub repository. It's public, as I said. I have two more slides, like a recap.

9. Lessons and Conclusion

Short description:

Lessons from the journey: It's hard to get it right from the beginning. Constantly observe, evaluate, and make improvements. No need to implement DDD and clean architecture 100%. Make it suit your needs. Building software for a small business is challenging. Understand the business and its domain. Embrace domain-driven design and clean architecture. Agile architecture allows for fast iterations and solving real-life business problems. Thank you for joining my presentation!

And some lessons from the whole journey is that it's very hard to get it right from the beginning. So don't worry, observe, evaluate and look for improvements. And always schedule time for paying that, because what I shared now, this was not from going from version one to version two directly. There was a lot of refactoring, a lot of other like failures and mistakes. But constantly we were looking at what we had like detected and were trying to pay to solve it.

And also, there is no need to implement DDD and clean architecture 100 percent. As I showed you, we didn't do that. So make it suit your needs and experience. This is maybe the most important lesson from our presentation today.

As a recap, building software for a small business is not easy. We should understand the business and its domain. We used domain driven design and clean architecture to create a robust and scalable system. And in the end, the resulting agile architecture allows for fast iterations and quick changes to the requirements, while the domain is being explored. In total, we have by embracing those software development practices that I shared. And in the end, we are modeling software to solve complex real life business problems.

And here I also added a couple of resources. And yeah, I hope that you are not tired, that you are not very bored and exhausted. And yeah, this was the end of my presentation. I hope you liked it. You can find the slides and the other materials like the GitHub repo on my public website. If you scan this QR code, you'll go straight to my website and you can find there the slides. So thank you a lot for joining my presentation. I hope you liked it. You can also leave me some feedback on social media so I can improve in the future. And yeah, thank you so much.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

GraphQL Galaxy 2021GraphQL Galaxy 2021
32 min
From GraphQL Zero to GraphQL Hero with RedwoodJS
We all love GraphQL, but it can be daunting to get a server up and running and keep your code organized, maintainable, and testable over the long term. No more! Come watch as I go from an empty directory to a fully fledged GraphQL API in minutes flat. Plus, see how easy it is to use and create directives to clean up your code even more. You're gonna love GraphQL even more once you make things Redwood Easy!
Vue.js London Live 2021Vue.js London Live 2021
24 min
Local State and Server Cache: Finding a Balance
How many times did you implement the same flow in your application: check, if data is already fetched from the server, if yes - render the data, if not - fetch this data and then render it? I think I've done it more than ten times myself and I've seen the question about this flow more than fifty times. Unfortunately, our go-to state management library, Vuex, doesn't provide any solution for this.For GraphQL-based application, there was an alternative to use Apollo client that provided tools for working with the cache. But what if you use REST? Luckily, now we have a Vue alternative to a react-query library that provides a nice solution for working with server cache. In this talk, I will explain the distinction between local application state and local server cache and do some live coding to show how to work with the latter.
GraphQL Galaxy 2022GraphQL Galaxy 2022
29 min
Rock Solid React and GraphQL Apps for People in a Hurry
In this talk, we'll look at some of the modern options for building a full-stack React and GraphQL app with strong conventions and how this can be of enormous benefit to you and your team. We'll focus specifically on RedwoodJS, a full stack React framework that is often called 'Ruby on Rails for React'.
GraphQL Galaxy 2022GraphQL Galaxy 2022
16 min
Step aside resolvers: a new approach to GraphQL execution
Though GraphQL is declarative, resolvers operate field-by-field, layer-by-layer, often resulting in unnecessary work for your business logic even when using techniques such as DataLoader. In this talk, Benjie will introduce his vision for a new general-purpose GraphQL execution strategy whose holistic approach could lead to significant efficiency and scalability gains for all GraphQL APIs.

Workshops on related topic

GraphQL Galaxy 2021GraphQL Galaxy 2021
140 min
Build with SvelteKit and GraphQL
Featured WorkshopFree
Have you ever thought about building something that doesn't require a lot of boilerplate with a tiny bundle size? In this workshop, Scott Spence will go from hello world to covering routing and using endpoints in SvelteKit. You'll set up a backend GraphQL API then use GraphQL queries with SvelteKit to display the GraphQL API data. You'll build a fast secure project that uses SvelteKit's features, then deploy it as a fully static site. This course is for the Svelte curious who haven't had extensive experience with SvelteKit and want a deeper understanding of how to use it in practical applications.

Table of contents:
- Kick-off and Svelte introduction
- Initialise frontend project
- Tour of the SvelteKit skeleton project
- Configure backend project
- Query Data with GraphQL
- Fetching data to the frontend with GraphQL
- Styling
- Svelte directives
- Routing in SvelteKit
- Endpoints in SvelteKit
- Deploying to Netlify
- Navigation
- Mutations in GraphCMS
- Sending GraphQL Mutations via SvelteKit
- Q&A
React Advanced Conference 2022React Advanced Conference 2022
95 min
End-To-End Type Safety with React, GraphQL & Prisma
Featured WorkshopFree
In this workshop, you will get a first-hand look at what end-to-end type safety is and why it is important. To accomplish this, you’ll be building a GraphQL API using modern, relevant tools which will be consumed by a React client.
Prerequisites: - Node.js installed on your machine (12.2.X / 14.X)- It is recommended (but not required) to use VS Code for the practical tasks- An IDE installed (VSCode recommended)- (Good to have)*A basic understanding of Node.js, React, and TypeScript
GraphQL Galaxy 2022GraphQL Galaxy 2022
112 min
GraphQL for React Developers
Featured Workshop
There are many advantages to using GraphQL as a datasource for frontend development, compared to REST APIs. We developers in example need to write a lot of imperative code to retrieve data to display in our applications and handle state. With GraphQL you cannot only decrease the amount of code needed around data fetching and state-management you'll also get increased flexibility, better performance and most of all an improved developer experience. In this workshop you'll learn how GraphQL can improve your work as a frontend developer and how to handle GraphQL in your frontend React application.
React Summit 2022React Summit 2022
173 min
Build a Headless WordPress App with Next.js and WPGraphQL
WorkshopFree
In this workshop, you’ll learn how to build a Next.js app that uses Apollo Client to fetch data from a headless WordPress backend and use it to render the pages of your app. You’ll learn when you should consider a headless WordPress architecture, how to turn a WordPress backend into a GraphQL server, how to compose queries using the GraphiQL IDE, how to colocate GraphQL fragments with your components, and more.
GraphQL Galaxy 2020GraphQL Galaxy 2020
106 min
Relational Database Modeling for GraphQL
WorkshopFree
In this workshop we'll dig deeper into data modeling. We'll start with a discussion about various database types and how they map to GraphQL. Once that groundwork is laid out, the focus will shift to specific types of databases and how to build data models that work best for GraphQL within various scenarios.
Table of contentsPart 1 - Hour 1      a. Relational Database Data Modeling      b. Comparing Relational and NoSQL Databases      c. GraphQL with the Database in mindPart 2 - Hour 2      a. Designing Relational Data Models      b. Relationship, Building MultijoinsTables      c. GraphQL & Relational Data Modeling Query Complexities
Prerequisites      a. Data modeling tool. The trainer will be using dbdiagram      b. Postgres, albeit no need to install this locally, as I'll be using a Postgres Dicker image, from Docker Hub for all examples      c. Hasura
GraphQL Galaxy 2021GraphQL Galaxy 2021
48 min
Building GraphQL APIs on top of Ethereum with The Graph
WorkshopFree
The Graph is an indexing protocol for querying networks like Ethereum, IPFS, and other blockchains. Anyone can build and publish open APIs, called subgraphs, making data easily accessible.

In this workshop you’ll learn how to build a subgraph that indexes NFT blockchain data from the Foundation smart contract. We’ll deploy the API, and learn how to perform queries to retrieve data using various types of data access patterns, implementing filters and sorting.

By the end of the workshop, you should understand how to build and deploy performant APIs to The Graph to index data from any smart contract deployed to Ethereum.