Chapter 1


1.1. 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.2. 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.3. 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.4. 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.5. Some things to note

1.5.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.5.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.5.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.5.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.