Visualizing Your Domain Model in Rails

Why?

The MVC architecture of Ruby on Rails already does well to follow a practice of separation of concerns, and inherently has compartmentalized your domain model for you already (as well as each part of that domain model’s connected views and controllers). However, once associations between different models come into play, as in the case of a has-many-has-many or a has-and-belongs-to-many relationship, the connectivity of the moving parts can get a bit tricky.

Wouldn’t it be nice if instead of scanning through different model and database files to see that your associations are perfectly in place and that the attributes you’d like in each of your tables are all there, there was a way to verify that what you had mapped out in your initial whiteboard domain modeling is actually all there? Enter Rails ERD.

Getting started with rails-erd

This gem relies on open source graph visualization software, Graphviz, to generate a diagram for us that cleanly displays our models, the data connected to each of those models Active Record, and the relationships between those models. On the note of relationships, Rails ERD is capable of easily analyzing meta-programmed associations.

To install, first make sure you have Graphviz installed. The easiest way to do this is through Homebrew:

% brew install graphviz

Then simply install the gem:

% gem install rake-erd

To use the gem require it in your Gemfile:

group :development do
  gem 'rails-erd'
end

and use Bundler to make sure you have all dependencies

% bundle install

Examples

Refinery is a modular and extendable CMS for creating custom content manageable websites. Refinery is an open source project and has a relatively straightforward domain model that makes it a strong showcase example for Rails ERD.

http://voormedia.github.io/rails-erd/gallery.html

The diagrams provided by Rails ERD uses UML:

The Unified Modeling Language (UML) is a general-purpose, developmental, modeling language in the field of software engineering, that is intended to provide a standard way to visualize the design of a system

To give a more precise example, we will rely on a Playlister domain model that includes models for Song, Artist, Genre, and SongGenre (that will serve as a join table). First we will create a database and make the proper migrations such that our schema will end up like this:

ActiveRecord::Schema.define(version: 20160818105014) do
create_table "artists", force: :cascade do |t|
    t.string   "name"
 end
create_table "genres", force: :cascade do |t|
    t.string   "name"
 end
create_table "song_genres", force: :cascade do |t|
    t.integer  "song_id"
    t.integer  "genre_id"
 end
create_table "songs", force: :cascade do |t|
    t.string   "name"
    t.integer  "artist_id"
 end
end

Once we’ve created (or even more easily, generated) our models, we will use ActiveRecord macros to give them the associations we would like:

class Artist < ActiveRecord::Base
  has_many :songs
  has_many :genres, through: :songs
end
class Genre < ActiveRecord::Base
  has_many :song_genres
  has_many :songs, through: :song_genres
  has_many :artists, through: :songs
end
class Song < ActiveRecord::Base
  belongs_to :artist
  has_many :song_genres
  has_many :genres, through: :song_genres
end
class SongGenre < ActiveRecord::Base
  belongs_to :song
  belongs_to :genre
end

Now that our models have been set up, our migrations have been made, and our associations declared, we simply run a rake task that comes with the Rails ERD gem and should get a response:

% rake erd
Loading application environment...
Loading code in search of Active Record models...
Generating Entity-Relationship Diagram for 4 models...
Done! Saved diagram to erd.pdf.

in your root directory, you now have access to a clean visualization of your domain model.

For more examples see the Rails ERD website’s gallery. To see what sort of customization features exist, read about their options attributes.