Chapter 1


1.1. About the updated edition

It has been over 4 years since the original release of Modular Rails. Wow, it’s been a while… and what a journey. A lot of learning has happened during this time, which has led to a lot of changes in this new edition! But the biggest change is not programing-related; Instead, it is the fact that I’m being joined by someone else for this new version, and his name is Theo!

Theo is a reader of the first edition of this book and has joined me as co-author. Modularity is ingrained in his company (bluVerve), so who better to add some input than someone whose company is built on the whole philosophy behind this book?

Sadly, we haven’t had the opportunity to update Modular Rails before this, because… life happens. Thibault moved to a new company (OmiseGO), spent some time focusing on himself and wrote another book (you should check out Master Ruby Web APIs - it pairs up quite nicely with this book). But with Theo’s help, things have started moving forward at a good pace.

I’m extremely happy to have him on board, and since it’s not just me anymore, all the “I”s have been replaced by “we”s in the rest of the book. We are excited to take you on an updated journey through modularity!

Modularity has helped a lot of people structure their applications in a more efficient and maintainable way, which is why we thought it was time to upgrade the book to Rails 5.2. It is important to make sure that it is kept up to date, and incorporates all the new features of Rails that relate to modularity. Rails is, after all, the best example of a modular system.

The main changes are the following:

  • The contents will be structured in a more logical manner that will be easier to follow
  • We will be using Ruby 2.6.3 (we suggest using RVM to manage your rubies, and you can install Ruby 2.6.3 by running rvm install 2.6.3)
  • We will be using Rails 5.2 (more specifically, 5.2.3)

If you’re an old reader, we hope this book helps you update your code, and that you get as much use out of it as you did from the previous version. If you’re new to modularity, you’re in for an exciting ride (Seriously, no jokes… you’ll be wondering why you never structured your applications like this from the beginning).

1.2. Introduction

The most commonly used architecture when developing a Ruby on Rails application, is monolithic. We all have had experience in building such applications; we group components by function, we create a folder for our controllers, a folder for our models, another folder for our views, and so on, and so on… For simple applications, this is more than enough. But what happens when our application does not fit the conventional scope of a “simple application”?

With growth comes complexity! Modular Rails offers a different solution (a different architecture, to be precise), that can handle larger, more complex applications. Adding another layer of abstraction will result in a cleaner codebase that is easier to deal with. The layer of abstraction proposed in this book is Modules. Not Ruby modules though, but business modules, that allow the grouping of multiple types of components and entities that belong in the same business domain.

Box 1.1. Modularity in Rails vs Modularity in your application

Ruby on Rails, by its nature, is modular. In fact, the use of gems makes your application modular (the gems are your “modules”). One could argue that by the mere fact that you are using Rails, your application is modular (because Rails is), but that is not what we’re trying to achieve here. This book aims to introduce modularity in your own code, by splitting your application in the business modules we mentioned earlier.

To give you a simple example, if you were to build a social media application, you could split it into three modules:

  • one module that deals with everything related to users and their friends
  • one module for a “group” / “page” feature
  • one module for the administration

You would probably end up with more than that in a real application, but this should give you an idea of where we’re going. In each one of these modules you would find the usual components (controllers, models, etc.), but only if they’re dealing with that domain logic, moving away from the usual monolithic application that often lacks structure. Your application will now be built brick by brick, module by module, putting together pieces of code that work togeter to fulfil your requirements.

Building a web application in a modular way can be done with many different technologies, in many different ways. In this book, we’ll be focusing on how it can be done with Ruby on Rails. Unfortunately, an application generated with Rails is not easy to break up into logical modules, which is probably why you’re reading this book! Building a modular Rails application means that you will build a set of reusable modules, somewhat like libraries, with very specific functionalities. Then you will simply put them together, just like bricks, to build your application.

Building modular applications is not easy. You won’t be building your web application like everyone else, and finding help will be hard. There is not much documentation either, but with this book you will be able to learn a lot. And if you still have questions after reading this book, we will gladly help you further!

1.3. Who are we ?

1.3.1. Thibault Denizet

I am Thibault Denizet. That’s me in the picture. I’m a young, dynamic Ruby on Rails developer who lives in Bangkok. I’m actually French but I hate the cold weather and I also dislike cooking. So logically, I came to a country where it’s always (too) hot and I don’t have to cook. Thailand is a great country to live in. If you ever come by, let me know so we can grab a beer!

My story with modularity started over two years ago, when I was charged with the rewriting of an existing web application into something more configurable and modular. I’ve been working on a few modular applications since then, while still creating regular apps when modularity was overkill.

I wrote the first revision of this book because I couldn’t find any documentation when I created my first modular application. I was studying open source apps, and even though reading code is a great way to learn something, you don’t always understand what’s going on. This is the book I wish I had at that time. It’s not a bible; far from it. But it will teach you everything you need to know. I hope you will enjoy it! (If you don’t, please tell us what you don’t like so we can improve it.)

1.3.2. Theo Scholiadis

My name is Theo Scholiadis. I am Greek and live in Cape Town, South Africa. No, I don’t break my plates after dinner, and yes, I do come with only 2 volumes: loud and louder. Give me some good Greek food, a glass of whiskey (OK, OK, a beer is good too) and some good music, and we have the start of a great evening!

Back in my university days I got my hands on a “PHP and MySQL Web Development” book, and one question stuck with me: “Why on earth is this not more mainstream? Write the software once, install it on a server (instead of every machine and worrying about licenses), and any computer with a browser can use it!” Needless to say, when I started digging into Ruby on Rails, I was hooked.

When I started my company to write software for the maritime industry, I wanted to implement one core rule: re-use as much code as possible. This led me down the path of writing modular programs, but there was not much out there in effectively implementing modularity with Ruby on Rails. When I found Thibault’s Modular Rails, I immediately contacted Thibault and asked to get involved in any way possible, even if it was just to proof the book (don’t tell Thibault, but I just wanted to make sure he kept updating the book). Little did I know that Thibault had bigger plans, and 1 year later I’m co-authoring the book with him!

I hope you find this book as useful as I did, and please feel free to pop us a message with things we can add to make it better and more useful to you, our readers.

1.4. Who is this book for?

We believe every Ruby on Rails developer should read this book at least once. It’s not long, but it comes with a lot of ‘under-the-hood’ information about engines. Of course, if you’re about to write a modular application, then you should definitely read it.

The goal is to teach you how to build your own modules and, at the end of the road, create a complete modular applications.

This book will probably be more useful to web development companies and freelancers, or anyone who ends up building the same (or even similar) thing over and over again.

1.5. How is this book organized?

This book has been separated into 3 modules, each with a number of chapters attempting to achieve a specific goal, or teach you a specific principle. The modules in this book are the following:

Module 1: What is Modularity

This is the module you’re currently reading. It explains the concepts of Modularity, as well as show you when you should use modularity and when it will be overkill.

  • Chapter 01: Introduction (what you’re currently reading)
  • Chapter 02: The Modular Way
  • Chapter 03: Rails & Modularity Basics

Module 2: The Core Module

In this module you will learn how to set up your parent Rails application so that all your modules can be plug-and-playable. We will also help you create your first module, the Core module, which will be a requirement for all your business modules.

  • Chapter 04: Set up
  • Chapter 05: Authentication
  • Chapter 06: Automated Tests with RSpec
  • Chapter 07: The Admin Panel
  • Chapter 08: Authorization with Pundit

Module 3: The Contacts Module

Here we will create our first business module: the Contacts module. We will show you how we integrate it in our application, while still maintaining our application’s modularity.

  • Chapter 09: Set up
  • Chapter 10: Adding a Controller
  • Chapter 11: Extending Views
  • Chapter 12: Extending Models & Controllers
  • Chapter 13: Exercise: Extending the Admin Panel

Module 4: The Tasks Module

Here we will create our second business module: the Tasks module. Like we did with our Contacts module, we will, again, show you how we integrate it in our application, while still maintaining our application’s modularity.

  • Chapter 14: Set up
  • Chapter 15: Controllers & Views
  • Chapter 16: Listing Tasks in Contacts
  • Chapter 17: Extending the Dashboard
  • Chapter 18: Exercise: Extending the Admin Panel

Module 5: Deployment

Finally we will show you how to deploy your application, as well as maintain it.

  • Chapter 19: Packaging Engines
  • Chapter 20: Managing Engines
  • Chapter 21: Publishing Engines
  • Chapter 22: Deploy your Application

1.6. How to read this book?

This book is meant to be read in the prescribed order, from beginning to end, but you’re welcome to use it as a reference and read it the way you want. Modules 2 and 3 contain most of the source code, and probably where you will learn the most, especially if you code along. We have tried to provide ample explanations and screenshots so that writing code is not mandatory, so you should be able to simply read through and start coding when you’re ready.

1.7. Some things to note

1.7.1. Terminology: Module & Engine

Throughout this book we will be using the terms modular (or module) and engine a lot. Like, a lot a lot. We use these two terms interchangeably and when we refer to module, we’ll be talking about our application’s module, which is wrapped in an engine, and not a Ruby module.

1.7.2. About the code in this book

We believe that the best way to learn more about coding is by actually seeing code. This is the reason you will find a lot of source code in this book. The code is contained in ‘listings’ (colored code boxes) so that it is easily noticed. In some cases the code spans more than one page. We did our best to keep the same code snippet on one page, but sometimes it was simply not possible.

If you’re ever uncertain of where some code is supposed to go, simply check the heading of the snippet. There you will find a path indicating the file name. Most of the time it will be referenced from the top level of the Rails application (BlastCRM), but sometimes it will be too long to be displayed in one line. In these cases, you will see the path starting at the engine level. Keep in mind that engines will be stored in blast_crm/engines/.

1.7.3. Errors, bugs, problems?

We have tried our best to provide the best content possible, but alas, some typos and bugs might escape us (they are called bugs for a reason). If you do find any, please report them by opening an issue on the example code’s GitHub repo issue page, located at We will be eternally grateful and will add your name to the Thank You page!

1.7.4. Requirements

To follow the tutorials in this book, it would be preferable that you work on some kind of Unix or Linux system, because we use the command line intensively to work on our modular application. If you’re on Windows, you can easily setup a virtual machine with VirtualBox and Ubuntu.