ArchUnitRuby

Architecture testing for Ruby. Build a dependency graph from a Ruby codebase and guard cycles, layers, naming, metrics, slices, and diagrams as ordinary tests. The working prototype ships as the archunit gem and includes source-generated API documentation.

Ruby 3.3+MIT

View repository ↗Documentation ↗

RubyGems

gem install archunit

architecture_spec.rb

require 'archunit'

RSpec.describe 'architecture' do
  it 'keeps API away from persistence' do
    rule = ArchUnit.project_files
      .in_folder('app/api/**')
      .should_not.depend_on_files
      .in_folder('app/database/**')

    expect(rule).to pass
  end
end

The ecosystem

Ruby, in context.

Ruby is a dynamic, object-oriented language designed around expressive code and developer happiness. It is best known for Ruby on Rails, but it also powers command-line tools, background workers, APIs, and long-lived business systems. Architecture tests make implicit Rails conventions visible and enforceable.

Dynamic, object-oriented, and optimized for readable code

Ruby on Rails, Sidekiq, RSpec, and Minitest

Useful for modular monoliths and growing Rails codebases

Adoption snapshot

Public adoption, in context.

RubyGems reports 2,242 downloads across all ArchUnitRuby versions. It does not expose a comparable rolling 30-day package total.

View RubyGems ↗Compare all libraries →

Package status: Published on RubyGems
Reported history: 2,242
Latest 30 days: Unavailable
GitHub stars: 4

Capabilities

What ArchUnitRuby brings to the test suite.

The family shares a recognizable architecture vocabulary while each implementation stays honest about its language, toolchain, and maturity.

File, layer, and slice dependency rules

RSpec and Minitest integrations

Naming, location, and external-module policies

Metrics and dependency graph reports

PlantUML adherence and exports

Structured violations and custom predicates

Go deeper

Detect cycles across a Rails application.

A cycle rule checks the selected application files as one directed graph and reports the complete paths that close a loop. Use a layer or slice rule when the decision is about independence between named business domains.

cycle_spec.rb

require 'archunit'

rule = ArchUnit.project_files.in_folder('app/**')
  .should.have_no_cycles

ArchUnit.assert_passes(rule)

Documentation highlights

Work with ArchUnitRuby beyond the quickstart.

ArchUnitRuby uses Prism for static analysis, so architecture checks do not boot the Rails application or execute gem code. It resolves common Ruby loading forms while staying explicit about dynamic behavior it cannot know safely.

Understand Ruby loading statically

require, require_relative, autoload, and load calls become typed graph edges with normalized project-relative paths.

Standard-library and gem dependencies retain the module name written in source.
Multiple-gem repositories contribute adjacent lib directories from gemspec locations without evaluating the gemspecs.
Interpolated or variable-driven imports are omitted rather than guessed because resolving them would require running application code.

Guard Rails and Ruby boundaries

File, layer, and slice rules cover dependency direction, cycles, naming, placement, diagrams, and modular-monolith boundaries.

RSpec and Minitest helpers format the same underlying violation objects.
PlantUML conformance connects a component diagram to the dependencies present in source.
Inline ignore directives and explicit load paths handle compatibility edges and non-standard repository layouts.

Inspect the graph and metrics

Graph reports and count, cohesion, coupling, and distance measures make architectural pressure visible before a hard boundary breaks.

Graph caching includes normalized load-path choices, so equivalent checks reuse extraction work.
Per-check logging can write to an IO stream or timestamped files without a global logger.
Custom predicates extend the grammar for conventions that are unique to a codebase.

Read the complete documentation ↗

Release and compatibility

0.0.1 preview

A working executable prototype published as version 0.0.1 and tested on current Ruby releases.

View on RubyGems ↗

LanguageRuby

Release0.0.1 preview

RuntimeRuby 3.3+

LicenseMIT

Where it fits

Put boundaries next to the code they protect.

Common starting points for ArchUnitRuby include the following project shapes.

Rails applicationsRuby servicesGemsModular monoliths

More ecosystems

The same intent, expressed natively.

Explore sibling implementations and carry the architecture vocabulary across a polyglot system.

Make the first boundary executable.

Add one meaningful rule, run it with the existing tests, and grow the architecture suite as the system reveals where it needs protection.

Start with ArchUnitRuby ↗