AXR

Ruby architecture for simplicity and team adoption

Architecture's hard. It’s very easy to build a complex system. Much harder to build a simple and adaptable solution. The code doesn't matter. Coding for the sake of writing code is foolish.

Only a few of us get to write software that survives 5-10 years or longer. 90% of our work is garbage that becomes obsolete in 1-3 years after release. Most of our work hours are wasted on features that will never be useful.

This is just a reality.

(c) Volodya Sveredyuk

Application engineering it's always about abstractions and how they describe the real world and business which pays our salaries for coding something that might improve it. Maybe. Sometimes.

I hate doing something alone. I am a team player and as a team player, I prefer conventions over configuration. But this is not working with knowledge responsibility segregation inside the software app. In the Ruby world (especially Rails) it's so easy to add a new feature. Just add one line, one dependency, one callback and now you share knowledge about one entity into another entity. More dependencies - more spaghetti and legacy that in future we should REWRITE EVERYTHING!

Architecture's about knowledge responsibility and not the code.

The worst thing that even we write the architecture document wherein a convenient way to agree on architecture and layers and entities, etc - We are not protected from violation of these conventions.

And this the place where AxR comes on the stage.

Please, welcome the DSL that helps:

1. Describes your application layers (modules)
2. Defines knowledge responsibilities between them
3. Checks if you did not violate anything

In your Gemfile

gem 'axr', group: :development

In your ruby app: (for rails app put it into config/initializers/axr.rb file)

require 'axr'

AxR.app.define do
  layer 'Api'
  layer 'YourBusinessLogic'
  layer 'Repo'
end

By default, layers will get level from top to bottom.

Api -> 0
YourBusinessLogic -> 1
Repo -> 2

Layers with lower-level have less isolation.

• Api knows about YourBusinessLogic and Repo
• YourBusinessLogic knows about Repo but don't know anything about Api
• Repo fully isolated and don't familiar with Api and YourBusinessLogic

Options

require 'axr'

AxR.app.define do
  layer 'A'
  layer 'B', familiar_with: 'C'
  layer 'C', familiar_with: 'B'
  layer 'D', isolated: true
  layer 'E', isolated: true
end

# app.define options
AxR.app.define(isolated: true) # All layers will be isolated by default
AxR.app.define(familiar_with: ['D', 'E') # All layers will be familiar with D and E by default

# layer options
familiar_with: [...] # Can operate with other layers
isolated: true # 100% isolated and should not operate with other layers
isolated: true, familiar_with: [...] # Isolated from all except familiars

Can organize knowledge structure like:

Run AxR checker in console

axr check . --load path/to/you/app/autoload.rb

For rails apps

axr check . --load config/environment

Run for a specific directory

axr lib/adapters

Run for a specific file

axr lib/adapters/youtube.rb

Finish scanning with status code 1 in case of any warnings (you can use in CI environment to fail pipeline step)

axr check --exit-on-warnings

ERP system

if Rails.env.development? || Rails.env.test?
  require 'axr'

  AxR.app.define(isolated: true) do
    layer 'UI',         familiar_with: %w[Docs Inventory Production]
    layer 'API',        familiar_with: %w[Docs Inventory Production]
    layer 'Docs',       familiar_with: %w[Inventory Accounts Repo]
    layer 'Accounts',   familiar_with: %w[Repo]
    layer 'Inventory',  familiar_with: %w[Repo]
    layer 'Production', familiar_with: %w[Repo]
    layer 'Repo'
  end
end

• Ignore vendor or any other directories dir as configuration
• Add sublayers
• Add rubocop cop
• Add more app examples
• Migrate to AST analyzer