Developer exploring open-source code and system design concepts.

Recently, I explored the GitHub repo for cal.diy to gain a deeper understanding of how a calendar booking system works, particularly how it handles booking failures, double bookings, consistency with external systems like Google Calendar, and background processing for notifications and reminders.

I want to share my experience with curious tech heads like me :p Here we go!

Why not use AI?

You can absolutely use AI to explore a repo, but you need to know what questions to ask to get meaningful insights. This article focuses on helping you ask the right questions before using AI to dive into the implementation details of a GitHub repo.

Identify what to learn

An established open-source repo is usually too big to read from start to finish. We want to spend our limited time and energy learning transferable knowledge.

In this example, I'm interested in system design concepts such as:

  • Fault tolerance
  • Eventual consistency
  • Background processing
  • Locking mechanisms to prevent double bookings

For someone with less experience in the subject, a good starting point is to identify the application's main data flow.

In this case, it's pretty straightforward: the booking creation flow, which is at the heart of Cal.com's business.

Following a critical data flow often reveals important problems that engineers need to solve to ensure system availability and reliability.

Run the application

Run the application locally to visualise the data flow and understand the nuances of each step in the workflow.

The framework

Here's the framework I follow:

  1. Identify a critical workflow.
  2. Follow the workflow through the source code.
  3. Raise questions about potential failures.
  4. Investigate how the implementation addresses them.
  5. Extract the underlying system design principles and consider where else they apply.
  6. Repeat!

For example, create a booking and note down the workflow:

Reserve a slot → Fill in form details → Create a booking → Receive an email notification

Don't start by asking how a system is implemented. Start by asking what could go wrong, then use the source code to discover how engineers solve those problems.

How to raise questions about potential failures?

When you're not sure what to ask, try picking a general-purpose question from the following list:

  • Concurrency: What happens if multiple users perform this action simultaneously?
  • Fault tolerance: What happens if a dependency becomes unavailable?
  • Consistency: What happens if an operation succeeds in one system but fails in another?
  • Background processing: What happens if a task takes too long or needs to be retried?
  • Scalability: What happens when request volume increases significantly?

For example, let's look at the reserve a slot step:

  1. Raise a question: What if two people try to reserve the same slot?
  2. Explore the code: I noticed that once a slot is selected, it's reserved for five minutes by default (or for a configurable amount of time). This raises another question: Okay, but does that actually prevent two people from reserving the same slot? The answer is no.
  3. Think about the implications: So, we eventually need to prevent double bookings when create a booking happens. Maybe we can afford to be a little more relaxed about temporary reservations since they happen upstream.
  4. Keep investigating: In create a booking, I found a unique constraint that prevents repeated bookings, mainly for retried requests from the same user. But this doesn't necessarily prevent conflicting bookings from different users.
  5. Raise another question: Does the system prevent bookings with overlapping time slots?
  6. Keep going! One question leads to another, and so on and so forth.

The underlying concept here is concurrency control, which isn't unique to calendar booking systems. Similar problems exist in ticket reservations, inventory management, and many other systems.

Wrap up

By following this approach, you can read just enough code to understand the system design concepts you're interested in, without getting lost in the entire codebase.

And sometimes, you'll discover that the questions you raise aren't fully addressed in the source code. That's when you start to understand why some repos come with a warning like:

Use at your own risk.

You can also explore how these reliability issues affect real users. For example, here's a recent PR addressing concurrent bookings with overlapping time slots.

Another great learning opportunity is reading the discussions around these PRs. You get to see how engineers think through problems, weigh trade-offs, and make architectural decisions.

I hope you find this useful! If you have any other tips for learning from open-source repos, please share them.

Let the good stuff spread!