The Right Shape

Coding agents made it cheap to rebuild the small SaaS tools your app depends on: feature flags, analytics, forms, a helpdesk. But most people rebuild them in the wrong shape. One new app per tool, one new deployment per tool, one new database per tool. That turns a subscription bill into an operations bill.

The right shape already ships with Rails: the engine. One host application, one deployment, one database server. Every feature you take back from a vendor becomes a mounted engine with its own repository, its own tests, and its own agent working on it.

This book builds that fleet, on the page, engine by engine.

What you build

• homeport, the host application. Rails 8.1, SQLite, Solid Queue, one server.
• active_flags, a feature-flag engine, built by hand so you learn every file.
• active_metrics, a privacy-first analytics engine. No cookies, no npm dependencies.
• active_forms, a forms and survey engine. Rendering in host pages, extension points, file uploads.
• active_desk, a support-desk engine, built by coding agents from a written spec, with the full session log and the real token cost.
• active_audit, extracted from the host with the strangler pattern.

Every chapter that writes code has a frozen chapter-NN git branch. Every code block in the book matches its branch exactly.

What you learn

• What an engine really is. The book opens with a 19-line engine written by hand, no generator.
• Namespaces, migrations, mounted dashboards, and the classic main_app route helper bug.
• The public facade pattern: the one part of an engine the host may touch.
• Middleware, jobs, assets, and Active Storage inside an engine.
• Authentication at the boundary: engines do not own identity.
• Why an engine is the right unit of work for a coding agent: a bounded context that fits in a context window, with a test suite as the leash.
• How to review agent output, and when to throw a branch away.
• The honest comparison: engines against Packwerk packs, microservices, and a plain monolith. Including when an engine is the wrong choice.
• Shipping: gemspec hygiene, versioning, upgrades, operating the fleet, and responding to a real CVE.

I’ve spent years building engines in production, from Active Storage Dashboard to ActiveCanvas, and talking about them at conferences. This book is everything I know about the shape, written down.

Stop renting software you can now build.