The other half is making something scalable and maintainable. One aspect of that is the ability to monitor your services.

This is what we will learn today using the help of software provided by Elastic. This is the company that originally made ElasticSearch, but which now provides a suite of different tools for search, observability, logging and much more.

For this article, we will specifically use the Elastic Application Performance Monitoring (APM) tool.

Table of Contents

• Prerequisites
• Why Should you Monitor Your Services?
• What is Elastic Application Performance Monitoring?
• How to set up APM
• Conclusion

Prerequisites

This article is strictly about Elastic APM. So, I assume you just want to connect it to your Node.js application.

I also assume you have Docker and Docker Compose installed locally and know how to use them.

You can find the code for this article here.

Why Should you Monitor Your Services?

If your software is successful (meaning you have users), then you may want to monitor your services for a few reasons.

Let's go over them in the following sections.

You want to know the status of your services

If your services are down, you want to know about it first. You don't want your users to be the ones to notify you.

To help with that, you can add alerts based on some criteria, such as:

• If there are more than 10 status code 500 errors in the last 5 minutes.
• If the latency of your services goes above some threshold (such as 1 second).

You can't improve something you don't measure.

If you want to optimize something, then you first have to measure it.

Find the hotspots and fix them. But to be able to find these, you must first monitor your services.

This will benefit you in two ways:

The first way is that you can define your SLOs (Service Level Objectives), which are goals that you would want to have for your services.

For example:

• Uptime Objectives – I want my services to be up 99.9% of the time.
• Latency Objectives – I want the P99 (99th percentile) of my requests to be completed in less than 1 second.

SLOs then help you define your SLAs (Service Level Agreements) which are promises you make to your customer. These promises increase the value that you provide to them.

Examples of SLAs include:

• Uptime Guarantee – Our services will be up 99.9% of the time. If not, then we would refund you (Every company has their own refunding model – for example, AWS will give credits back for all the time affected, while other companies will simply reimburse you).
• Latency Guarantee – Our P99 is lower than 200ms. If not, then there will be repercussions.

On to our final point.

Metrics don't always have to be technical

We can measure user behavior.

Things such as how long they stay on a specific page or some domain level things which are special for the business.

These metrics allows us to make data driven decisions.

For example, if you see your users not completing some sort of form, then you would decide that there is something wrong with it and fix it.

Another example would be that if your landing page isn't making a lot of sales then you would decide to do something about it.

What is Elastic Application Performance Monitoring?

Elastic Application Performance Monitoring (APM) is a tool that is used to monitor your application built on top of the Elastic Stack.

Here are some of its features:

• Real Time Monitoring – APM collects metrics on the fly, so you can see the status of your services in real-time.
• Detailed Monitoring – APM collects detailed information about requests such as response time, database queries, calls to caches, external HTTP requests, and more.
• System Metrics – APM automatically picks up basic host level metrics and agent specific metrics, like .NET metrics from the .NET agent. It also collects metrics such as CPU usage and more.
• Collects Errors – APM automatically collects unhandled errors and exceptions. They are grouped based on the stack trace, so you can identify new errors as they appear.
• Tracing – APM allows you to trace requests across microservices that have APM set up.
• Support – APM supports almost all popular programming languages and frameworks.

How to Set Up APM

Now that we know what APM is and how it works, let's set it up with a Node agent locally. For this we need to go through two steps.

Step 1: Set Up ELK Locally

Setting up the Elastic Stack (ELK) locally can be a pain. There are so many different services and you have to configure them all to work together.

Thankfully, other people have noticed this problem and created pre-configured Docker setup for ELK.

For the most up to date information, follow the guide here.

Here's a TLDR version:

1. git clone https://github.com/sherifabdlnaby/elastdocker.git
2. cd elastdocker
3. make setup
4. make all

At this point, you should have all the required services up and running. Most notably the three most important ones are:

• ElasticSearch which is the heart of all of this is running at port 9200.
• Kibana which is our dashboard running at port 5601.
• APM server which picks up the metrics running at port 8200.

If you want to login to Kibana, here are the credentials:

• Username: elastic
• Password: changeme

Step 2: Set Up Node Agent

Okay, now that we have ELK set up, let's set things up from the client side.

The first step is to add the APM node agent package. Install that using the following command:

npm install elastic-apm-node --save

Here's an important note. The agent must be started before all your other modules.

So, most likely you would have to start it in your application main file (usually index.js, server.js or app.js) at the top.

Here's an example for an Express application:

const apm = require('elastic-apm-node').start({
  serviceName: 'node-application',
  secretToken: 'secrettokengoeshere',
  verifyServerCert: false,
  serverUrl: 'https://127.0.0.1:8200',
})

const app = require('express')()

app.get('/', function (req, res) {
  res.send('Hello World!')
})

app.listen(3000)

Let's break down the configuration:

• serviceName: name of your application.
• secretToken: token required to authenticate the application to APM server. (The default token that is preconfigured from our docker-compose files is secrettokengoeshere)
• verifyServerCert: as we are running this locally, we don't want to verify certificates.
• serverUrl: URL of our APM server.

All that's left now is to run your application and play around with it a little for it to send some metrics.

Then go to Kibana at https://localhost:5601/.

Under Observability, click on APM.

You will find your application and it will look something like this:

Elastic APM Dashboard

Conclusion

In summary: creating features is half the battle – the other half is monitoring and maintaining them.

You can use Elastic's out the box solution Application Performance Monitoring tool to monitor your application.

I hope you learned something today and if you have any questions feel free to ask me on Twitter (or X) @tamerlan_dev.

Thanks for reading.

There's always a new frontend framework to learn, or a new database or language that's a variation of another language. It's never ending and feels like you always have to keep up.

But it doesn't have to be this way.

Everything is Built From the Fundamentals

If you learn the fundamentals, then everything else will become easier.

For example, if you learn how the TCP/IP protocol works, then from that you can easily learn all the other protocols that are built on top of it.

You're essentially having to cover less ground. The more fundamentals you know, the less you will struggle learning new things.

I believe there are 10 core subjects which, if you learn them, will give you a solid foundation.

Why Should You Learn These Key Concepts?

Learning the fundamentals will really put you in the top 5% of all programmers.

If we look at it from a different perspective, here's a great quote from Ras Bodik.

Don’t be a boilerplate programmer. Instead, build tools for users and other programmers. Take historical note of textile and steel industries: do you want to build machines and tools, or do you want to operate those machines?

But There are a Million Different Courses to Choose From

Well, look no further.

Below, I've compiled a bunch of helpful resources on each subject – with some alternatives, of course. So you can focus on learning and not on mindlessly researching which books/videos/courses are the best.

A few notes

This article is well-suited for self-taught developers or developers who don't feel quite comfortable with certain computer science concepts.

If you are learning to program for the first time, I would recommend r/learnprogramming community on Reddit.

This article was heavily inspired by Oz Nova and Myles Byrne who authored the site teachyourselfcs.com. If you enjoy this article, feel free to check out and share their site.

Table of Contents

• Programming
• Computer Architecture
• Algorithms and Data Structures
• Math for Computer Science
• Operating Systems
• Computer Networking
• Databases
• Languages and Compilers
• Distributed Systems
• Web Security
• Conclusion

Programming

Source

I'm not talking about syntax here. But actually programming or problem solving. Things such as abstraction, functions as data, recursion, and the different kinds of programming paradigms (object-oriented, functional, and declarative).

The book I recommend to learn programming is Structures and Interpretations of Computer Programs (SICP) (It's also known as the wizard book).

The book is free and has a set of MIT lectures. But the MIT lectures are a bit hard to watch due to the poor quality of that time (2005). So I recommend Brian Harvey’s SICP lectures (for the 61A course at Berkeley) instead.

Why this book?

Because this book focuses on the big picture.

It doesn't care about the programming language. It uses a variation of Lisp called Scheme. Scheme is very easy to learn (you can probably learn it in less than an hour), so it let's you focus on ideas not syntax.

Because of its simplicity, it makes it possible to examine different programming paradigms. It's a functional first approach, but you can implement your own OOP.

Scheme is a great language for teaching because it takes the focus away from the language and puts it on the big ideas.

If you're worried about it not being used in the industry, it's ok – you can always learn a more commonly-used programming languages after you grasp these high-level concepts.

But what if I REALLY don't want to learn Scheme?

Okay, you can follow the new version of the book which uses Python. The book is called Composing Programs. It also has its own set of lectures.

But, I highly recommend at least trying to do the Scheme version. It's just magical once you get it.

Okay, I've tried it but it's really hard

Yes, I understand.

Some of you will find SICP a bit too hard. It's not meant for purely beginner programmers.

If that's the case, then I would recommend How to Design Programs (HTDP). It uses a language very similar to Scheme and is generally more slower paced. You can use this book and its course on edX.

Tips on Studying

Don't read these books like a story.

It's not meant to be read cover to cover. Instead, focus on the exercises. You don't have to do them all, but just make sure you know how to solve most of them.

The lectures are optional and only needed if they help. It's really up to you.

Additional Resources

• Virtual meetups that talk about SICP
• Racket (IDE for Scheme) (Checkout this StackOverFlow answer for Scheme setup)

Computer Architecture

Source

You wrote some code and it magically runs.

How does that work? Well, this is what you will learn with computer architecture. This is by far the most neglected subject by most self taught engineers.

As engineers, we don't believe in magic. We have to unravel the magic behind computers. You will also learn some useful stuff such as:

• What is the L1, L2 cache?
• Why does cyberpunk lag?

The book I recommend here is Computer Systems: A Programmer's Perspective. I would also recommend an introductory course that will cover chapters 1-6 of the book (That was made by the authors of the book).

But there's a catch

This book is not meant to be read cover to cover. It has a lot of content, that may not well be presented in the optimal order.

So I recommend that you follow the course and do the labs.

What if I find it too hard?

A lot of people will find the content a bit heavy, so to ease into it, I would recommend doing the following:

• Read Code: The Hidden Language of Computer Hardware and Software\
• Read this handbook on Software Architecture
• Watch all 4 videos of Exploring How Computers Work
• Watch all 41 videos of Crash Course: Computer Science
• Take the course NAnd2Tetris
• Learn a bit of C by reading the book: C Programming a Modern Approach

Once you finish that you can then come back to Computer Systems: A Programmers Perspective.

Data Structures and Algorithms

Source

Everyone wants to work at a FAANG company, but no one wants to learn Data Structures and Algorithms.

Nevertheless, I don't want you to learn these just because of technical interviews. Data structures and algorithms are important because they help build your problem solving skills.

There are many great books and courses on Data Structures and Algorithms but the one I would recommend is a book named The Algorithm Design Manual by Steven Skiena. You can also check out his course here.

Don't forget to practice

Same rules apply here. Don't just learn about data structures, but create them in whatever language you want. Don't just memorize algorithms but implement them and see where and how you can use them.

A good tip is solving some Leetcode problems while going through the book/course.

What if I find it too hard?

If you find the material a bit heavy, then I would recommend the following resources:

• Read the book: Grokking Algorithms
• Read the book: How to Solve It: A New Aspect of Mathematical Method

In general there are many different books/courses that teach Data Structures and Algorithms – Here are some other great resources:

• Data Structures and Algorithms course on freeCodeCamp
• Algorithms Illuminated
• Princeton Algorithms Course
• ThePrimegeans Data Structures and Algorithms Course
• MIT Introduction to Algorithms

Math for Computer Science

Don't worry, this is some random math photo found here

Many new developers skip this.

But, hear me out – computer science is essentially a branch of mathematics. Learning it will make you a better developer by honing your problem solving skills.

The most relevant area for CS is Discrete Mathematics

Discrete mathematics is the branch of mathematics that deals with countable or finite numbers.

The topics in discrete mathematics are many, but the ones which are relevant for CS are:

• Logic
• Combinatorics
• Discrete Probability
• Set Theory
• Graph Theory
• Number Theory

How to Study Discrete Mathematics

I would suggest starting with a set of lecture notes by László Lovász.

Professor Lovász notes are easier to digest than formal texts and are just generally fun. He starts of with a problem and solves it using discrete mathematics.

After that, you can take an MIT book called Mathematics for Computer Science. The book comes with video lectures that are freely available.

What if it's too hard?

Don't worry – sometimes you just have to accept that you won't always get it right away.

It's fine.

But if you feel like you're missing some fundamental knowledge, then it's a different story. The fundamental prerequisite subjects for discrete mathematics are:

• Algebra
• Geometry
• Calculas

There are many free resources, but the ones I would recommend are:

• Khan Academy
• College Algebra course
• Calculus 1 course
• Calculus 2 course

Operating Systems

Source

Remember when I told you that we as developers want to remove the magic in computing?

Same thing applies here – operating systems seem like some sort of magical black box. But they're not – it's just a lot of clever engineering.

If you know how these operating systems are built and work, then you will definitely be in a league of your own.

It's somewhat difficult to find good resources online for operating systems but the most recommend book is Operating Systems: Three Easy Pieces (OSTEP). There isn't any official video lecture online that fully covers the book but I found this playlist on YouTube.

Recommend Prerequisites

I would suggest learning computer architecture first and a little bit about C before embarking on the operating systems journey.

Optional Resources

Now, I recommend finishing OSTEP first and then checking out the other recommend resources. They are all optional.

• Want to build your own Linux system? Check out Linux from Scratch.
• Want an in-depth overview of Linux, MacOS, and Windows? Here's a handbook for you.
• Want to build your own OS? Check out OSDEV
• Want to build your own Sockets? Check out Beej's Guide to Network Programming

Computer Networking

Source

Since the dawn of the internet, computer networking has been one the most important subjects for software engineers.

If you don't know things like IP, TCP, UDP, HTTP, TLS, DNS, SMTP, and so on — then you should learn about computer networking (especially if you are a backend engineer).

The recommended book here is Computer Networking: A Top-Down Approach. You can also check out the video lectures from the author of the book himself.

But before beginning that I would recommend to check out this video crash course on computer networking from a bottom up approach. And here's a helpful tutorial that covers the basics well.

Databases

Source

Databases are somewhat new – they came around the 1970s and have since become integral parts of many applications.

I highly recommend the below courses from the CMU Database Group. They're all freely available on YouTube. I would recommend going through at least the first one.

1. Introduction To Databases
2. Database Seminars
3. Advanced Databases

Also, here's a great collection of resources to help you learn about SQL databases. And here's a free course on NoSQL databases.

Languages and Compilers

Source

You may know how to code in one or more programming languages.

But do you know how to create or design one? That's what you will learn by studying programming languages and compilers.

The recommended introductory book is called Crafting Interpreters.

After that you can move on to Compilers: Principles, Techniques & Tools, also called “the Dragon Book”. The book is covers a lot of topics so I highly recommend taking a course with it. The one I recommend is from Alex Aiken on edX.

And here's a helpful beginner-friendly tutorial on how the compiler works in C programming.

Distributed Systems

Source

If you choose to study only one subject from the list, make it distributed systems. It's the holy grail for tech companies, and if you want to get a developer job, you should be proficient about distributed systems.

My recommend path in learning the subject is:

1. Read the book: Understanding Distributed Systems
2. Read the book: Designing Data Intensive Applications also known as the "red book"
3. While reading the "red book", take its accompanying MIT course on YouTube.
4. Read the book: Software Architecture: The Hard Parts (Optional)
5. You can also check out my handbook about design patterns for distributed systems.

Web Security

Source

There have been a lot of security breaches in the last 2-3 years.

It's getting dangerous out there – and as a software engineer, knowing some fundamentals of web security will give you an edge.

The course I recommend first is CS253 Web Security by Stanford. It gives a comprehensive overview of web security. So expect topics like web app vulnerabilities, injection, denial-of-service, and many more.

You can also review these common vulnerabilities and learn how to prevent attacks that take advantage of them.

Later on, if you want, you could learn how to hack using pwn.college.

Conclusion

Learning all these subjects will take you a while, and will require consistent effort. But if you like what you do and are interested in the subject, then it should feel like play and not a chore.

Regardless of the subjects you choose to study. The most important tip I can give you is...

Don't be a passive learner

Don't just watch videos – do the exercises as well. Build the projects along with the tutorials.

Don't just read books but engage in the book by asking questions and doing your own research.

You want the information to stick, so you don't forget it. And to make it stick you have to actively engage in the subject.

I sincerely hope that I encouraged you to study some of these subjects. As always I want to end it of by thanking you for reading this article.

I wish you all the best.

The work was good but I always had this thought in the back of my mind:

"Man, I want to work on big systems such as ones for Google, Netflix, etc..."

I was 19 and a junior developer, so cut me some slack here.

I didn't even know the term distributed systems until one of my colleagues started talking about it.

Then I researched it – I researched a lot. It seemed very complicated, and I felt very stupid.

But I was excited.

I studied this concept of distributed systems for a while, but didn't fully understand it until I saw it all in action a few years later.

Now that I have some experience, I would like to share with you what I know about distributed systems.

Prerequisite Knowledge

The topics I'll be discussing here may be a bit advanced for beginner programmers. To help you be prepared, here's what I assume you know:

• Mid Level Programming (any language will work)
• Basic Computer Networking (TCP/IP, network protocols, and so on)
• Basic Data Structures and Algorithms (Big O notation, search, sort, and so on)
• Databases (Relational, NoSQL, and so on)

If that sounds like a lot, don't feel discouraged.

Here are some resources that can help you brush up on some of these more specific topics:

1. Learn how computer networks work in this free course
2. Learn about data structures and algorithms in this free course
3. Learn about relational databases here, and about NoSQL databases here.

Here's What We'll Cover:

1. What are Distributed Systems?
2. Common Challenges in Distributed Systems
3. Command and Query Responsibility Segregation (CQRS) Pattern
4. Two-Phase Commit (2PC) Pattern
5. Saga Pattern
6. Replicated Load-Balanced Services (RLBS) Pattern
7. Sharded Services Pattern
8. Sidecar Pattern
9. Write-Ahead Log Technique
10. Split-Brain Pattern
11. Hinted Handoff Pattern
12. Read Repair Pattern
13. Service Registry Pattern
14. Circuit Breaker Pattern
15. Leader Election Pattern
16. Bulk Head Pattern
17. Retry Pattern
18. Scatter Gather Pattern
19. Bloom Filters Data Structure

What are Distributed Systems?

Netflix Architecture. Source

When I started my career, I worked as a front-end developer for an agency.

We used to get requests from clients and then we'd just build their site.

Back then I didn't fully understand the architecture and infrastructure behind the stuff I was building.

Thinking back about it now, it wasn't complicated at all.

We had one backend service written in PHP and Yii2 (PHP Framework) and a frontend written in JavaScript and React.

All of this was deployed to one server hosted in ps.kz (Kazakhstan Hosting Provider) and exposed to the internet using NGINX as a web server.

This architecture works for most projects. But once your application becomes more complex and popular, the cracks begin to show.

You get problems such as:

• Complexity – Codebase is too large and too complex for one person to mentally handle. It's also hard to create new features and maintain old ones.
• Performance Issues – The popularity of your app caused it to have a lot of network traffic and it has proven to be too much for your single server. Because of that, the application has started to face performance issues.
• Inflexibility – Having a single codebase means that you are stuck with the technology stack that you began with. If you want to change it, then you will either have to rewrite the whole thing in another language or break up the app.
• Fragile System – Code being highly coupled together means that if any of the functionality breaks then the whole application will break. This leads to more downtime which will lose the business more money.

There are many ways to optimize a monolithic application, and it can go very far. Many big tech companies such as Netflix, Google, and Facebook (Meta) started off as monolithic applications because they're easier to launch.

But they all began facing problems with monoliths at scale and had to find a way to fix it.

What did they do? They restructured their architectures. So instead of having a single super service that contained all the features of their business, they now had multiple independent services that talk to each other.

This is the basis of distributed systems.

Some people mistake distributed systems for microservices. And it's true – microservices are a distributed system. But distributed systems do not always follow the microservice architecture.

So with that in mind, let's come up with a proper definition for distributed systems:

A distributed system is a computing environment in which various components are spread across multiple computers (or other computing devices) on a network.

Common Challenges in Distributed Systems

Distributed systems are by far much more complex than monolithic ones.

That's why before migrating or starting a new project, you should ask the question:

Do I really need it?

If you decide that you do need a distributed system, then there are some common challenges you will face:

• Heterogeneity – Distributed systems allow us to use a wide range of different technologies. The problem lies in how we keep consistent communication between all the different services. Thus it is important to have common standards agreed upon and adopted to streamline the process.
• Scalability – Scaling is no easy task. There are many factors to keep in mind such as size, geography, and administration. There are many edge cases, each with their own pros and cons.
• Openness – Distributed systems are considered open if they can be extended and redeveloped.
• Transparency – Transparency refers to the distributed system's ability to conceal its complexity and give off the appearance of a single system.
• Concurrency – Distributed systems allow multiple services to use shared resources. Problems may arise when multiple services attempt to access the same resources at the same time. We use concurrency control to ensure that the system remains in a stable state.
• Security – Security is comprised of three key components: availability, integrity, and confidentiality.
• Failure Handling – There are many reasons for errors in a distributed system (for example, software, network, hardware, and so on...). The most important thing is how we handle those errors in a graceful way so that the system can self-heal.

Yea, designing robust and scalable distributed systems is not easy.

But you are not alone. Other smart people have faced similar problems and offer common solutions which are called design patterns.

Let's cover the most popular ones.

PS. We won't only cover patterns, but anything that helps in distributed systems. This may include data structures, algorithms, common scenarios, etc...

Command and Query Responsibility Segregation (CQRS) Pattern

Source

Imagine that you have an application with millions of users. You have multiple services that handle the backend, but as a single database.

The problem arises when you do reads and writes on this same database. Writes are a lot more expensive to compute than reads, and the system starts to suffer.

This is what the CQRS pattern solves.

It states that writes (commands) and reads (queries) should be separated. By separating writes and reads, we can allow developers to optimize each task separately.

For example, you might choose a high-performance database for write operations and a cache or search engine for read operations.

Pros

• Code Simplification – Reduces system complexity by separating writes and reads.
• Resource Optimizations – Optimizes resource usage by having a separate database for writes and reads.
• Scalability – Improves scalability for reads as you can simply add more database replicas.
• Reduce Number of Errors – By limiting the entities that can modify shared data, we can reduce the chances of unexpected modifications of data.

Cons

• Code Complexity – Adds code complexity by requiring developers to manage reads and writes separately.
• Increased Development Time – This can increase development time and cost (in the beginning only).
• Additional Infrastructure – This may require additional infrastructure to support separate read and write models.
• Increased Latency – It can cause increased latency when sending high-throughput queries.

Use Cases

CQRS is best used when an application's writes and reads have different performance requirements. But it is not always the best approach, and developers should carefully consider the pros and cons before adopting the pattern.

Here are some use cases that utilize the CQRS pattern:

• E-Commerce – Separate read models for product catalogs and recommendations, while the write side handles order processing and inventory management.
• Banks – Optimize read models for balance inquiries and reporting, while the write side handles transactions and calculations.
• Healthcare – CQRS can be used to optimize the reads for patient searches, medical record retrieval, and generating reports, while the write side manages data updates, scheduling, and treatment plans.
• Social Media –By applying CQRS, the read models can efficiently handle feed generation, personalized content recommendations, and user profile queries, while the write side handles content creation, updates, and engagement tracking.

Two-Phase Commit (2PC) Pattern

_Source_

2PC solves the problem of data consistency. When you have multiple services talking to a relational database, it's hard to keep the data consistent as one service can create a transaction while the other aborts it.

2PC is a protocol that ensures that all services commit or abort a transaction before it is completed.

It works in two phases. The first phase is the Prepare phase in which the transaction coordinator tells the service to prepare the data. Then comes the Commit phase, which signals the service to send the prepared data, and the transaction gets committed.

2PC systems make sure that all services are locked by default. This means that they can't just write to the database.

While locked, the services complete the Prepare stage to get their data ready. Then the transaction coordinator checks each service one-by-one to see if they have any prepared data.

If they do, then the service gets unlocked and the data gets committed. If not, then the transaction coordinator moves on to another service.

2PC ensures that only one service can operate at a time, which makes the process more resistant and consistent than CQRS.

Pros

• Data Consistency – Ensures data consistency in a distributed transaction environment.
• Fault Tolerance – Provides a mechanism to handle transaction failures and rollbacks.

Cons

• Blocking – The protocol can introduce delays or blocking in the system, as it may have to wait for unresponsive participants or resolve network issues before proceeding with the transaction.
• Single point of failure – Reliance on a single coordinator introduces a potential point of failure. If the coordinator fails, the protocol may be disrupted, leading to transaction failures or delays.
• Performance overhead – The additional communication rounds and coordination steps in the protocol introduce overhead, which can impact the overall performance, especially in scenarios with many participants or high network latency.
• Lack of scalability – As the number of participants increases, the coordination and communication overhead also increase, potentially limiting the scalability of the protocol.
• Blocking during recovery – The protocol may introduce blocking during recovery until the failed participant is back online, impacting system availability and responsiveness.

Use Cases

2PC is best used for systems that deal with important transaction operations that must be accurate.

Here are some use cases where the 2PC pattern would be beneficial:

• Distributed Databases – Coordinating transaction commits or aborts across multiple databases in a distributed database system.
• Financial Systems – Ensuring atomic and consistent transaction processing across banks, payment gateways, and financial institutions.
• E-commerce Platforms – Coordinating services like inventory management, payment processing, and order fulfillment for reliable and consistent transaction processing.
• Reservation Systems – Coordinating distributed resources and participants in reservation processes for consistency and atomicity.
• Distributed File Systems – Coordinating file operations across multiple nodes or servers in distributed file systems to maintain consistency.

Saga Pattern

So let's imagine that you have an e-commerce app that has three services, each with its own database.

You have an API for your merchants which is called /products to which you can add a product with all its information.

Whenever you create a product, you also have to create its price and meta-data. All three are managed in different services with different databases.

So, you implement the simple approach of:

Create product -> create price -> create meta-data

But what if you created a product but failed to create a price? How can one service know that there was a failed transaction of another service?

The saga pattern solves this problem.

There are two ways to implement sagas: orchestration and choreography.

Orchestration

Source

The first method is called Orchestration.

You have a central service that calls all the different services in the right order.

The central service makes sure that if there is a failure, it will know how to compensate for that by reverting transactions or logging the errors.

Pros

• Suitable for complex transactions that involve multiple services or new services added over time.
• Suitable when there is control over every participant in the process and control over the flow of activities.
• Doesn't introduce cyclical dependencies, because the orchestrator unilaterally depends on the saga participants.
• Services don't need to know about commands for other services. There is a clear separation of concerns which reduces complexity.

Cons

• Additional design complexity requires you to implement a coordination logic.
• If the orchestrator fails then the whole system fails.

When to Use Orchestration?

You should consider using this pattern:

• If you need a centralized service that coordinates of the workflow.
• If you want a clear and centralized view of the workflow which makes it easier to understand and manage the overall system behavior.
• If you have complex and dynamic workflows that require a high degree of coordination and centralized control.

Choreography

Source

On the other hand, the Choreography method doesn't use a central service. Instead, all communication between servers happens by events.

Services will react to events and will know what to do in case of success or failure.

So for our example above, when the user creates a product it will:

1. Create an event called product-created-successfully
2. Then the price service will react to the event by creating a price for the product and it will then create another event called price-created-successfully
3. The same logic applies to the meta-data service.

Pros

• Suitable for simple workflows that don't require complex coordination logic.
• Simple to implement because it doesn't require additional service implementation and maintenance.
• There is no single point of failure as responsibilities are distributed between the services.

Cons

• Difficult to debug because it's difficult to track which saga services listen to which commands.
• There's a risk of cyclic dependency between Saga services because they have to consume each other's commands.
• Integration testing is difficult because all services must be running to simulate a transaction.

When to Use Choreography:

You should consider using this pattern if:

• The application needs to maintain data consistency across multiple microservices without tight coupling.
• There are long-lived transactions and you don’t want other microservices to be blocked if one microservice runs for a long time.
• You need to be able to roll back if an operation fails in the sequence.

Replicated Load-Balanced Services (RLBS) Pattern

Source

This is essentially a load balancer – I don't know why they made it sound so intimidating.

A load balancer is software or hardware that distributes network traffic equally between a set of resources.

But that's not always the case – it can also route different routes to different services.

So for example:

• /frontend goes to the front-end service.
• /api goes to the backend service.

Pros

• Performance – Load balancing distributes the workload evenly across multiple resources, preventing any single resource from becoming overloaded. This leads to improved response times, reduced latency, and better overall performance for users or clients accessing the system.
• Scalability – Load balancing allows you to scale horizontally, meaning that instead of getting more powerful servers, you can get more servers.
• High availability – As said above, load balancing allows us to vertically scale which means we have multiple servers. If one server fails then the load balancer will detect that and traffic can be redirected to other working servers.
• Better resource utilization – Load balancing helps to optimize resource utilization by distributing traffic evenly across multiple servers or resources. This ensures that each server or resource is used efficiently, helping to reduce costs and maximize performance.

Cons

• Complexity – Implementing and configuring load balancing can be complicated especially for large scale systems.
• Single Point of Failure – While load balancers enhance system availability, they can also become a single point of failure. If the load balancer itself fails, it can cause a disruption in service for all resources behind it.
• Increased Overhead –Load balancers computations are not free, if they are not controlled then they can become a bottleneck to the entire system.
• Session Handling Challenges – Load balancing stateful applications is a bit tricky as you need to maintain sessions. It requires additional mechanisms such as sticky sessions or session synchronization, which adds complexity.

When to use load balancing

A load balancer is mainly used when:

• You have a high traffic website and you want to spread the load so that your servers don't fry.
• You have users from all over the world and want to serve them data from their closest location. You could have a server in Asia and another in Europe. The load balancer would then route all users from Asia to the Asian server and European users to the Europe server.
• You have a service orientated architecture with API's corresponding to different services. Load balancing can be used as a simple API gateway.

I've written a bunch of articles on load balancing, so feel free to check them out.

• How to set up NGINX load balancing: a step-by-step guide
• Load balancing in Kubernetes: a step-by-step guide
• Load balancing 101: How it works and why it matters for your platform

Sharded Services Pattern

Source

In the previous section, we talked about replicated services. Any request can be processed by any of the services. This is because they are replicas of one another.

This is good for stateless services. But what if you have a stateful service? Then a sharded approach would be more appropriate.

Sharded service only accepts certain kinds of requests.

For example, you may have one shard service accept all caching requests while another shard service accepts high-priority requests.

But, how do we implement this?

Well, if we are strictly talking about application services then you could go with the service oriented architecture approach. You could have multiple services developed and deployed independently.

Then you could use a load balancer to route requests by URL path to the appropriate service.

PS. Sharding is not only used for application services but can be used for databases, caches, CDNs, etc...

Pros:

• Scalability – Sharding allows you to distribute load across multiple nodes or servers, thus enabling horizontal scaling. As your workload increases, you can just add more shards.
• Performance – A single node doesn't have to handle all requests especially if it is computationally heavy. Each node can take in a subset of requests, improving the systems performance.
• Cost-effectiveness – Sharding can be a cost-effective solution for scaling your system. Instead of investing in a single, high-capacity server, you can use commodity hardware and distribute the workload across multiple, less expensive servers.
• Fault isolation – Sharding provides a level of fault isolation. If one shard or node fails, the remaining shards can continue serving requests.

Cons:

• Complexity – Sharding is not easy to implement. It requires careful planning and design to handle data distribution, consistency, and query coordination.
• Operational overhead – Managing a sharded system involves additional operational tasks such as monitoring, maintenance, and backup, which can require more resources and expertise.

Use Cases

The Sharded Services Pattern is typically used in the following scenarios:

• Performance Requirements – If your system is dealing with large data volumes or high read/write workloads that a single server cannot handle, sharding can distribute the workload across multiple shards. This enables parallel processing and improving overall performance.
• Scalability requirements – When you anticipate the need for horizontal scalability in the future, sharding can be implemented from the beginning to provide the flexibility to add more shards and scale the system as the workload grows.
• Cost considerations – If vertical scaling (upgrading to more powerful hardware) becomes cost-prohibitive, sharding offers a cost-effective alternative by distributing the workload across multiple, less expensive servers or nodes.
• Geographical distribution – Sharding can be beneficial when you need to distribute data across different geographical locations or data centers, allowing for improved performance and reduced latency for users in different regions.

But keep in mind that there must be careful considerations when sharding your services as it is very complex and expensive to implement and revert.

Sidecar Pattern

Source

In a service-oriented architecture, you might have a lot of common functionalities – things such as error handling, logging, monitoring, and configuration.

In the past, there were two ways to solve this problem:

Implement common functionalities within the service

The problem with this approach is that the utilities are tightly linked and run within the same process by making efficient use of the shared resources. This makes the components interdependent.

If one functionality fails then this can lead to another functionality failing or the whole service failing.

Implement common functionalities in a separate service

This may seem a good approach because the utilities can be implemented in any language and it does not share resources with other services.

The downsides are that it adds latency to the application when we deploy two services on different containers, and it adds complexity in terms of hosting, deployment, and management.

How can we do it better?

One method is using the side-car pattern. It states that a container should only address a single concern and do it well.

So to do that, we have a single node (virtual or physical machine) with two containers.

The first is the application container which contains the business logic. The second container, usually called the sidecar, is used to extend/enhance the functionality of the application container.

Now you might ask, "But, how is this useful?"

You should keep in mind that the sidecar service runs in the same node as the application container. So they share the same resources (like filesystem, memory, network, and so on...)

An example

Let's say you have a legacy application that generates logs and saves them in a volume (persisted data) and you want to extract them into an external platform such as ELK.

One way to do this is just extending the main application. But that's difficult due to the messy code.

So you decide to go with the sidecar method and develop a utility service that:

• Captures the logs from the volume.
• Transfers the logs into Elastic.

The architecture of the node would look something like this:

Source

Hooray, you haven't changed any code in the application and you extended its functionality by plugging in a sidecar.

Heck, you can even plug this log aggregator sidecar into other applications.

Pros:

• Modularity – Sidecar allows you to develop and maintain utility functions independently.
• Scalability – If there is too much load on the sidecar, you can easily horizontally scale it by adding more containers.
• Isolation – The sidecar is isolated from the main application, providing an additional layer of security.

Cons:

• Complexity – It requires extra management of multiple containers and their dependencies.
• Resource overhead – Because we have an extra container, this can increase the overall resource usage of the application.
• Coordination – The sidecar must be coordinated in a way that it works correctly with the main application which increases complexity.
• Debugging – Debugging is more difficult with the sidecar pattern, as it requires tracing the interactions between the main application and the sidecar.

Use Cases

The sidecar pattern is useful when you want to add additional functionality to the application without touching the core business logic code.

By deploying the sidecar, the core logic can remain lightweight and focus on its primary task while the sidecar can handle additional functionality.

If need be, you can reuse the sidecar for other applications too.

Now that we know when to use this pattern, let's look at some use cases where it is beneficial:

• Logging and Monitoring – The sidecar container collects logs and metrics from the main container, providing centralized storage and real-time monitoring for improved observability.
• Caching – The sidecar container caches frequently accessed data or responses, enhancing performance by reducing the need for repeated requests to external services.
• Service Discovery and Load Balancing – The sidecar container registers the main container with a service discovery system, enabling load balancing and fault tolerance across multiple instances of the main container.
• Security and Authentication – The sidecar container handles authentication tasks, offloading responsibilities like OAuth, JWT verification, or certificate management from the main container.
• Data Transformation and Integration – The sidecar container performs data transformation and integration tasks, facilitating seamless communication and synchronization between the main container and external systems.
• Proxy and Gateway – The sidecar container acts as a proxy or gateway, providing functionalities like rate limiting, SSL termination, or protocol translation for enhanced communication capabilities.
• Performance Optimization – The sidecar container handles CPU-intensive tasks or background processes, optimizing resource usage and improving the main container's performance.

Write-Ahead Log Technique

Imagine this: you are working on a service that is connected to a database with sensitive user information.

One day, the server crashes. Your database crashes. All the data is gone, apart from the backups.

You sync the database with the backup, but the backup is not up to date. It's 1 day old. You sit and cry in the corner.

Well thankfully, that will most likely never happen.

Because most databases have something called a write-ahead log (WAL).

What is a write-ahead log?

A write-ahead log is a popular technique used to preserve:

• Atomicity – Every transaction is treated as a single unit. Either the entire transaction is executed, or none of it is executed. This ensures that the data does not get corrupted or lost.
• Durability – Ensures that the data will not be lost, even in an event of a system failure.

But how does it work?

A WAL stores every change you made onto a file on a hard disk.

So for example, let's say you created your own in-memory database called KVStore. In case of system failure, you want:

• Data to not be lost.
• Data to be recovered onto memory.

So you decide to implement a write-ahead log.

Every time you do any transaction (SET or REMOVE), the command will be logged into a file on the hard disk. This allows us to recover the data in case of system failure. The memory will be flushed, but the log is still stored in the hard drive.

The overall architecture would look something like this:

Source

It's not all sunshine and rainbows

As useful as it is, WAL is not easy to implement. There are many nuances, but the most common ones are:

Performance

If you use standard file-handling libraries in most programming languages, you would most likely "flush" the file onto the hard disk.

Flushing every log will give you a strong guarantee of durability. But this severely limits performance and can quickly become a bottleneck.

You might ask, "why don't we delay flushing or do it asynchronously?"

Well, this might improve performance but at the risk of losing entries from the log if the server crashes before entries are flushed.

The best practice here is to implement techniques like Batching, to limit the impact of the flush operation.

Data Corruption

The other consideration is that we have to make sure that corrupted log files are detected.

To handle this, save log files via CRC (Cyclic Redundancy Check) records, which validates the files when read.

Storage

Single Log files can be difficult to manage and can consume all the available storage.

To handle this issue, use techniques like:

• Segmented Log – Split the single log into multiple segments.
• Low-Water Mark – This technique tells us which portion of the logs can be safely discarded.

These two techniques are used together as they both complement each other.

Duplicate Entries

WALs are append-only, meaning that you can only add data. Because of this behavior, we might have duplicate entries. So when the log is applied, it needs to make sure that the duplicates are ignored.

One way to solve this is to use a hashmap, where updates to the same key are idempotent. If not, then there needs to be a mechanism to mark each transaction with a unique identifier and detect duplicates.

Use Cases

Overall WALs are mostly used in databases but can be beneficial in other areas:

Write-ahead logs (WALs) are widely used in various systems and databases. Here are some common use cases for write-ahead logs:

• File Systems – File systems can employ write-ahead logging to maintain data consistency. By logging changes before applying them to the file system, WALs allow for crash recovery and help prevent data corruption in case of system failures.
• Message Queues and Event Sourcing – Write-ahead logs are often used in message queues and event sourcing architectures. The logs serve as a reliable and ordered record of events, allowing for reliable message delivery, event replay, and system state restoration.
• Distributed Systems – Distributed systems that need to maintain consistency across multiple nodes can benefit from write-ahead logs. By coordinating log replication and replay, WALs help synchronize data updates and ensure consistency in distributed environments.

Split-Brain Pattern

Source

That's definitely an interesting name, isn't it? It might make you think of the two halves of the brain.

Well, it is actually somewhat similar.

A split brain in distributed systems happens when nodes in a distributed system become disconnected from each other but still continue to operate.

Split brain? Nodes working independently when they should work together? Sound similar? I hope so.

Anyways, the biggest problem with this is that it causes:

• Data Inconsistency
• Competing for resources

This will usually shut the cluster off while developers try to fix things. This causes downtime which makes the business lose money.

What's the fix?

One fix is using a generational number. Every time a leader is elected, the generation number gets incremented.

For example, if the old leader had a generational number of one, then the second leader will have a generational number of two.

The generation number is included in every request, and now clients can just trust the leader with the highest number.

But keep in mind that the generational number must be persisted on disk.

One way to do that is using a Write Ahead Log. See, things are connected to each other.

This solution is categorized as a leader election but there are others:

• Quorum-based Consensus – Use algorithms like Raft or Paxos to ensure that only a majority of nodes can make decisions, preventing conflicting decisions in a split brain scenario.
• Network Partition Detection – Use monitoring techniques or distributed failure detectors to identify network partitions and take appropriate actions.
• Automatic Reconciliation – Implement mechanisms to automatically resolve conflicts and ensure data consistency once a split brain is resolved, such as merging conflicting changes or using timestamps or vector clocks.
• Application-level Solutions – Design the application to tolerate split brain scenarios by employing eventual consistency models, conflict-free data structures, or CRDTs.
• Manual Intervention –In some cases, manual intervention may be required to resolve split brain scenarios, involving human decision-making or administrative actions to determine the correct system state and perform data reconciliation.

Pros

• Data Consistency – Implementing a fix ensures that shared data remains consistent across the distributed system.
• System Stability – Resolving split brain scenarios promotes system stability by avoiding conflicting operations and maintaining coherent behavior.

Cons

• Increased Complexity – Fixing split brain scenarios adds complexity to the system due to the intricate logic and mechanisms required.
• Performance Overhead – Split brain resolution mechanisms may impact system performance and latency due to additional processing and communication requirements.
• Higher Resource Utilization – Addressing split brain scenarios may require allocating more resources, potentially increasing costs.
• Increased Failure Surface – Introducing split brain resolution mechanisms may inadvertently introduce new failure modes or vulnerabilities.
• Configuration and Tuning Complexity – Implementing a fix requires careful configuration and ongoing maintenance to ensure optimal behavior in different scenarios.

Hinted Handoff Pattern

_Source_

The Hinted Handoff technique makes sure that you have:

• Fault Tolerance – The ability of the system to continue working even if one or more components fail.
• Availability of Data – Ability to access and modify the data at any given time.

What problem does it solve?

Imagine you have a bank service that communicates with a node that has three replicas. None of the nodes are leaders, so the architecture is leaderless.

You send a request to update the customer's balance to $100. You send this to all the replicas.

The request is successful for the first two replicas but the last one is down. After a few seconds, the replica that was down got back up again but it has the old data.

How do we fix this issue?

The hinted handoff technique says that when a node for a particular data goes offline, then the other nodes of the system will temporarily store updates or modifications intended for the unavailable node.

Hence the name "hints".

So when the unavailable node comes back alive, it can retrieve the hints and apply them.

So the process goes like this:

1. Detection – When a node fails, other nodes detect this failure and mark that node as unavailable.
2. Hint Generation – When a node receives a request to send to the unavailable node, it will store it locally, usually to a file on the disk.
3. Hint Delivery – When the available node goes back online, it sends a message to the other nodes requesting any hints that were made while it was offline. The other nodes send the hints and the node applies them.

By using this technique we ensure our data is consistent and available even when nodes fail or become temporarily unavailable.

Pros

• Improved data availability – Hinted handoff ensures data remains accessible during temporary node failures by transferring responsibilities to other nodes.
• Data consistency – Hinted handoff helps maintain data consistency by synchronizing the failed node with others when it recovers.
• Reduced latency – Hinted handoff minimizes the impact of node failures on system performance, routing requests to alternative nodes and reducing latency.
• Scalability – Hinted handoff enables dynamic redistribution of data responsibilities, allowing the system to handle increased workloads and node changes.

Cons

• Increased complexity – Implementing hinted handoff adds complexity to the system, making development, debugging, and maintenance more challenging.
• Storage overhead – Hinted handoff requires storing additional metadata, incurring storage overhead to track handoff status.
• Potential data staleness – After a failure, recovered nodes may have temporarily stale data until synchronization occurs, leading to potential inconsistencies.
• Increased network traffic – Hinted handoff involves transferring data responsibilities, resulting in increased network traffic and potential impact on network performance.

Use Cases

Hinted handoff is typically implemented in distributed database systems or distributed storage systems where data availability and consistency are crucial.

Here are some scenarios where implementing hinted handoff is beneficial:

• Cloud storage systems – Hinted handoff enables seamless redirection of client requests to available nodes in cloud storage systems when a node becomes temporarily unavailable.
• Messaging systems – Hinted handoff allows distributed messaging systems to route messages to other active brokers when a broker node fails, ensuring message delivery and system operability.
• Distributed file systems – Hinted handoff in distributed file systems allows the temporary transfer of data responsibilities to other nodes when a data node fails, ensuring data availability and uninterrupted read/write operations.
• Content delivery networks (CDNs) – Hinted handoff in CDNs facilitates the redirection of content delivery requests to other servers in the network when a server becomes temporarily unavailable, ensuring continuous content delivery to users.

Read Repair Pattern

Source

In a distributed system, you can have data partitioned into multiple nodes.

This introduces a new challenge where we have to keep the data consistent in all nodes.

For example, if you update data on node A, the changes might not be immediately propagated to other nodes due to all sorts of reasons.

So we use the "read repair" pattern

When a client reads a piece of data from a node, that node will check if the data is the latest. If not, then it receives the latest data from another node.

Once it receives the latest data, it will update the node with the old data with the new data. Hence the "repair".

But this is done on the application side

Doing things on the application side is pretty flexible as you can have your own custom logic per service but it increases complexity and development time.

Thankfully, there are three other methods of implementing read repair:

• Write-Based Read Repair – Proactively update multiple replicas or nodes with the latest data during write operations.
• Background Repair – Schedule periodic background repair processes to scan and repair inconsistencies in the database.
• Database-Specific Read Repair – Leverage built-in read repair mechanisms or conflict resolution features provided by the database.

Pros

• Data Consistency – Read repair maintains data consistency by automatically detecting and correcting inconsistencies between replicas or nodes.
• Improved User Experience – Read repair provides reliable and accurate data, enhancing the user experience by reducing conflicting or outdated information.
• Fault Tolerance – Read repair increases system resilience by addressing data inconsistencies and reducing the risk of cascading failures.
• Performance Optimization – Read repair improves performance by minimizing the need for separate repair processes and distributing the repair workload.
• Simplified Development – Read repair automates consistency checks, simplifying application development.

Cons

• Increased Complexity – Implementing read repair adds complexity to system design, development, and maintenance efforts.
• Performance Overhead – Read repair may introduce additional latency and computational overhead, impacting overall system performance.
• Risk of Amplifying Failures – Incorrect implementation of read repair can propagate inconsistencies or amplify failures.
• Scalability Challenges – Coordinating repairs in large-scale systems can be challenging, impacting performance and scalability.
• Compatibility and Portability – Read repair mechanisms may be specific to certain databases or technologies, limiting compatibility and portability.

Use Cases

Read repair can be beneficial in various scenarios where maintaining data consistency across replicas or nodes is crucial.

Here are some situations where you should consider using read repair:

• Distributed Database Systems – Use read repair in distributed database systems where data is replicated across multiple nodes or replicas to ensure data consistency.
• High Data Consistency Requirements – Implement read repair when your application requires a high level of data consistency, such as in financial systems, collaborative editing platforms, or real-time analytics.
• Read-Heavy Workloads – Consider read repair for read-heavy workloads to detect and reconcile inconsistencies during read operations, improving performance by reducing the need for separate repair processes.
• Systems with Network Delays or Failures – Use read repair in environments with network delays or occasional node failures to automatically detect and correct data inconsistencies caused by these issues.

Service Registry Pattern

When you are working with a distributed system, you will have services that have instances that can scale up or down.

One service can have ten instances at one time and two at another time.

The IP addresses of these instances get created dynamically. Problems arise here.

Imagine that you have a client and it wants to talk to a service. How will it know the IP address of the service if IP addresses are dynamically created?

The answer is a service registry.

What the heck is that?

A service registry is usually a separate service that runs that keeps information about available instances and their locations.

But how does the service registry know all this information?

When we create an instance of any of our services, we register ourselves to the service registry with our name, IP address, and port number.

The service registry then stores this information in its data store.

When a client needs to connect to a service, it queries the service registry to obtain the necessary information for connecting to the service.

Now that we know what a service registry is, let's talk about the patterns of service discovery.

Client Side Discovery

Source

The first and easiest way is for the client to call the service registry and get information about all the available instances of a service.

This approach works well when you want to:

• Have something simple and straightforward.
• Have the client-side make the decisions about which instances to call.

But the significant drawback here is that it couples the client with the service registry.

So you must implement client-side discovery logic for every programming language and framework that your service uses.

Server Side Discovery

Source

On the other hand, the server-side discovery forces the client to make the request via a load balancer.

If you don't know what a load balancer is, feel free to check out my other comprehensive article on it.

The load balancer will call the service registry and routes the request to the specific instance.

Server-side discovery has the following benefits:

• Abstracting the details of the service registry to the load balancer means that the client can simply make a request to the load balancer.
• It's built-in in most popular providers such as AWS ELB (Elastic Load Balancer).

The only downside is that you have another component (service registry) in your infrastructure that you have to maintain.

Circuit Breaker Pattern

Source

Let's say you have three services, A, B, and C. They all call each other sequentially – A calls B, which calls C.

All goes well as long as the services work. But what if one of the services is down Then the other services would fail. If service C is down, then B and A would be down, too.

How do we fix this?

We use the circuit breaker pattern which acts as a middleware between two services.

It monitors the state of the second service and, in case of failure or unresponsiveness, stops the requests to the service and returns a fallback response or error message to the component.

The middleware has three states:

• Closed – The service can communicate with the second service normally.
• Open – When the middleware detects a certain number of consecutive failures then it transitions to the open state, and all requests to the service are immediately blocked.
• Half Open – After a certain period of time, the middleware transitions to a half-open state which allows a limited number of requests to be sent to the second service. If successful, then the middleware transitions to a closed state otherwise it will transition to an open state.

Overall, the circuit breaker pattern increases resilience by providing a fallback mechanism and reducing the load on a failed service.

It also provides insight into the status of a service which helps us identify failures more quickly.

Pros

• Fault tolerance – Circuit breakers enhance system stability by protecting against cascading failures and reducing the impact of unavailable or error-prone dependencies.
• Fail-fast mechanism – Circuit breakers quickly detect failures, allowing for faster recovery and reducing latency by avoiding waiting for failed requests to complete.
• Graceful degradation – Circuit breakers enable the system to gracefully degrade functionality by providing alternative responses or fallback mechanisms during failures.
• Load distribution – Circuit breakers can balance the load across available resources during high traffic or when a service is experiencing issues.

Cons

• Increased complexity – Implementing a circuit breaker adds complexity to the system, impacting development, testing, and maintenance efforts.
• Overhead and latency – Circuit breakers introduce processing overhead and latency as requests are intercepted and evaluated against circuit states.
• False positives – Circuit breakers can mistakenly block requests even when the dependency is available, leading to false positives and impacting system availability and performance.
• Dependency on monitoring – Circuit breakers rely on accurate monitoring and health checks, and if these are unreliable, the effectiveness of the circuit breaker may be compromised.
• Limited control over remote services – Circuit breakers provide protection but lack direct control over underlying services, requiring external intervention for resolving certain issues.

Use Cases

The circuit breaker pattern is beneficial in specific scenarios where a system relies on remote services or external dependencies.

Here are some situations where it is recommended to use the circuit breaker pattern:

• Distributed systems – When building distributed systems that communicate with multiple services or external APIs, the circuit breaker pattern helps improve fault tolerance and resilience by mitigating the impact of failures in those dependencies.
• Unreliable or intermittent services – If you are integrating with services or dependencies that are known to be unreliable or have intermittent availability, implementing a circuit breaker can protect your system from prolonged delays or failures caused by those dependencies.
• Microservices architecture – In a microservices architecture, where individual services have their own dependencies, implementing circuit breakers can prevent cascading failures across services and enable graceful degradation of functionality during failures.
• High-traffic scenarios – In situations where the system experiences high traffic or load, circuit breakers can help distribute the load efficiently by redirecting requests to alternative services or providing fallback responses, thereby maintaining system stability and performance.
• Resilient and responsive systems – The circuit breaker pattern is useful when you want to build systems that are resilient and responsive to failures. It allows the system to quickly detect and recover from issues, reducing the impact on users and ensuring a smoother user experience.

Leader Election Pattern

_Source_

The leader election pattern is a pattern that gives a single thing (process, node, thread, object) superpowers in a distributed system.

This pattern is used to ensure that a group of nodes can coordinate effectively and efficiently.

So when you have three or five nodes performing similar tasks such as data processing or maintaining a shared resource, you don't want them to conflict with one another (that is, contesting for resources or interfering with each other's work).

Elect one leader that coordinates everything

The leader will be responsible for critical decisions or distributing workloads among the other processes.

Any node can be a leader, so we should be careful when we elect them. We don't want two leaders at the same time.

So we must have a good system for selecting a leader. It must be robust, which means it has to cope with network outages or node failures.

How to select a leader

One algorithm named Bully assigns every node with a unique identifier. The node with the highest identifier initially is considered the leader.

If a low-ranked node detects that the leader has failed, it sends a signal to all the other high-ranked nodes to take over. If none of them respond then the node will make itself the leader.

Another popular algorithm is called the Ring algorithm. Each node is arranged in a logical ring. The node with the highest identifier is initialized as a ring.

If a lower-ranked node detects that the ring has failed, then it will request all the other nodes to update their leader to the next highest node.

Both of the above algorithms assume that every node can be uniquely identified.

Pros

• Coordination – Leader election allows for better organization and coordination in distributed systems by establishing a centralized point of control.
• Task Assignment – The leader can efficiently allocate and distribute tasks among nodes, optimizing resource utilization and workload balancing.
• Fault Tolerance – Leader election ensures system resilience by promptly electing a new leader if the current one fails, minimizing disruptions.
• Consistency and Order – The leader maintains consistent operations and enforces the proper order of tasks in distributed systems, ensuring coherence.

Cons

• Overhead and Complexity – Leader election introduces additional complexity and communication overhead, increasing network traffic and computational requirements.
• Single Point of Failure – Dependency on a single leader can lead to system disruptions if the leader fails or becomes unavailable.
• Election Algorithms – Implementing and selecting appropriate leader election algorithms can be challenging due to varying trade-offs in performance, fault tolerance, and scalability.
• Sensitivity to Network Conditions – Leader election algorithms can be sensitive to network conditions, potentially impacting accuracy and efficiency in cases of latency, packet loss, or network partitions.

Use Cases

• Distributed Computing – In distributed computing systems, leader election is crucial for coordinating and synchronizing the activities of multiple nodes. It enables the selection of a leader responsible for distributing tasks, maintaining consistency, and ensuring efficient resource utilization.
• Consensus Algorithms – Leader election is a fundamental component of consensus algorithms such as Paxos and Raft. These algorithms rely on electing a leader to achieve agreement among distributed nodes on the state or order of operations.
• High Availability Systems – Leader election is employed in systems that require high availability and fault tolerance. By quickly electing a new leader when the current one fails, these systems can ensure uninterrupted operations and mitigate the impact of failures.
• Load Balancing – In load balancing scenarios, leader election can be used to select a leader node responsible for distributing incoming requests among multiple server nodes. This helps in optimizing resource utilization and evenly distributing the workload.
• Master-Slave Database Replication – In database replication setups, leader election is used to determine the master node responsible for accepting write operations. The elected master coordinates data synchronization with slave nodes, ensuring consistency across the replica set.
• Distributed File Systems – Leader election is often employed in distributed file systems, such as Apache Hadoop's HDFS. It helps in maintaining metadata consistency and enables efficient file access and storage management across a cluster of nodes.

Bulk Head Pattern

Source

Things fail for all sorts of reasons in a distributed system. This is why we need to make sure our systems are resilient in case of failures.

One way to improve that is to use the bulkhead pattern.

So let's say we have two services, A and B.

Some requests of A depend on B. But the issue is that service B is pretty slow which makes A slow and blocks its threads. This makes all requests to A slow, even the ones which don't depend on B.

The bulkhead pattern solves that by allocating a specific amount of threads for requests to B. This prevents A from consuming all threads due to B.

Pros

• Fault isolation – The bulkhead pattern contains failures within individual services, minimizing their impact on the overall system.
• Scalability – Services can be independently scaled, allowing allocation of resources where needed without affecting the entire system.
• Performance optimization – Specific services can receive performance optimizations independently, ensuring efficient operation.
• Development agility – Code modularity and separation of concerns facilitate parallel development efforts.

Cons

1. Complexity – Implementing the bulkhead pattern adds architectural complexity to the system.
2. Increased resource usage – Duplication of resources across components may increase resource consumption.
3. Integration challenges – Coordinating and integrating the services can be challenging and introduce potential points of failure.

Use Cases

Here are some common scenarios where the bulkhead pattern is beneficial:

• Microservices architecture – The bulkhead pattern is used to isolate individual microservices, ensuring fault tolerance and scalability in a distributed system.
• Resource-intensive applications – By partitioning the system into components, the bulkhead pattern optimizes resource allocation, enabling efficient processing of resource-intensive tasks without impacting other components.
• Concurrent processing – The bulkhead pattern helps handle concurrent processing by assigning dedicated resources to each processing unit, preventing failures from affecting other units.
• High-traffic or high-demand systems – In systems experiencing high traffic or demand, the bulkhead pattern distributes the load across components, preventing bottlenecks and enabling scalable handling of increased traffic.
• Modular and extensible systems – The bulkhead pattern facilitates modular development and maintenance, allowing independent updates and deployment of specific components in a system.

Retry Pattern

Source

The retry pattern is used to handle temporary failures.

Requests fail for all sorts of reasons, from faulty connections to site reloading after a deployment.

So let's say we have a client and a service. The client sends a request to the service and receives a response code 500 back.

There are multiple ways to handle this according to the retry pattern.

• If the problem is rare, then retry immediately.
• If the problem is more common, then retry after some amount of delay (for example 50ms, 100ms, etc)
• If the issue is not temporary (invalid credentials, and so on) then cancel the request.

But sometimes, the client thinks that the request has failed

Sometimes the operation was a success but the request failed to return something. This happens when requests are not stateless, meaning that they change the state of the system somehow (like CRUD operations on a database).

So what we do is we send a duplicate request which can cause problems in the system.

For that, we need some sort of tracking system. We can use the circuit breaker pattern to limit the impact of repeatedly retrying a failed/recovering service.

Pros

• Resilience and Reliability – By automatically retrying failed requests, you increase the chance of the system recovering from failure (resilience) and increase a chance of a successful requests (reliability).
• Error handling – Retrying an operation transparently hides the error from the end user, making the system appear more robust.
• Simplified Implementation – The retry pattern is simple to implement. Instead of having custom error handling logic for all your requests, you can wrap them all with a retry pattern class.
• Performance optimization – In some cases, temporary errors may be resolved quickly, and the subsequent retries can succeed without significant delays. This can help optimize performance by avoiding unnecessary failures and reducing the impact on the end user.

Cons

• Increased latency – When retries are attempted, there is an inherent delay introduced in the system. If the retries are frequent or the operations take a long time to complete, the overall latency of the system may increase.
• Risk of infinite loops – Without proper safeguards, retries can potentially lead to infinite loops if the underlying error condition persists.
• Increased network and resource usage – Retrying failed operations can lead to additional network traffic and resource utilization.
• Potential for cascading failures – If the underlying cause of the failure is not resolved, retrying the operation may result in cascading failures throughout the system.
• Difficulty in handling idempotent operations – Retrying stateful requests can lead to unintended consequences if the request is performed multiple times.

Use Cases

The applicability of the retry pattern depends on the specific requirements and characteristics of the system being developed.

The pattern is most useful for handling temporary errors. But, you must also keep in mind for scenarios involving long delays, stateful requests, or cases where manual intervention is required.

Now, let's look at some use cases where retrying requests help:

• Network communication – When working with third party services or APIs over a network, all sorts of errors can occur.
• Database operations – Databases also face the same issues due to temporary unavailability, timeouts, or deadlock situations.
• File or resource access – When accessing files, external resources, or dependencies, failures due to locks, permissions, or temporary unavailability can occur.
• Queue processing – Systems that rely on message queues or event-driven architectures may encounter temporary issues like queue congestion, message delivery failures, or service availability fluctuations.
• Distributed transactions – In distributed systems, performing coordinated transactions across multiple services or components can face challenges like network partitions or temporary service failures.
• Data synchronization – When synchronizing data between different systems or databases, temporary errors can disrupt the synchronization process.

Scatter Gather Pattern

Source

Let's say we have a process-heavy task like video compression.

We get a video and have to compress it into 5 different resolutions such as 240p, 360p, 480, 720p, and 1080p.

We have a single image compression service that takes in the video and processes each resolution sequentially. The problem here is that it's very slow.

The scatter-gather pattern advises us to run multiple of these processes simultaneously and gather all the results in one place.

So for our video process examples, this is how it will look:

1. Scatter – We will divide the task into multiple nodes, so one node will take care of compressing the video into 240p, another to 360p, and so on.
2. Process – Each node will compress its video individually and simultaneously.
3. Gather – Once all the nodes have finished compressing the videos, the videos will be stored on some server and we collect the links for all the different versions.

Instead of waiting for each of our videos to be compressed sequentially, now we can parallelize this whole process and increase performance significantly.

Pros

• Parallel Processing – The scatter-gather pattern improves performance by enables parallel processing of subtasks. Tasks can execute concurrently across multiple nodes or processors.
• Scalability – The scatter gather pattern allows us to scale horizontally, the higher our workload, the more nodes we provision.
• Fault Tolerance – This pattern enhances fault tolerance by redistributing failed subtasks to other available nodes, ensuring the overall task can still be completed successfully.
• Resource Utilization – The scatter-gather pattern optimizes resource utilization by efficiently leveraging available computational resources across multiple nodes or processors.

Cons

• Communication Overhead – This pattern involves communication between nodes which introduce potential latency and network congestion that may impact overall performance, especially with large data volumes.
• Load Balancing – Balancing the workload evenly across nodes can be challenging, leading to potential inefficiencies and performance bottlenecks if some nodes are idle while others are overloaded.
• Complexity – This pattern is not easy to implement and adds an aditional layer of complexity to the system. It requires careful planning and synchronization mechanisms to coordinate subtasks.
• Data Dependency – Handling dependencies among subtasks, where the output of one subtask is needed as input for another, can be more complex in the scatter-gather pattern compared to other patterns.

Use Cases

The scatter-gather pattern is useful in distributed systems and parallel computing scenarios where you can divide tasks into smaller subtasks that can be performed concurrently across multiple nodes and processors.

Here are some use cases where the scatter-gather pattern can be used:

• Web Crawling – You can use the scatter gather pattern to fetch and crawl multiple web pages concurrently.
• Data Analytics – Apply scatter-gather to divide large datasets into chunks for parallel processing in data analysis tasks, combining individual results for final insights.
• Image/Video Processing – Utilize scatter-gather for distributed image/video processing, such as encoding frames in parallel and gathering results for the final output.
• Distributed Search – Implement scatter-gather in distributed search systems to distribute search queries across nodes, gather and rank results for final search output.
• Machine Learning – Apply scatter-gather in distributed machine learning for parallel model training on scattered data and combining models for final trained model.
• MapReduce – Incorporate scatter-gather in the MapReduce model for big data processing, scattering input, parallel processing of intermediate results, and gathering for final output.

Bloom Filters (Data Structure)

_Source_

Bloom filters is a data structure that is designed to tell you efficiently both in memory and speed whether an item is in a set.

But the cost of this efficiency is that it is probabilistic. It can tell you that an item is either:

• Definitely not in a set.
• Might be in a set.

Pros

• Space Efficiency – Bloom filters usually require a smaller amount of memory to store the same number of elements compared to hash tables or other similar data structures.
• Fast Lookups – Checking whether an element is in a Bloom filter has a constant-time complexity regardless of the size of the filter or the number of elements it contains.
• No False Negatives – Bloom filters provide a definitive "no" answer if an element is not in the filter. There are no false negatives, meaning if the filter claims an element is not present, it is guaranteed to be absent.
• Parallelizable – Bloom filters can be easily parallelized, allowing for efficient implementation on multi-core systems or distributed environments.

Cons

• False Positives – Due to their probabilistic nature, there is a small probability that the filter will incorrectly claim an element is present when it is not. The probability of false positives increases as the filter becomes more crowded or the number of elements increases.
• Limited Operations – Bloom filters only support insertion and membership tests. They do not allow deletion of elements or provide a mechanism to retrieve the original elements stored in the filter. Once an element is inserted, it cannot be removed individually.
• Fixed Size – The size of the bloom filter must be determined beforehand and cannot dynamically resize. If these parameters are not estimated accurately, the filter may become ineffective or waste memory.
• Unordered Data – Bloom filters do not maintain the order or provide any information about the stored elements. They are not suitable for scenarios that require ordering or retrieval of elements based on certain criteria.

Use Cases

Bloom filters are most useful in situations where approximate membership tests with a low false positive rate are acceptable and where memory efficiency is a priority.

Here are some scenarios where Bloom filters are particularly beneficial:

• Caching Systems – Bloom filters can be used to quickly check if an item is likely to be present in the cache or not. By checking the bloom filter, the system can avoid the costly operation of fetching the item from the cache or underlying storage if it is not likely to be there, thereby improving overall performance.
• Content Delivery Systems – CDNs use bloom filters to handle cache invalidation. Instead of checking each edge server, we use a bloom filter to identify whether the edge server potentially has a specific resource.
• Anti-Spam Systems – Anti-spam systems check emails against common spam databases. Instead of checking against the databases which is expensive, we use bloom filters which are much more efficient.
• Distributed Data Processing – In a distributed data processing framework such as Hadoop or Spark. We use bloom filters to optimize join operations by pre-filtering data and removing unnecessary shuffles.

Conclusion

You don't need to be an expert in all of these things – I'm not. And even if you don't ever directly use or work with some of these concepts, they are still good to know.

Try to implement them in simple projects. It's a good idea to keep the projects simple enough so you won't get sidetracked.

Below, I share with you my favorite resources that I used to learn about distributed systems.

Thank you for reading.

Recommended Resources

• Microservices.io
• Designing Data Intensive Applications
• System Design Interview Prep
• System Design Prime
• Distributed Systems: Principles and Paradigms

As a developer, it's a good idea to learn how things work "under the hood". That way you understand what your code and the tools you use are actually doing.

But it might seem easier to rely on black box abstraction and ignore the inner workings.

A popular black box abstraction is the internet.

Sure, many of us probably know the basics of what the internet is and how it works. There is a client and a server and they simply "communicate" with each other using something called HTTP or HTTPS?

But that's the extent of most people's knowledge.

I'm not saying we shouldn't use abstractions – I'm just saying that we should have some basic idea about how things work.

This is why I'm writing this article: to demystify this black box to help you learn how computers communicate with each other over a network.

What is the OSI Model?

The Seven Layers of OSI

The Open Systems Interconnection or OSI model is essentially a reference system that lays out how computers communicate with each other over a network.

It was created in 1983 by representatives of telecom companies and officially standardized in 1984 by the International Organization for Standardization (ISO).

It is divided into seven layers. Each layer has its own domain and receives data from the previous layer, while passing data to the next layer.

The seven layers are:

1. Application Layer
2. Presentation Layer
3. Session Layer
4. Transport Layer
5. Network Layer
6. Data Link Layer
7. Physical Layer

If we think of it in coding terms, each layer is a class with some core functionality, and each class communicates with only the class above or below it.

Keep in mind that this is a reference model, meaning that we don't actually use it in real life. There is another model which is very similar to the OSI model but it encapsulates the first three layers and the last two.

This "real life" model is called the TCP/IP Model which is what the internet runs on.

OSI vs TCP/IP Model diagram

But before we jump in and deal with each layer one by one, let's go over why should you learn the OSI model if it's not even used in real life.

Why Learn the OSI Model

During the past 20 years or so, the world has dramatically changed.

The internet came, the "web" came, and within the web ecosystem lots of things have changed. We started with simple HTML pages, then came JavaScript, and now we have all these frameworks and it sometimes feels so overwhelming.

But, you gotta remember this:

Learn the fundamentals, learn from first principles.

Let's take the web, for example, aside from all these changes we have seen during the past 20 years.

How the web works hasn't actually change much.

We still use the HTTP protocol.

It's true that the HTTP protocol has been updated, but not so much.

Even if we break down HTTP, it's made from TCP which also hasn't changed much.

My point is that you should stop looking at the shiny new things and focus on the fundamentals that these shiny new things are built upon.

For example, I remember when web sockets was a popular thing.

But if we break it down, they're based on the TCP protocol.

If you know TCP, you can easily understand how web sockets work and don't have to rely on black box abstractions.

I hope I've convinced on why you should learn from first principles. This not only applies to software engineering but to many other fields, too.

With that done, let's go over the seven layers of the OSI model.

The Seven Layers of the OSI Model

Application Layer

This is the layer where the end user exists

The application layer is where most software engineers work. And this is where your browsers lives.

But I'm not talking about concrete applications such as Chrome, Skype, or Outlook.

I'm talking more fundamental things, such as protocols.

For example:

• Your browser makes a request to a web server using the HTTP protocol.
• Your email app uses the SMTP protocol to send and receive emails.
• Without the DNS protocol, you would have to type 142.250.150.138 instead of google.com.

In a nutshell, the application layer handles the foundation that almost all end user applications use.

Presentation Layer

Once the client makes the HTTP request, the request itself get's passed down to the presentation layer (also called syntax layer).

This layer handles three main functionalities:

Encryption and Decryption

You don't want your data out in public, which is why smart people created the Transport Layer Security (TLS). It essentially encrypts your data.

It's also responsible for decrypting requests coming from other servers to be consumed by the application layer.

Serialization and Deserialization

These are some big words, but what they essentially mean is "translation".

We want to "translate" our data to forms that our application understands.

For example, simple data structures may be translated into "objects" that our JavaScript application understands.

On the other hand, if we want our data to pass down the layer, we would translate our object into simple data structures that could be understood in the lower layers.

Compression

This is a no-brainer: the fewer bits there are to send, the faster the request will be.

This is also one of the main functions of the presentation layer. Keep in mind this is a lossless compression meaning no information will be lost in the process.

Well to be fair, in the real world most of these things are done in the application layer.

This is why in the TCP/IP model the presentation layer is part of the application layer.

Session Layer

The session layer is responsible for opening, closing and maintaining connections between client and server

This one is a bit confusing. And in fact, I couldn't find many use cases for it.

The primary function of the session layer is to manage connections between client and server.

But what does that actually mean?

So let's say you want to go to google.com

To do that you first have to establish a connection with google.com, so you say "Hey server, what's up, I want to connect to google.com".

The server responds back: "Yeah, sure."

Congratulations, you have just established a connection with google.com's server and can freely send a GET request to fetch the page.

Long story short, this layer is used for:

• Opening connections
• Keeping connections alive
• Closing connections.

Now comes the reality check: in real life this pretty much does not exist and is part of the Transport Layer – which we'll discuss next.

Transport Layer

TCP and UDP visualized

This is where the interesting stuff happens.

The transport layer is usually defined based on the protocol that's being used.

The two most popular ones are:

• Transmission Control Protocol (TCP)
• User Datagram Protocol (UDP)

TCP is one of the main protocols in the internet suite. It is used on top of the IP (internet protocol) to ensure reliable transmission of packets.

TCP fixes many issues that arise when you use IP such as lost packets, out of order packets, duplicate packets, and corrupted packets.

You would use TCP in applications that require all packets to be error-free such as text messaging.

On the other hand UDP is stateless, meaning it doesn't save any state between the client and server It is also very light making it fast. But the downside is that it's not reliable, packets can go missing, get corrupted, and so on.

UDP is mostly used when you don't really care if you lose a few packets here and there, such as video streaming.

Also keep in mind that the data in this layer are called segments.

Long story short, TCP is reliable but slow, while UDP is unreliable but fast.

Network Layer

The network layer is responsible for sending packets from network to network

I don't really know why this is called the network layer.

It should be called the internet layer – because the most important protocol here is the Internet Protocol (IP)

What the IP basically does is it takes the segments from the transport protocol, and adds meta-data that helps identify where your client is in a local network.

Another function of the network layer is message forwarding, meaning that it sends your packets from network to network.

Data in this layer are called packets.

Data-Link Layer

The data link layer is made of two parts: MAC and LLC

This layer defines how data is transmitted between two systems.

It takes care of things such as how long two systems talk to each other, how much data can be sent, and what happens if there are any errors. All this is handled in the Data Link layer.

The data link layer is broken up to two sub-layers:

• Logical Link Layer (LLC) – This layer provides flow control, acknowledgment, and error handling in case things go wrong.
• Media Access Control (MAC) – This layer is responsible for assigning a unique id number based on your network card called a MAC address. Meaning no two devices have the same MAC addresses.

Packets are taken from the network layer, and are encapsulated with the addition of new headers for the MAC address of the client and server.

There is also another subset of data added at the end of the packet which is used for error detection. This is called the tail.

Once these meta-data are added, the data is now called a frame.

Physical Layer

Bits can be transferred using electricity, radio waves, or even light

Finally this is the physical layer.

Don't get confused with the word physical – we are not only talking about wires.

Data can get transferred in many different ways such as radio waves or even light.

Unfortunately these ways of transportation do not know "frames", they only know bits.

The function of this layer is to simply transform frames into bytes (8 bits) and send them over some transport method (electricity, waves, light, and so on).

Finally our request will get transmitted to the server, and the server will go through the same process but in reverse.

Conclusion

In this article, you learned:

• That the OSI Model is a reference model on how two systems talk to each other over a network.
• We don't use this model in real life. Instead, we use another similar model called the TCP/IP model.
• The OSI mode is made up of seven parts, each with a specific function.

I hope you learned something today, and would like to thank you for reaching the end.

I plan to post snippets of content similar to this on Twitter, so if you're interested follow me @tamerlan_dev.

Two years ago, I started working professionally as a backend developer. And I was very intimidated by all the technology I didn't yet know. Words like Docker, Kubernetes, and GraphQL seemed quite scary.

But I mustered up the courage and started to learn them all one by one.

It was actually easier than I thought, so I would like to share with you what I've learned about GraphQL by creating a simple demo project together.

You can find the final project on GitHub here.

Prerequisites

Before we begin, make sure to have these installed on your system:

• PHP 7+
• Composer 2.0
• Docker 20.10.6 (Any other version should be fine)
• Docker-Compose 1.29.1 (Any other version should be fine)

I also assume that you have:

• Basic knowledge of Laravel (Eloquent, Migrations, MVC, Routes, and so on)
• Knowledge of PHP (Syntax, OOP, and so on)
• Basic knowledge of GraphQL (in theory)

What We're Going to Build

I like RPG games like the Elder Scrolls Series or Final Fantasy, so of course our app will be about games. The project will consist of only two models called Quests and Categories.

Database Schema

By the end of this post we will create a CRUD GraphQL API for each model.

How to Initialize the Project

Create a Laravel project using this command:

composer create-project laravel/laravel quest_journal

This will create a new project in a new directory called quest_journal.

Next let's setup sail like this:

# Move into the project
cd quest_journal

# Install and configure laravel sail
php artisan sail:install

It's gonna ask you which services to install. Just press enter to only install MySQL.

If all goes well, you should now see a docker-compose.yml file in your project directory.

Let's then run the containers using sail:

# Run the containers
./vendor/bin/sail up -d

# Check if the containers are running
docker ps

At this point I suggest you alias sail to ./vendor/bin/sail. You can do that by adding this piece of code to your bashrc or zshrc:

# in ~./zshrc or ~./bashrc

alias sail = 'bash vendor/bin/sail'

Moving on, if you go to localhost you should see something like this:

Default Laravel Home Page

But before we move on, there are some packages that we need to install first:

# IDE helper for laravel, always useful to have.
sail composer require --dev barryvdh/laravel-ide-helper

# GraphQL library which we are going to use
sail composer require rebing/graphql-laravel

Next we have to publish the GraphQL library like this:

sail artisan vendor:publish --provider="Rebing\\GraphQL\\GraphQLServiceProvider"

This should create a GraphQL config file that we will use in config/graphql.php.

How to Create the Migrations and Models

This isn't a Laravel tutorial, so we'll quickly create the models with the appropriate migrations.

Let's start with category model:

# Create model with migrations
sail artisan make:model -m Category

This will create the Category model with it's migration file.

Our category will consist of four fields:

• ID
• Title
• Created_At
• Updated_At

Our category migrations file should look like this:

<?php

// database/migrations/yyyy_mm_dd_hhMMss_create_categories_table.php

use Illuminate\\Database\\Migrations\\Migration;
use Illuminate\\Database\\Schema\\Blueprint;
use Illuminate\\Support\\Facades\\Schema;

class CreateCategoriesTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('categories', function (Blueprint $table) {
            $table->id();
            $table->text('title');
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('categories');
    }
}

Next let's configure the category model class.

We will do two things here:

• Make the field title editable, so we will add it to our $fillable array.
• Define the relationship between category model and quest model.

<?php

// App\\Models\\Category

namespace App\\Models;

use Illuminate\\Database\\Eloquent\\Factories\\HasFactory;
use Illuminate\\Database\\Eloquent\\Model;

class Category extends Model
{
    use HasFactory;

    protected $fillable = ['title'];

    public function quests(){
        return $this->hasMany(Quest::class);
    }
}

You will have some errors concerning the Quest model, but no worries – we will handle that next.

Run the command to make a model and migration file for quest:

sail artisan make:model -m Quest

This will create a model named Quest and a migration file for it.

Our quest will have the fields:

• ID
• Title
• Description
• Reward
• Category_ID
• Created_At
• Updated_At

<?php
// database/migrations/yyyy_mm_dd_hhMMss_create_quests_table.php

use Illuminate\\Database\\Migrations\\Migration;
use Illuminate\\Database\\Schema\\Blueprint;
use Illuminate\\Support\\Facades\\Schema;

class CreateQuestsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('quests', function (Blueprint $table) {
            $table->id();
            $table->text('title');
            $table->text('description');
            $table->integer('reward');
            $table->foreignId('category_id')->constrained();
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('quests');
    }
}

As you can see, we declared the category_id to be a foreignId. This way Laravel will automatically create a foreign key relationship between the tables categories and quests.

Next let's configure the quest model class.

Here we will:

• Make the appropriate fields editable by adding them to the $fillable array.
• Define the relationship between category model and quest model.

<?php

// App\\Models\\Quest

namespace App\\Models;

use Illuminate\\Database\\Eloquent\\Factories\\HasFactory;
use Illuminate\\Database\\Eloquent\\Model;

class Quest extends Model
{
    use HasFactory;

    protected $fillable = ['title', 'category_id', 'description',                               'reward'];

    public function category(){
        return $this->belongsTo(Category::class);
    }
}

With both the migrations and models ready, we can apply the changes to the database.

Run this command:

# Apply migrations
sail artisan migrate

Our database should be updated! Next we should put some data into our tables.

How to Seed the Database

We need data to work with, but as developers we are too lazy to manually do it.

This is where factories come.

First, we'll create the factory classes for both the quest and category model.

Run the following commands:

# Create a factory class for quest model
sail artisan make:factory QuestFactory --model=Quest

# Create a factory class for category model
sail artisan make:factory CategoryFactory --model=Category

This will create for us two new classes:

• QuestFactory – a class that helps us generate quests.
• CategoryFactory – a class that helps us generate categories.

Let's start with the QuestFactory. In our definitions function we will tell Laravel how each field should be generated. For the field category_id, we will pick a random category.

<?php

// database/factories/QuestFactory.php

namespace Database\\Factories;

use App\\Models\\Category;
use App\\Models\\Quest;
use Illuminate\\Database\\Eloquent\\Factories\\Factory;

class QuestFactory extends Factory
{
    /**
     * The name of the factory's corresponding model.
     *
     * @var string
     */
    protected $model = Quest::class;

    /**
     * Define the model's default state.
     *
     * @return array
     */
    public function definition()
    {
        $categoryIDs = Category::all()->pluck('id')->toArray();

        return [
            'title' => $this->faker->title(),
            'description' => $this->faker->text(),
            'reward' => $this->faker->numberBetween(1 , 100),
            'category_id' => $this->faker->randomElement($categoryIDs)
        ];
    }
}

CategoryFactory is much simpler, as we simply have to generate a title.

<?php

// database/factories/CategoryFactory.php

namespace Database\\Factories;

use App\\Models\\Category;
use Illuminate\\Database\\Eloquent\\Factories\\Factory;

class CategoryFactory extends Factory
{
    /**
     * The name of the factory's corresponding model.
     *
     * @var string
     */
    protected $model = Category::class;

    /**
     * Define the model's default state.
     *
     * @return array
     */
    public function definition()
    {
        return [
            'title' => $this->faker->title()
        ];
    }
}

Now instead of creating seeders, we will simply run the factory create method inside DatabaseSeeder.php:

<?php

// database/seeders/DatabaseSeeder.php

namespace Database\\Seeders;

use App\\Models\\Category;
use App\\Models\\Quest;
use Illuminate\\Database\\Seeder;

class DatabaseSeeder extends Seeder
{
    /**
     * Seed the application's database.
     *
     * @return void
     */
    public function run()
    {
        Category::factory(10)->create();
        Quest::factory(10)->create();
    }
}

Finally run the command to seed the database.

sail artisan db:seed

Folder Structure

At this point we are ready to create our GraphQL APIs. To do that let's first create a new folder in the app directory called GraphQL.

Inside the GraphQL folder, create three new folders:

• Mutations
• Queries
• Types

It will look something like this:

This is where the bulk of our code will be. As you might be able to tell, it's very different from REST architecture. Before we begin writing the code, let me quickly explain the purpose of each folder.

• Mutations: This folder will contain classes that manage the insert, update, and delete operations.
• Queries: This folder will contain the classes that fetch data from the database.
• Types: You can think of this as a model, or a model resource. Basically types are objects that can be fetched from the database. For example, we are going to have a QuestType and a CategoryType.

How to Define the Category and Quest Types

Let's first start with types. We'll create two new classes in our types folder called:

1. CategoryType
2. QuestType

Here is where we will use the rebing/graphql-laravel package which basically helps us create types, queries, and mutations.

Our types will inherit the Type class from Rebing\\GraphQL\\Support\\Type. There's also another class called Type in the package but it's used to declare the type of field (like string, int, and so on).

Let's begin with the CategoryType class:

<?php

// app/graphql/types/CategoryType 

namespace App\\GraphQL\\Types;

use App\\Models\\Category;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Type as GraphQLType;

class CategoryType extends GraphQLType
{
    protected $attributes = [
        'name' => 'Category',
        'description' => 'Collection of categories',
        'model' => Category::class
    ];

    public function fields(): array
    {
        return [
            'id' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'ID of quest'
            ],
            'title' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'Title of the quest'
            ],
            'quests' => [
                'type' => Type::listOf(GraphQL::type('Quest')),
                'description' => 'List of quests'
            ]
        ];
    }
}

Let's break this down:

• Attributes: This is your type configuration. It has core information about your type, and to which model it associates.
• Fields: This method returns the fields that your client can ask for.

You may have noticed that we have a field called quests which is a list of QuestType. But we don't associate the class directly – we instead use its name from its attribute.

Next is the QuestType class:

<?php

// app/graphql/types/QuestType 

namespace App\\GraphQL\\Types;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Type as GraphQLType;

class QuestType extends GraphQLType
{
    protected $attributes = [
        'name' => 'Quest',
        'description' => 'Collection of quests with their respective category',
        'model' => Quest::class
    ];

    public function fields(): array
    {
        return [
            'id' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'ID of quest'
            ],
            'title' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'Title of the quest'
            ],
            'description' => [
                'type' => Type::nonNull(Type::string()),
                'description' => 'Description of quest'
            ],
            'reward' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'Quest reward'
            ],
            'category' => [
                'type' => GraphQL::type('Category'),
                'description' => 'The category of the quest'
            ]
        ];
    }
}

How to Define the Queries for Your Model

Now that we have defined our types, we can move on to queries.

For each model we will have two queries:

• A class to query a single model
• A class to query a list of models

To keep stuff organized, create two new folders in your Queries folder:

• Category
• Quest

Let's create our classes:

• QuestQuery
• QuestsQuery
• CategoryQuery
• CategoriesQuery

Your file structure should look like this:

Let's start with the QuestQuery class:

<?php

// app/graphql/queries/quest/QuestQuery 

namespace App\\GraphQL\\Queries\\Quest;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Query;

class QuestQuery extends Query
{
    protected $attributes = [
        'name' => 'quest',
    ];

    public function type(): Type
    {
        return GraphQL::type('Quest');
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' => Type::int(),
                'rules' => ['required']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        return Quest::findOrFail($args['id']);
    }
}

Let's break this down:

• Our query classes will inherit from Rebing\\GraphQL\\Support\\Query
• The attributes function is used as the query configuration.
• The type function is used to declare what type of object this query will return.
• The args function is used to declare what arguments this query will accept. In our case we only need the id of the quest.
• The resolve function does the bulk of the work – it returns the actual object using eloquent.

The rest of the classes have a similar format, so it's pretty much self explanatory.

<?php

// app/graphql/queries/quest/QuestsQuery 

namespace App\\GraphQL\\Queries\\Quest;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Query;

class QuestsQuery extends Query
{
    protected $attributes = [
        'name' => 'quests',
    ];

    public function type(): Type
    {
        return Type::listOf(GraphQL::type('Quest'));
    }

    public function resolve($root, $args)
    {
        return Quest::all();
    }
}

<?php

// app/graphql/queries/category/CategoryQuery 

namespace App\\GraphQL\\Queries\\Category;

use App\\Models\\Category;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Query;

class CategoryQuery extends Query
{
    protected $attributes = [
        'name' => 'category',
    ];

    public function type(): Type
    {
        return GraphQL::type('Category');
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' => Type::int(),
                'rules' => ['required']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        return Category::findOrFail($args['id']);
    }
}

<?php

// app/graphql/queries/category/CategoriesQuery 

namespace App\\GraphQL\\Queries\\Category;

use App\\Models\\Category;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Query;

class CategoriesQuery extends Query
{
    protected $attributes = [
        'name' => 'categories',
    ];

    public function type(): Type
    {
        return Type::listOf(GraphQL::type('Category'));
    }

    public function resolve($root, $args)
    {
        return Category::all();
    }
}

How to Create the Mutation Classes

Mutations will house our classes that control the insertion/deletion of our models. So for each model we will have three classes:

• A class to create a model
• A class to update a model
• A class to delete a model

We have two models in our app, so we will have 6 mutation classes.

To keep things organized, create two new folders in your Mutations folder:

• Category
• Quest

Let's create our mutation classes:

• CreateCategoryMutation
• DeleteCategoryMutation
• UpdateCategoryMutation
• CreateQuestMutation
• DeleteQuestMutation
• UpdateQuestMutation

Your file structure should look like this:

Let's start with CreateCategoryMutation:

<?php

// app/graphql/mutations/category/CreateCategoryMutation 

namespace App\\GraphQL\\Mutations\\Category;

use App\\Models\\Category;
use Rebing\\GraphQL\\Support\\Mutation;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;

class CreateCategoryMutation extends Mutation
{
    protected $attributes = [
        'name' => 'createCategory',
        'description' => 'Creates a category'
    ];

    public function type(): Type
    {
        return GraphQL::type('Category');
    }

    public function args(): array
    {
        return [
            'title' => [
                'name' => 'title',
                'type' =>  Type::nonNull(Type::string()),
            ],
        ];
    }

    public function resolve($root, $args)
    {
        $category = new Category();
        $category->fill($args);
        $category->save();

        return $category;
    }
}

As you can see, the structure is very similar to our queries.

Once again let's break down this class:

• Our mutation classes will inherit from Rebing\\GraphQL\\Support\\Mutation
• The attributes function is used as mutation configuration.
• The type function is used to declare what type of object this query will return.
• The args function is used to declare what arguments this mutation will accept. In our case we only need the title field.
• The resolve function does the bulk of the work – it does the actual mutation using eloquent.

The rest of the mutations have a similar format, so they should be self-explanatory.

<?php

// app/graphql/mutations/category/DeleteCategoryMutation 

namespace App\\GraphQL\\Mutations\\Category;

use App\\Models\\Category;
use Rebing\\GraphQL\\Support\\Mutation;
use GraphQL\\Type\\Definition\\Type;

class DeleteCategoryMutation extends Mutation
{
    protected $attributes = [
        'name' => 'deleteCategory',
        'description' => 'deletes a category'
    ];

    public function type(): Type
    {
        return Type::boolean();
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' => Type::int(),
                'rules' => ['required']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        $category = Category::findOrFail($args['id']);

        return  $category->delete() ? true : false;
    }
}

<?php

// app/graphql/mutations/category/UpdateCategoryMutation 

namespace App\\GraphQL\\Mutations\\Category;

use App\\Models\\Category;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Mutation;

class UpdateCategoryMutation extends Mutation
{
    protected $attributes = [
        'name' => 'updateCategory',
        'description' => 'Updates a category'
    ];

    public function type(): Type
    {
        return GraphQL::type('Category');
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' =>  Type::nonNull(Type::int()),
            ],
            'title' => [
                'name' => 'title',
                'type' =>  Type::nonNull(Type::string()),
            ],
        ];
    }

    public function resolve($root, $args)
    {
        $category = Category::findOrFail($args['id']);
        $category->fill($args);
        $category->save();

        return $category;
    }
}

<?php

// app/graphql/mutations/quest/CreateQuestMutation 

namespace App\\GraphQL\\Mutations\\Quest;

use App\\Models\\Quest;
use Rebing\\GraphQL\\Support\\Mutation;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;

class CreateQuestMutation extends Mutation
{
    protected $attributes = [
        'name' => 'createQuest',
        'description' => 'Creates a quest'
    ];

    public function type(): Type
    {
        return GraphQL::type('Quest');
    }

    public function args(): array
    {
        return [
            'title' => [
                'name' => 'title',
                'type' =>  Type::nonNull(Type::string()),
            ],
            'description' => [
                'name' => 'description',
                'type' =>  Type::nonNull(Type::string()),
            ],
            'reward' => [
                'name' => 'reward',
                'type' => Type::nonNull(Type::int()),
            ],
            'category_id' => [
                'name' => 'category_id',
                'type' => Type::nonNull(Type::int()),
                'rules' => ['exists:categories,id']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        $quest = new Quest();
        $quest->fill($args);
        $quest->save();

        return $quest;
    }
}

<?php

// app/graphql/mutations/quest/DeleteQuestMutation 

namespace App\\GraphQL\\Mutations\\Quest;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Mutation;

class DeleteQuestMutation extends Mutation
{
    protected $attributes = [
        'name' => 'deleteQuest',
        'description' => 'Deletes a quest'
    ];

    public function type(): Type
    {
        return Type::boolean();
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' => Type::nonNull(Type::int()),
                'rules' => ['exists:quests']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        $category = Quest::findOrFail($args['id']);

        return  $category->delete() ? true : false;
    }
}

<?php

// app/graphql/mutations/quest/UpdateQuestMutation 

namespace App\\GraphQL\\Mutations\\Quest;

use App\\Models\\Quest;
use GraphQL\\Type\\Definition\\Type;
use Rebing\\GraphQL\\Support\\Facades\\GraphQL;
use Rebing\\GraphQL\\Support\\Mutation;

class UpdateQuestMutation extends Mutation
{
    protected $attributes = [
        'name' => 'updateQuest',
        'description' => 'Updates a quest'
    ];

    public function type(): Type
    {
        return GraphQL::type('Quest');
    }

    public function args(): array
    {
        return [
            'id' => [
                'name' => 'id',
                'type' =>  Type::nonNull(Type::int()),
            ],
            'title' => [
                'name' => 'title',
                'type' =>  Type::nonNull(Type::string()),
            ],
            'description' => [
                'name' => 'description',
                'type' =>  Type::nonNull(Type::string()),
            ],
            'reward' => [
                'name' => 'reward',
                'type' => Type::nonNull(Type::int()),
            ],
            'category_id' => [
                'name' => 'category_id',
                'type' => Type::nonNull(Type::int()),
                'rules' => ['exists:categories,id']
            ]
        ];
    }

    public function resolve($root, $args)
    {
        $quest = Quest::findOrFail($args['id']);
        $quest->fill($args);
        $quest->save();

        return $quest;
    }
}

Schemas

All the hard work is done! Now we have to put everything together.

We have to register our queries, mutations, and types in our config/graphql:

<?php

return [
    // ... some code

    'schemas' => [
        'default' => [
            'query' => [
                'quest' => \\App\\GraphQL\\Queries\\Quest\\QuestQuery::class,
                'quests' => \\App\\GraphQL\\Queries\\Quest\\QuestsQuery::class,
                'category' => \\App\\GraphQL\\Queries\\Category\\CategoryQuery::class,
                'categories' => \\App\\GraphQL\\Queries\\Category\\CategoriesQuery::class,
            ],
            'mutation' => [
                'createQuest' => \\App\\GraphQL\\Mutations\\Quest\\CreateQuestMutation::class,
                'updateQuest' => \\App\\GraphQL\\Mutations\\Quest\\UpdateQuestMutation::class,
                'deleteQuest' => \\App\\GraphQL\\Mutations\\Quest\\DeleteQuestMutation::class,
                'createCategory' => \\App\\GraphQL\\Mutations\\Category\\CreateCategoryMutation::class,
                'updateCategory' => \\App\\GraphQL\\Mutations\\Category\\UpdateCategoryMutation::class,
                'deleteCategory' => \\App\\GraphQL\\Mutations\\Category\\DeleteCategoryMutation::class,
            ],
            'middleware' => [],
            'method' => ['get', 'post'],
        ],
    ],

        'types' => [
       'Quest' => \\App\\GraphQL\\Types\\QuestType::class,
       'Category' => \\App\\GraphQL\\Types\\CategoryType::class
    ],

    // some code 
];

Now that all that's done, let's try out our APIs.

How to Test the Queries

Our GraphQL library provides us with an IDE.

So make sure your Docker containers are running and head into http://localhost/graphiql.

You should see something like this:

Let us test our queries:

Fetch a Single Quest

Fetch a List of Quests

Insert a Quest into the Database

Update a Quest

Delete a Quest from the Database

Conclusion

Congratulations, you have created your first GraphQL API.

In summary:

• A GraphQL API consists of three parts: Queries, Types, and Mutations.
• Mutations manage your CRUD operations.
• Queries fetch from the database.
• Types are the model resource that gets returned to the client.

Thank you for reading!