I am BARRY HESS > Blog

A Model Diagram for Your Rails Application

Recently I started working on a fairly large existing application. Lots of stuff going on, and I wanted a visualization of both the model and controller classes to make me feel that indeed the application could be encapsulated. In my search, I ran into two libraries that could help me do such a thing. The first was Rails Application Visualizer and the second was Railroad. Both use the GraphViz library to do the grunt work. I chose Railroad mainly because it was a gem and nonintrusive to the application.

The first requirement in using Railroad is to get GraphViz installed. Eventually I found this excellent series of Mac builds from RyanDesign. They are easily installed and he has a great FAQ describing everything you need or may wish to do to setup the GraphViz library on your Mac.

Here is the process I went through:

Install GraphViz

I downloaded the latest Intel Mac build and installed it. For me, GraphViz ended up in /usr/local/graphviz-2.12/. Then I created a symlink:

cd /usr/local
sudo ln -s graphviz-2.12 graphviz

Then I updated ~/.bash_profile to bring GraphViz into my path. This allowed me to call dot and neato on the command line.

export PATH=/usr/local/graphviz/bin:$PATH

Finally, I reloaded bash so all the exports were refreshed:

source ~/.bash_profile

Install Railroad

Pretty easy:

gem install -y railroad

Generate model and controller diagrams

After quite a bit of playing around, I settled on the following calls to generate my model and controller diagrams. My biggest hurdle is that I don’t have a way to tile print super-large PDF’s, given I’m only using base OSX tools (i.e. Preview). So these commands gave me the most printable output. Luckily I just bought a new laser printer!

Generating a model diagram:

railroad -Mal | dot -Tpdf > models.pdf

The ‘M’ switch tells railroad to create a model diagram. The ‘a’ switch includes all models, not just ActiveRecord::Base models. And the ‘l’ switch throws a label on the diagram about when it was created and which migration version it represents. The PDF diagram seemed cleanest and it printed decently on a single page - if I squint.

And a controller diagram:

 railroad -Cl | neato -Tpng > controllers.png

On the other hand, the controller diagram did not work well in PDF. Since none of the controllers were interrelated, the results were a single “line” of controllers spreading out horizontally. Not printable. The PNG format fit all the classes onto a page rather nicely.

The Railroad site has plenty of good documentation and examples for you to play with. So why don’t you go visualize your app already?