Project

pferd

0.0
The project is in a healthy, maintained state
Generate domain-based ERDs for Rails. Useful for modelling potential conformations before committing to them
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Dependencies

Runtime

 Project Readme

Pferd

Pferd is a Ruby gem that generates an Entity Relationship Diagram (ERD) of your Ruby on Rails models, automatically grouping models by their domain. This is useful when you are in the process of modularising your codebase, and want to visualise various domain configurations without having to move code around.

The diagram (optionally) highlights domain boundary violations, giving you insights into possible cross-domain coupling issues.

Installation

Add this line to your application's Gemfile:

gem 'pferd'

And then execute:

bundle install

Or install it directly using:

gem install pferd

Usage

To generate an ERD, simply run:

rake pferd:generate

Defining Domains

Pferd groups your models by domain using the @domain YARD tag. To specify the domain of a model, add a YARD comment above the model class definition. For example:

# @domain payments
class Transaction < ApplicationRecord
  # Model code
end

If a model does not have a @domain tag, it will be placed in the default domain (Global by default).

Configuration

Pferd comes with configurable options that you can customise. Below is the default configuration:

# Establish some default configs
Pferd.configure do |config|
  # Classes without an explicit domain tag should be in this domain
  config.default_domain_name = 'Global'

  # Exclude these classes
  config.ignored_classes = []

  # Exclude classes nested in these modules
  config.ignored_modules = ['ActiveStorage']

  # Load models matching these glob-paths
  config.model_dirs = ['app/models']

  # The name of the generated output file
  config.output_file_name = 'pferd.png'
end

How to customise:

You can modify the configuration within an initializer (config/initializers/pferd.rb):

Pferd.configure do |config|
  config.default_domain_name = 'Core'
  config.ignored_classes = ['SomeTemporaryModel']
  config.ignored_modules = ['ActiveStorage', 'ActionMailbox']
  config.model_dirs = ['app/models', 'engines/*/app/models']
  config.output_file_name = 'custom_erd.png'
end

Domain Boundary Violations

Pferd will analyse your model associations and highlight where models reference entities from another domain. Violations will be clearly marked in the ERD using special edge styles (e.g., dashed or highlighted lines).

This feature helps you identify and address cases where models may be overstepping domain boundaries, promoting better separation of concerns within your codebase.

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration.

License

Pferd is available as open source under the terms of the MIT License.