Getting Started

After reading this guide, you will know:

• How to install ArchSpec.
• How to create an architecture file.
• How to run checks in a Rails app.
• How to read the first failure.

Installation

ArchSpec requires Ruby 3.2 or newer.

Add ArchSpec to your Gemfile:

group :development, :test do
  gem "archspec"
end

Then install it:

bundle install

Create the Spec

Run:

bundle exec archspec init

This creates Archspec.rb:

architecture :rails

Add a fuller architecture when the app has a clear shape:

architecture :layered

Override the default directories when the app uses different names:

architecture :layered, layers: {
  interface: "app/controllers/**/*.rb",
  application: "app/services/**/*.rb",
  domain: "app/models/**/*.rb"
}

Run It

bundle exec archspec check

ArchSpec exits with 0 when the rules pass and non-zero when they fail.

Read a Failure

A failure shows the message and rule, the offending code, and the evidence ArchSpec found:

[error] models must not depend on controllers [dependencies.forbid]

app/models/user.rb:2:3

    1 │ class User < ApplicationRecord
  → 2 │   UsersController
      │   ^~~~~~~~~~~~~~~
    3 │ end

  note: User references UsersController

Run explain on the file to see how ArchSpec assigned it:

bundle exec archspec explain app/models/user.rb

app/models/user.rb

  defined constants: User
  components:
    models: matched file pattern app/models/**/*.rb
  outgoing facts:
    1:14 │ inherits from ApplicationRecord
     2:3 │ references UsersController

Commit the Spec

Treat Archspec.rb like a test file. A rule should describe a boundary the team is willing to enforce.