What Does Your Rails App Really Scream? It Shouldn’t Just Be “Rails!”

Ruby on Rails. The very name conjures up images of rapid development, convention over configuration, and getting things done quickly. And it delivers on that promise! We can scaffold controllers, models, and views with a few simple commands, building functional applications in no time.

But have you ever taken a step back and looked at the structure of your growing Rails application? What does it truly communicate at a glance? Too often, the answer is simply: “I’m a Rails app!”

Consider the typical Rails folder structure:

app/
├── controllers/
│   └── orders_controller.rb
├── models/
│   └── order.rb
└── views/
    └── orders/
        ├── index.html.erb
        ├── show.html.erb
        └── ...

Familiar, isn’t it? This structure is ingrained in the Rails way of doing things. We instinctively know where to find our controllers, models, and views related to orders. However, this structure primarily speaks to the framework being used. It tells us nothing about the business the application serves. Is it managing pizza orders? Hotel bookings? Financial transactions? The framework-centric organization leaves us guessing.

This is where the insightful concept of Screaming Architecture, championed by Robert C. Martin (Uncle Bob), comes into play. The core idea is elegantly simple:

When you look at a system’s structure, you should instantly know what the core business is — not just the framework it uses.

Imagine a newcomer joining your team. Looking at the standard Rails structure, they might understand the basic MVC flow, but grasping the underlying business logic will require diving deep into individual files and piecing together the narrative.

Let’s illustrate this with a more concrete example — a pizza delivery application, just like in the LinkedIn post.

Instead of the standard structure, what if our app/ directory looked something like this?

app/
├── pizza/
│   ├── orders/
│   │   ├── creator.rb
│   │   ├── canceller.rb
│   │   └── tracker.rb
│   └── delivery/
│       ├── driver_assigner.rb
│       └── route_optimizer.rb
├── payments/
│   └── processor.rb
└── web/ # Or 'controllers' if you prefer, but focused on the web interface
    ├── pizza/
    │   └── orders_controller.rb
    └── payments_controller.rb

Now, take a moment to observe the difference. What does this structure scream?

“I deliver pizzas!”

The top-level directories — pizza, payments – immediately hint at the core domains of the application. Drilling down into pizza/orders reveals key business processes related to order management: creation, cancellation, and tracking. Similarly, pizza/delivery clearly outlines functionalities around getting those pizzas to customers. The payments directory speaks for itself.

Here’s a breakdown of why this domain-centric approach is so powerful:

1. Domain Front and Center

The most significant advantage is that the core business domain takes precedence. Developers, both new and experienced, can quickly understand the application’s purpose by simply navigating the directory structure. The “what” of the application is immediately apparent, not just the “how” provided by the framework.

2. Encapsulated Business Logic

By organising code around business features or domains, we naturally tend to encapsulate the core business logic within these modules. For instance, the pizza/orders/creator.rb is likely to contain the intricate steps involved in creating a new pizza order, potentially involving inventory checks, customer validation, and order item creation. This keeps the business rules together and makes them easier to locate and maintain.

3. Leaner Controllers and Focused Models

In this architecture, controllers become primarily orchestrators. They receive web requests, delegate the actual business logic to the appropriate domain services (like Pizza::Orders::Creator), and then handle the response (rendering a view, redirecting, etc.). Models, on the other hand, remain focused on data persistence and validation relevant to their specific entities (e.g., an Order model might handle database interactions and basic data constraints). This separation of concerns leads to cleaner and more maintainable code.

4. Testable Core Workflows

Because the business logic is encapsulated in plain Ruby objects (POROs) within the domain layers, these crucial workflows can be tested in isolation, without the need to boot up the entire Rails environment. This leads to faster and more reliable unit tests for the core functionality of your application. You can test the pizza order creation process without even touching a controller or a view.

The Sweet Payoff

Adopting a Screaming Architecture in your Rails applications yields significant benefits in the long run:

• Faster Onboarding: New team members can quickly grasp the business domain, reducing the learning curve and enabling them to contribute meaningfully sooner. They’re not just navigating framework conventions; they’re understanding the core purpose of the application.
• Reusable and Framework-Agnostic Business Rules: The business logic encapsulated within the domain layers becomes more easily reusable across different parts of the application and potentially even in other systems or contexts. Because it’s decoupled from the Rails framework, it’s more resilient to changes in the underlying technology.
• Resilient Architecture: If, for some reason, you decide to migrate parts of your application to a different framework or even a microservices architecture, the well-defined business logic within your domain layers can be extracted and reused with relative ease. Your core business rules aren’t tightly coupled to Rails.

Making the Shift (It Doesn’t Have to Be All at Once)

Implementing a Screaming Architecture doesn’t necessarily require a complete rewrite of your existing Rails application. You can start incrementally by identifying key business domains and gradually refactoring related code into dedicated directories.

For example, you might begin by creating a pizza/ directory and moving all order-related logic (models, services, background jobs) into sub-directories within it. Then, you can adjust your controllers to interact with these domain-specific components.

Rails is Fantastic, But…

Rails provides an excellent foundation for building web applications rapidly. However, by consciously structuring our applications to reflect the business domain, we can create systems that are not only fast to build but also easier to understand, maintain, and evolve.

Let’s leverage the power and flexibility of Ruby on Rails to build applications that scream their purpose loud and clear — whether it’s delivering pizzas, managing logistics, or revolutionizing finance — and not just that they are “another Rails app.” It’s about shifting the focus from the tool to the craft and the value it delivers.

References:

1. https://dev.to/nilebits/what-is-screaming-architecture-442o
2. https://www.codingblocks.net/podcast/clean-architecture-make-your-architecture-scream/
3. https://www.nilebits.com/blog/2024/09/what-is-screaming-architecture/
4. https://gist.github.com/ygrenzinger/14812a56b9221c9feca0b3621518635b

Explore more articles and insights on software engineering and technology on the Rently Engineering Blog: https://engineering.rently.com/