The Modular Monolith in Ruby on Rails

A Rails app grows. Changes in one corner start breaking another, two teams keep colliding in the same files, and eventually someone says the word microservices.

Almost always, that's the wrong instinct. What you usually need is a modular monolith: one deployable Rails app, with real, enforced boundaries between its parts. The interesting contrast isn't monolith versus microservices — it's an organised codebase versus a big ball of mud.

This is the current, Rails 8 / Zeitwerk-era version of how I think about it. No nostalgia, no hype.

When you actually want one

Reach for a modular monolith when:

• the codebase has grown past what one person holds in their head
• there's more than one team touching it
• the domains are nameable (billing, identity, catalogue…) rather than a soup
• changes in one area keep breaking unrelated ones
• you want the option to extract a service later without betting the company on it now

If none of that is true yet, skip to the "when NOT to" section before you do anything.

Three mechanisms (and how they really compare)

There are three honest ways to draw boundaries inside a Rails app, plus the network boundary you get from microservices. They are not interchangeable.

The short version: Packwerk meets your monolith where it already is — you add it to a sprawling app and let CI tell you where the boundaries leak, without moving a single file first. Engines give you the strongest structural boundary and the cleanest path to one day lifting a slice out. Plain namespaced modules cost almost nothing and are often the right first step. Microservices buy you total isolation and charge you an operational tax for it — only worth paying when the isolation is the actual requirement.

The Zeitwerk part people trip over

Zeitwerk maps constants to file paths, and it's unforgiving on purpose: billing/ledger.rb must define Billing::Ledger. A few things follow from that:

• eager loading runs app-wide at boot, so namespace mistakes surface early instead of in production
• don't fight the namespace — when you see Zeitwerk::NameError, that's the boundary working, not the framework being difficult
• engines all contribute to one shared loader. So a constant in one engine is still technically reachable from another. Engines give you structural isolation, not privacy. If you want privacy, you enforce it (Packwerk, review, discipline) — Zeitwerk won't do it for you.

That last point catches a lot of people who assume an engine is a sealed box. It isn't.

A migration loop that doesn't break production

You don't get to stop the world and rearchitect. So the move is small, reversible steps, each with a safe stopping point:

1. Pick a seam with the fewest inbound dependencies.
2. Namespace it in place; ship.
3. Define its public API; ship.
4. Draw the boundary (Packwerk pack or engine); ship.
5. Enforce it; ship.
6. Repeat.

The point of "ship" after every step is that you can stop after any of them and still have a working, revenue-generating app. No big-bang branch that lives for three months.

When NOT to build one

This is the section most articles skip, so I'll be blunt. Don't modularise when:

• the app is young or small — you haven't collided with the real boundaries yet, so you'll guess them wrong
• the domains aren't nameable yet
• it's thin CRUD — there's no complexity to contain
• you're using architecture to fix a people or process problem. Boundaries in code won't fix a boundary problem between teams.

And a Rails 8 note: Solid Queue, Solid Cache and Solid Cable have quietly removed a lot of the old pressure to extract services just to get a queue or a cache. The case for a well-organised monolith is stronger now than it was in 2018.

FAQ

Is a modular monolith just a step towards microservices? Sometimes, but treating it as merely a stepping stone is the wrong frame. For a lot of teams it's the destination — you get most of the organisational benefit without the operational bill.

Engines or Packwerk first? If you have a large existing app you can't restructure this quarter, Packwerk first — it tells you where the boundaries actually are. If you're starting a new bounded area cleanly, an engine.

Does Zeitwerk enforce my boundaries? No. It enforces naming. Boundaries are enforced by you and your CI.

The original, kept up to date, is here: https://davidslv.uk/modular-monolith-rails/

If you want to go deeper, I wrote a free book on exactly this — Modular Rails: Architecture for the Long Game, all 18 chapters free to read online: https://davidslv.uk/books/modular-rails/ . There are runnable companion repos in it (Orbit, a worked example; and a small tool for finding seams). No sign-up wall.