DEV Community: Luis Donis

How I Structure a Modular Rails SaaS Application

Luis Donis — Wed, 11 Mar 2026 03:00:00 +0000

How I Structure a Modular Rails SaaS Application

In my previous post, I wrote about the Rails SaaS architecture I wish I had 5 years ago.

The main idea was simple: once a Rails application grows into a real SaaS product, the problem is no longer just writing features quickly.

The real challenge becomes keeping the system understandable.

That naturally leads to the next question:

What does that structure actually look like in practice?

This post is my attempt to answer that.

It is not the only way to organize a Rails app.
It is just the structure that currently makes the most sense to me for products with multiple business capabilities, internal tooling, and long-term growth.

The Problem With the Default Growth Path

Most Rails applications begin with a very reasonable structure:

app/
config/
db/
lib/

That works well at the beginning.

But as the product grows, many business capabilities start living side by side in the same application layer:

authentication
roles and permissions
notifications
dashboards
auditing
support tickets
file management
billing logic
admin tools

At that point, the issue is not that Rails is bad.

The issue is that everything starts competing for space inside the same app boundaries.

Models become aware of too much.
Controllers start coordinating unrelated concerns.
Helpers grow in weird directions.
Concerns multiply.
And eventually, the application feels large even when individual features are not that complex.

The Shift: Structure by Capability

What has worked better for me is structuring the system by business capability instead of only by technical layer.

So instead of thinking only in terms of:

models
controllers
views

I think in terms of:

support
audit
admin
accounts
users
dashboards
billing

Each of those capabilities gets its own boundary.

In Rails, the cleanest way I have found to do that is with engines.

A Simple High-Level Structure

A modular Rails SaaS application might look like this:

my_app/
├── app/
├── config/
├── db/
├── lib/
├── engines/
│   ├── lesli_core/
│   ├── lesli_admin/
│   ├── lesli_audit/
│   ├── lesli_billing/
│   ├── lesli_dashboard/
│   ├── lesli_shield/
│   └── lesli_support/
└── Gemfile

The main application still exists.
But it is no longer the place where every feature gets dumped.

Instead, the main app acts more like the integration layer.

The engines contain the actual business capabilities.

What Belongs in the Main App?

This is the part that matters most.

A modular structure only works if the main app stays disciplined.

In my case, the main Rails app is usually responsible for:

environment configuration
deployment configuration
boot process
mounting engines
app-specific branding and overrides
product-specific custom logic
final composition of the system

So the app is still important.
It just stops pretending to own every domain directly.

What Belongs in an Engine?

Each engine owns a clear capability.

For example, a support engine might contain:

engines/lesli_support/
├── app/
│   ├── controllers/
│   ├── models/
│   ├── views/
│   └── components/
├── config/
│   └── routes.rb
├── db/
│   └── migrate/
├── lib/
│   └── lesli_support/
├── lesli_support.gemspec

That engine can own:

tickets
comments or discussions
statuses
priorities
assignment flows
support-specific dashboards
notifications related to support

That creates something extremely valuable:

local reasoning.

When I need to work on support, I go to the support engine.
I am not hunting through a giant application trying to remember where ticket logic leaked into other layers.

The Role of a Core Layer

I still like having a shared core layer.

But I think it should stay small and intentional.

For me, a core engine usually contains things like:

shared concerns that are truly cross-cutting
shared UI primitives
base classes
common helpers
platform configuration helpers
common interfaces between engines

What I try to avoid is turning the core layer into a second monolith.

If core becomes the place where every engine dumps shared shortcuts, then the architecture slowly collapses back into the same problem.

So the question I ask is:

Is this really cross-cutting, or am I just avoiding a cleaner boundary?

Routing and Composition

One thing I like about this approach is that composition stays explicit.

The main application decides what gets mounted.

A simplified example might look like this:

Rails.application.routes.draw do
  mount LesliAdmin::Engine, at: "/admin"
  mount LesliSupport::Engine, at: "/support"
  mount LesliAudit::Engine, at: "/audit"
end

That makes the final application shape easy to understand.

The product is not a mystery.
It is a composition of capabilities.

Boundaries Matter More Than Reuse

A nice side effect of engines is reuse.

But honestly, that is not the main reason I like them.

The bigger benefit is enforced boundaries.

Without boundaries, every feature eventually reaches into everything else.

With boundaries, integration has to be intentional.

That changes how the codebase grows.

You start asking better questions:

Should this dependency exist?
Does support really need to know about billing internals?
Is this concern shared, or just misplaced?
Should this logic live in the app, the engine, or the core layer?

Those questions improve architecture more than any naming convention ever will.

This Is Not Free

To be fair, this kind of structure also adds some overhead.

You have to think more about things like:

engine naming
domain boundaries
dependency direction
migrations across engines
shared conventions
local development workflow

So I would not use this for every project.

If you are building a small internal tool, an MVP, or something you need to ship very quickly, this can feel like too much structure too early.

But when the product starts growing across multiple capabilities, that extra structure stops feeling heavy and starts feeling useful.

What I Like Most About This Approach

What I like most is not that it feels more “advanced.”

It is that it makes the system easier to work with.

When I add a feature, I have a better idea of where it belongs.
When I debug something, I am not jumping across unrelated parts of the app.
When I refactor, I feel a little more confident that I am not breaking everything around it.

For me, that is what good architecture should do.

Not win abstraction points.
Not look impressive on a diagram.

Just make the app easier to understand as it grows.

How This Connects to Lesli

This is the same general direction I have been exploring while building Lesli.

I am not trying to make Rails more complicated.
I am mostly trying to give larger SaaS-style applications a cleaner place to grow.

Lesli is still evolving, but this modular approach is one of the ideas behind it.

The Rails SaaS Architecture I Wish I Had 5 Years Ago

Luis Donis — Sun, 22 Feb 2026 02:24:00 +0000

The Rails SaaS Architecture I Wish I Had 5 Years Ago

Five years ago, I started building SaaS applications with Ruby on Rails.

Like most Rails apps, everything started beautifully simple.

A few models.
A few controllers.
Some concerns.
Some service objects.

It felt clean.

Six months later?

Business logic everywhere
“Temporary” modules that became permanent
Cross-cutting features tangled across the app
Shared helpers doing too much
Growing fear of refactoring core features

The app still worked — but the architecture wasn’t intentional anymore.

And that’s the real problem.

The Pattern I Kept Repeating

Every SaaS I built ended up having the same core capabilities:

Authentication
Roles & permissions
Notifications
Audit logs
Dashboards
Support tickets
Document management
Account scoping / multi-tenancy

But I kept rebuilding them inside the main app.

Every. Single. Time.

And every time, they slowly leaked into everything else.

The Architecture Shift

At some point I started asking myself:

What if SaaS capabilities weren’t just folders inside /app?
What if they were isolated systems?

Instead of structuring only by MVC, I started structuring by capability.

Each major SaaS feature became its own Rails engine:

Auth engine
Support engine
Audit engine
Dashboard engine
Admin engine

Each engine:

Owns its models
Owns its controllers
Owns its routes
Owns its views
Owns its database tables
Has explicit integration points

No leaking constants.\
No random cross-feature helpers.\
No accidental coupling.

Just clear boundaries.

Why Engines?

Rails engines are often misunderstood.

Many developers think they’re only for gems or mountable admin panels.

But for SaaS architecture, they provide something incredibly valuable:

Structural isolation.

When features live in engines:

You can reason about them independently
You can test them in isolation
You can disable or replace them
You reduce accidental coupling
You avoid the “god app” problem

The main Rails app becomes the orchestrator — not the dumping ground.

What This Changes in Practice

Instead of this:

app/models/user.rb
app/models/role.rb
app/models/ticket.rb
app/models/audit_log.rb

You get something like this:

engines/auth/app/models/auth/user.rb
engines/support/app/models/support/ticket.rb
engines/audit/app/models/audit/log.rb

Clear ownership.

Clear responsibility.

Clear boundaries.

The Real Benefit: Cognitive Load

The biggest improvement wasn’t performance.

It wasn’t scalability.

It was mental clarity.

When a bug appears in support logic, I know exactly where to go.

When I need to extend auditing, I don’t fear breaking unrelated features.

Architecture stops being accidental.

It becomes intentional.

Is This Over-Engineering?

For small apps?

Probably.

For serious SaaS products?

Not really.

Once your application has:

Multiple accounts
Role systems
Permissions
Notifications
Background processing
Operational tooling

You’re no longer building “just a Rails app.”

You’re building infrastructure.

What I’m Doing Now

I’m currently building an open-source Rails framework based on this idea.

Each SaaS capability lives in its own engine.

The goal isn’t to abstract everything.

The goal is to start with intentional structure — instead of cleaning up chaos later.

It’s still evolving.

I’m still learning.

But it already feels more sustainable than anything I built five years ago.