Rewrite your old admin in less than a week.

01 · why the rewrite never happens

The admin is load-bearing, so it never gets its turn.

Everyone agrees the old admin should be replaced. It still isn't, and the reasons are always the same three.

Notice that none of these say the work is hard. The blocker is that the rewrite can only be imagined as one big block that gets scheduled all at once, and it never will be. The fix is to make it not one big block.

02 · where Avo fits

Avo doesn't replace your app. It joins it.

Avo is a Rails engine you mount at its own path inside the app you already run. Same database, same models, same deploy. There's no new service to operate, no data to sync, and no second system to keep in step with the first.

Because it lives at its own path, it runs side by side with your current admin. The old one keeps working while you build the new one behind it, gated by the same authentication you already trust.

This is the whole reason a rewrite collapses into a week. You aren't migrating data or standing up infrastructure. You're describing models you already have, in an app that's already deployed, and cutting over one screen at a time when you're ready. Nothing about it is big-bang.

03 · what maps to what

Whatever you're replacing, most of the rewrite is translation.

Almost everything your old admin does has a direct Avo equivalent, so you're mostly re-describing screens you already understand, not redesigning them.

A first resource is about as much code as it sounds. This is a full Index, Show, New, and Edit for Post, the screen you would have hand-written or the Active Admin block you would have ported:

class Avo::Resources::Post < Avo::BaseResource
  def fields
    field :id, as: :id
    field :title, as: :text
    field :published_at, as: :date_time
    field :author, as: :belongs_to
  end
end

An admin framework maps just as cleanly: Active Admin register blocks, filters, scopes, and member actions each have a one-line Avo equivalent, and dashboards and stats pages become Avo dashboards of cards. For a fuller side-by-side, see the Active Admin comparison or how Avo stacks up against the other admin frameworks.

04 · the week, day by day

A quarter's worth of dread, spent in five days.

Here's what the week actually looks like. It works because every step ships something real, and nothing is held back for a single cutover at the end.

Prefer to prompt?

Hand this to Claude Code, Cursor, or whatever agent you build with, and review the port like any other pull request.

Replace the admin in my Ruby on Rails application with Avo 4 (https://avohq.io, docs at https://docs.avohq.io/4.0/), without ever taking the old one offline.

1. Add the avo gem, bundle, run bin/rails generate avo:install, and mount Avo at /avo, beside the existing admin, behind the same authentication.
2. List every model the current admin manages. For each one, run bin/rails generate avo:resource <model> and port the pieces one to one: columns and form inputs become field declarations, filters become Avo filters, scopes point at the model scopes that already exist, and custom operations become Avo Actions calling the same service objects.
3. Wire authorization through my existing Pundit policies; if the old admin used CanCanCan, port the abilities to policies once (https://docs.avohq.io/4.0/authorization.html).
4. Go resource by resource and ship each one as it reaches parity. Do not wait for a big-bang cutover; both admins run side by side on the same models.
5. Verify each ported resource against the old screen: same columns, same filters, same permissions for each role.
6. When the last workflow is over, keep the old admin mounted for a week as a safety net, then delete its routes and code.

05 · and it stays replaced

You did it once, and you don't own it forever.

The reason the rewrite kept slipping is the same reason it's worth handing off: the admin is pure overhead, no matter how well you build it. Once it runs on Avo, that overhead is ours.