Stellwerk is a Ruby gem that helps enforce architectural rules in Ruby on Rails applications. It analyzes the codebase and identifies violations of architectural constraints specified in stellwerk.yml.

The name "Stellwerk" is derived from the German word for "signal station" in a railway context. It keeps your Rails on track!

Install the gem and add to the application's Gemfile by executing:

bundle add stellwerk

If bundler is not being used to manage dependencies, install the gem by executing:

gem install stellwerk

Create a stellwerk.yml in the root of your Rails application that defines at least one rule.

Run the check task in your Rails app:

bin/rails stellwerk:check

You can also run a simpler check without booting the app. Stellwerk will not use the app's autoloaders and instead emulate a default Rails setup. This is useful for testing or as a workaround when Stellwerk doesn't understand your autoloader setup (please report a bug in that case). There can be false positives with this mode for custom autoloader configurations.

bin/rails stellwerk:check_simple

Rules are defined in the stellwerk.yml file.

The Layered Architecture rule enforces that files in one layer do not reference files in a layer that is "above" it.

Example configuration with three layers:

rules:
  layers:
    - app/controllers
    - [ app/jobs, app/models ]
    - lib

In this scenario,

• all controllers, jobs and models can depend on stuff in lib
• controllers can additionally depend on jobs and models
• code in lib can not depend on controllers, jobs or models and jobs or models can not depend on controllers
• everything not mentioned (e.g. app/services) can depend on anything else and be depended on by anything else

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

1. Update the version in lib/stellwerk/version.rb. Push / merge to main.
2. rake release

Bug reports and pull requests are welcome on GitHub at https://github.com/exterm/stellwerk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

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

Everyone interacting in the Stellwerk project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.