Rails Conventions & Patterns Skill

This skill provides authoritative guidance on Ruby on Rails conventions, design patterns, and idiomatic code standards for production applications.

When to Use This Skill

• Writing new Rails controllers, models, or services

• Refactoring existing Rails code

• Making decisions about code organization

• Choosing between different Rails patterns

• Ensuring code follows Rails conventions

• Reviewing Rails code for convention compliance

Ruby & Rails Versions

ruby: "3.2+ (prefer 3.3+ for YJIT benefits)" rails: "7.1+ (prefer 8.0+ for new projects)"

Rails 7.x/8.x Modern Features

Rails 7.1+ Features

Composite Primary Keys

class BookOrder < ApplicationRecord self.primary_key = [:shop_id, :id] belongs_to :shop has_many :line_items, foreign_key: [:shop_id, :order_id] end

ActiveRecord::Encryption (sensitive data)

class User < ApplicationRecord encrypts :email, deterministic: true encrypts :ssn, :credit_card end

Horizontal Sharding

class ApplicationRecord < ActiveRecord::Base connects_to shards: { default: { writing: :primary, reading: :primary_replica }, shard_two: { writing: :primary_shard_two } } end

Async Query Loading

posts = Post.where(published: true).load_async

Do other work

posts.to_a # Wait for results

Normalize values before validation

class User < ApplicationRecord normalizes :email, with: -> { _1.strip.downcase } normalizes :phone, with: -> { _1.gsub(/\D/, '') } end

Rails 8.0+ Features

Improved Solid Queue (built-in job backend)

config/application.rb

config.active_job.queue_adapter = :solid_queue

Solid Cache (built-in caching)

config/application.rb

config.cache_store = :solid_cache_store

Authentication generator

rails generate authentication

Built-in rate limiting

class Api::PostsController < Api::BaseController rate_limit to: 10, within: 1.minute, only: :create end

Per-environment credentials

rails credentials:edit --environment production

Modern Ruby 3.3+ Features

Pattern matching in case expressions

case user in { role: "admin", active: true } grant_full_access in { role: "user", active: true } grant_standard_access else deny_access end

Endless method definitions (one-liners)

def full_name = "#{first_name} #{last_name}" def published? = published_at.present?

Data class (immutable value objects, Ruby 3.2+)

User = Data.define(:id, :name, :email) user = User.new(id: 1, name: "Alice", email: "alice@example.com")

YJIT optimization (Ruby 3.3+)

config/application.rb

if defined?(RubyVM::YJIT.enable) RubyVM::YJIT.enable end

File Organization Standards

Models

location: "app/models/" max_lines: 200 guidance: | Focus on associations, validations, scopes, and essential callbacks. Extract business logic to Service Objects. Keep models focused on data persistence and domain rules.

Controllers

location: "app/controllers/" max_lines: 100 guidance: | Limit to REST actions. Use before_action for shared logic. Complex operations delegate to Service Objects. Follow "Skinny Controller, Fat Model (but not too fat)" pattern.

Comprehensive Controller Patterns

RESTful Controller Structure

class PostsController < ApplicationController before_action :authenticate_user! before_action :set_post, only: [:show, :edit, :update, :destroy] before_action :authorize_post, only: [:edit, :update, :destroy]

GET /posts

def index @posts = Post.published.page(params[:page]) end

GET /posts/:id

def show # @post set by before_action end

GET /posts/new

def new @post = Post.new end

POST /posts

def create @post = CreatePostService.call(current_user, post_params)

if @post.persisted?
  redirect_to @post, notice: "Post created successfully"
else
  render :new, status: :unprocessable_entity
end

end

GET /posts/:id/edit

def edit # @post set by before_action end

PATCH /posts/:id

def update if UpdatePostService.call(@post, post_params) redirect_to @post, notice: "Post updated successfully" else render :edit, status: :unprocessable_entity end end

DELETE /posts/:id

def destroy @post.destroy! redirect_to posts_url, notice: "Post deleted successfully" end

private

def set_post @post = Post.find(params[:id]) end

def authorize_post authorize @post # Pundit end

def post_params params.require(:post).permit(:title, :body, :published) end end

API Controller Patterns

app/controllers/api/base_controller.rb

module Api class BaseController < ActionController::API include ActionController::HttpAuthentication::Token::ControllerMethods

before_action :authenticate_api_user!

rescue_from ActiveRecord::RecordNotFound, with: :not_found
rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
rescue_from Pundit::NotAuthorizedError, with: :forbidden

private

def authenticate_api_user!
  authenticate_or_request_with_http_token do |token, options|
    @current_user = User.find_by(api_token: token)
  end
end

def not_found(exception)
  render json: { error: exception.message }, status: :not_found
end

def unprocessable_entity(exception)
  render json: { errors: exception.record.errors }, status: :unprocessable_entity
end

def forbidden
  render json: { error: "Forbidden" }, status: :forbidden
end

end end

app/controllers/api/v1/posts_controller.rb

module Api module V1 class PostsController < Api::BaseController def index posts = Post.published.page(params[:page]) render json: PostBlueprint.render(posts, root: :posts) end

  def create
    post = CreatePostService.call(current_user, post_params)

    if post.persisted?
      render json: PostBlueprint.render(post), status: :created
    else
      render json: { errors: post.errors }, status: :unprocessable_entity
    end
  end
end

end end

Hotwire Controller Patterns

class PostsController < ApplicationController

Turbo Stream responses

def create @post = CreatePostService.call(current_user, post_params)

respond_to do |format|
  if @post.persisted?
    format.turbo_stream
    format.html { redirect_to @post }
  else
    format.turbo_stream { render :form_errors, status: :unprocessable_entity }
    format.html { render :new, status: :unprocessable_entity }
  end
end

end

def update respond_to do |format| if UpdatePostService.call(@post, post_params) format.turbo_stream format.html { redirect_to @post } else format.turbo_stream { render :form_errors, status: :unprocessable_entity } format.html { render :edit, status: :unprocessable_entity } end end end end

app/views/posts/create.turbo_stream.erb

<%= turbo_stream.prepend "posts", @post %> <%= turbo_stream.update "new_post_form", "" %>

Nested Resource Controllers

class CommentsController < ApplicationController before_action :set_post before_action :set_comment, only: [:show, :edit, :update, :destroy]

GET /posts/:post_id/comments

def index @comments = @post.comments.page(params[:page]) end

POST /posts/:post_id/comments

def create @comment = @post.comments.build(comment_params) @comment.user = current_user

if @comment.save
  redirect_to [@post, @comment]
else
  render :new, status: :unprocessable_entity
end

end

private

def set_post @post = Post.find(params[:post_id]) end

def set_comment @comment = @post.comments.find(params[:id]) end end

Controller Concerns

app/controllers/concerns/paginatable.rb

module Paginatable extend ActiveSupport::Concern

included do before_action :set_pagination_params end

private

def set_pagination_params @page = params[:page] || 1 @per_page = params[:per_page] || 25 end

def paginate(collection) collection.page(@page).per(@per_page) end end

Usage

class PostsController < ApplicationController include Paginatable

def index @posts = paginate(Post.published) end end

Services

location: "app/services/" naming: "{Domain}Manager::{Action} (e.g., OrdersManager::CreateOrder)" structure: | class OrdersManager::CreateOrder def initialize(user:, params:) @user = user @params = params end

def call
  # Single public entry point
  # Returns Result object or raises
end

private

# Small, focused private methods

end

Methods

max_lines: 15 max_params: 4 guidance: "If method needs more params, use a Parameter Object or Hash"

Naming Conventions

classes: "PascalCase" methods: "snake_case" predicates: "end with ? (e.g., active?, valid?)" dangerous_methods: "end with ! (e.g., save!, destroy!)" constants: "SCREAMING_SNAKE_CASE" private_methods: "Prefix with purpose, not underscore"

Ruby Idioms

Prefer

• Guard clauses over nested conditionals

• Explicit returns for clarity

• &. (safe navigation) over try

• Keyword arguments for 2+ parameters

• Struct /Data for simple value objects

• frozen_string_literal: true pragma

Avoid

• unless with else

• Nested ternaries

• and /or for control flow

• Monkey patching in application code

Pattern Decision Tree

Always inspect existing codebase patterns before recommending any pattern.

Service Object

Use when:

- Business logic spans multiple models

- Operation has multiple steps

- Logic doesn't belong to any single model

- Need to orchestrate external services

Avoid when:

- Simple CRUD operation

- Logic clearly belongs to one model

- Single-line delegation

Inspect first:

ls app/services/

Check existing service naming convention

Form Object

Use when:

- Form spans multiple models

- Complex validations not tied to persistence

- Wizard/multi-step forms

Avoid when:

- Standard single-model form

- Simple attribute updates

Inspect first:

ls app/forms/ 2>/dev/null

grep -r 'include ActiveModel' app/ --include='*.rb'

Query Object

Use when:

- Complex queries with multiple conditions

- Query logic reused across controllers

- Query needs composition/chaining

Avoid when:

- Simple scope suffices

- One-off query

Inspect first:

ls app/queries/ 2>/dev/null

grep -r 'class.Query' app/ --include='.rb'

Concern

Use when:

- Truly shared behavior across 3+ unrelated models

- Behavior is cohesive and self-contained

Avoid when:

- Only 1-2 models share the code

- Behavior is not cohesive

- Just to 'clean up' a model

Inspect first:

ls app/models/concerns/ app/controllers/concerns/

Check how many models use each concern

Decorator/Presenter

Use when:

- View logic becoming complex

- Same presentation logic in multiple views

- Need to augment model for display

Avoid when:

- Simple attribute display

- One-off formatting

Inspect first:

ls app/decorators/ app/presenters/ 2>/dev/null

grep 'draper' Gemfile

ActionMailer Conventions

Mailer Structure

app/mailers/user_mailer.rb

class UserMailer < ApplicationMailer default from: 'notifications@example.com'

def welcome_email(user) @user = user @url = root_url

mail(
  to: email_address_with_name(@user.email, @user.name),
  subject: 'Welcome to My App'
)

end

def password_reset(user, token) @user = user @token = token @reset_url = edit_password_reset_url(token: @token)

mail(to: @user.email, subject: 'Password Reset Instructions')

end

private

def email_address_with_name(email, name) Mail::Address.new(email).tap { |a| a.display_name = name }.format end end

app/views/user_mailer/welcome_email.html.erb

<h1>Welcome <%= @user.name %>!</h1> <p>Click here to get started: <%= link_to 'Get Started', @url %></p>

app/views/user_mailer/welcome_email.text.erb

Welcome <%= @user.name %>!

Click here to get started: <%= @url %>

Mailer Testing

spec/mailers/user_mailer_spec.rb

RSpec.describe UserMailer, type: :mailer do describe '#welcome_email' do let(:user) { create(:user, email: 'user@example.com') } let(:mail) { UserMailer.welcome_email(user) }

it 'renders the subject' do
  expect(mail.subject).to eq('Welcome to My App')
end

it 'renders the receiver email' do
  expect(mail.to).to eq([user.email])
end

it 'renders the sender email' do
  expect(mail.from).to eq(['notifications@example.com'])
end

it 'contains user name' do
  expect(mail.body.encoded).to match(user.name)
end

end end

Mailer Previews (Rails 4.1+)

test/mailers/previews/user_mailer_preview.rb

class UserMailerPreview < ActionMailer::Preview def welcome_email UserMailer.welcome_email(User.first) end

def password_reset user = User.first token = SecureRandom.urlsafe_base64 UserMailer.password_reset(user, token) end end

Visit: http://localhost:3000/rails/mailers/user_mailer/welcome_email

Background Delivery

Deliver later (asynchronous)

UserMailer.welcome_email(@user).deliver_later

Deliver later with delay

UserMailer.welcome_email(@user).deliver_later(wait: 1.hour)

Deliver later at specific time

UserMailer.welcome_email(@user).deliver_later(wait_until: Date.tomorrow.noon)

Deliver now (synchronous)

UserMailer.welcome_email(@user).deliver_now

Background Job Conventions

ActiveJob Structure

app/jobs/application_job.rb

class ApplicationJob < ActiveJob::Base

Global retry configuration

retry_on StandardError, wait: :exponentially_longer, attempts: 5 retry_on ActiveRecord::Deadlocked, wait: 5.seconds, attempts: 3

Discard specific errors

discard_on ActiveJob::DeserializationError

Global error handling

rescue_from(Exception) do |exception| ErrorTracker.notify(exception) raise exception end end

app/jobs/send_welcome_email_job.rb

class SendWelcomeEmailJob < ApplicationJob queue_as :mailers

def perform(user) UserMailer.welcome_email(user).deliver_now end end

Usage

SendWelcomeEmailJob.perform_later(user)

Sidekiq-Specific Patterns

app/jobs/process_order_job.rb

class ProcessOrderJob < ApplicationJob queue_as :orders

Sidekiq-specific options

sidekiq_options retry: 3, backtrace: true, dead: true

def perform(order_id) order = Order.find(order_id) OrderProcessor.new(order).process! end end

config/sidekiq.yml

:queues:

• critical
• default
• mailers
• low_priority

:schedule: daily_cleanup: cron: '0 0 * * *' # Daily at midnight class: DailyCleanupJob

Job Testing

spec/jobs/send_welcome_email_job_spec.rb

RSpec.describe SendWelcomeEmailJob, type: :job do include ActiveJob::TestHelper

let(:user) { create(:user) }

it 'enqueues the job' do expect { SendWelcomeEmailJob.perform_later(user) }.to have_enqueued_job(SendWelcomeEmailJob).with(user) end

it 'sends welcome email' do expect { perform_enqueued_jobs do SendWelcomeEmailJob.perform_later(user) end }.to change { ActionMailer::Base.deliveries.count }.by(1) end

it 'retries on failure' do allow(UserMailer).to receive(:welcome_email).and_raise(StandardError)

expect {
  SendWelcomeEmailJob.perform_later(user)
}.to have_enqueued_job(SendWelcomeEmailJob).on_queue(:mailers)

end end

Action Cable (WebSocket) Conventions

Channel Structure

app/channels/application_cable/connection.rb

module ApplicationCable class Connection < ActionCable::Connection::Base identified_by :current_user

def connect
  self.current_user = find_verified_user
end

private

def find_verified_user
  if verified_user = User.find_by(id: cookies.encrypted[:user_id])
    verified_user
  else
    reject_unauthorized_connection
  end
end

end end

app/channels/chat_channel.rb

class ChatChannel < ApplicationCable::Channel def subscribed # Stream from specific room stream_from "chat_#{params[:room_id]}"

# Or stream for current user
stream_for current_user

end

def unsubscribed # Cleanup when channel is unsubscribed stop_all_streams end

def speak(data) # Receive data from client message = current_user.messages.create!( content: data['message'], room_id: params[:room_id] )

# Broadcast to all subscribers
ActionCable.server.broadcast(
  "chat_#{params[:room_id]}",
  message: render_message(message)
)

end

private

def render_message(message) ApplicationController.render( partial: 'messages/message', locals: { message: message } ) end end

Client-Side JavaScript

// app/javascript/channels/chat_channel.js import consumer from "./consumer"

consumer.subscriptions.create( { channel: "ChatChannel", room_id: roomId }, { connected() { console.log("Connected to chat") },

disconnected() {
  console.log("Disconnected from chat")
},

received(data) {
  const messages = document.getElementById('messages')
  messages.insertAdjacentHTML('beforeend', data.message)
},

speak(message) {
  this.perform('speak', { message: message })
}

} )

Broadcasting from Models

app/models/message.rb

class Message < ApplicationRecord belongs_to :user belongs_to :room

after_create_commit :broadcast_message

private

def broadcast_message broadcast_append_to( [room, :messages], target: "messages", partial: "messages/message", locals: { message: self } ) end end

Cable Testing

spec/channels/chat_channel_spec.rb

RSpec.describe ChatChannel, type: :channel do let(:user) { create(:user) } let(:room) { create(:room) }

before do stub_connection(current_user: user) end

it 'successfully subscribes' do subscribe(room_id: room.id) expect(subscription).to be_confirmed expect(subscription).to have_stream_from("chat_#{room.id}") end

it 'broadcasts messages' do subscribe(room_id: room.id)

expect {
  perform :speak, message: 'Hello'
}.to have_broadcasted_to("chat_#{room.id}")

end end

Enhanced Concern Best Practices

When to Use Concerns

GOOD: Truly shared behavior across unrelated models

app/models/concerns/publishable.rb

module Publishable extend ActiveSupport::Concern

included do scope :published, -> { where(published: true) } scope :draft, -> { where(published: false) }

validates :published_at, presence: true, if: :published?

end

def publish! update!(published: true, published_at: Time.current) end

def unpublish! update!(published: false, published_at: nil) end end

Used in multiple unrelated models

class Post < ApplicationRecord include Publishable end

class Video < ApplicationRecord include Publishable end

class Podcast < ApplicationRecord include Publishable end

Concern with Dependencies

app/models/concerns/taggable.rb

module Taggable extend ActiveSupport::Concern

included do # Dependencies injection has_many :taggings, as: :taggable, dependent: :destroy has_many :tags, through: :taggings

scope :tagged_with, ->(tag_name) {
  joins(:tags).where(tags: { name: tag_name })
}

end

Instance methods

def tag_names=(names) self.tags = names.map { |n| Tag.find_or_create_by(name: n.strip) } end

def tag_names tags.pluck(:name) end

Class methods

class_methods do def most_tagged(limit = 10) select('taggable_id, COUNT(*) as tags_count') .group('taggable_id') .order('tags_count DESC') .limit(limit) end end end

Controller Concerns

app/controllers/concerns/error_handling.rb

module ErrorHandling extend ActiveSupport::Concern

included do rescue_from ActiveRecord::RecordNotFound, with: :not_found rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity rescue_from Pundit::NotAuthorizedError, with: :unauthorized end

private

def not_found respond_to do |format| format.html { render 'errors/404', status: :not_found } format.json { render json: { error: 'Not found' }, status: :not_found } end end

def unprocessable_entity(exception) respond_to do |format| format.html { render 'errors/422', status: :unprocessable_entity } format.json { render json: { errors: exception.record.errors }, status: :unprocessable_entity } end end

def unauthorized respond_to do |format| format.html { redirect_to root_path, alert: 'Not authorized' } format.json { render json: { error: 'Not authorized' }, status: :forbidden } end end end

Usage

class ApplicationController < ActionController::Base include ErrorHandling end

Method Visibility Rules

Public

Callable from anywhere, defines the API

Controller actions must be public

Methods called from views must be public

Service interface methods

Rails context:

- Controller: only public methods are routable

- Model: public methods accessible from controllers/views

- Component: only public methods callable from templates

Private

Can only be called within the class, without explicit receiver

Implementation details

Helper methods not part of public API

Methods that should never be called externally

Rails context:

- Controller: helper methods, before_action callbacks

- Service: internal computation methods

- Model: internal validation helpers

CRITICAL: Private methods CANNOT be called from outside the class.

If a view needs data, the component MUST have a public method.

Protected

Callable from same class or subclasses

Methods meant for inheritance

Rare in typical Rails apps

Rails context:

- Occasionally in base controllers/models for shared behavior

Delegation Patterns

Using delegate

Creates public forwarding methods

LIMITATION: Cannot delegate to private methods on target

delegate :method1, :method2, to: :target

class Component < ViewComponent::Base delegate :total, :count, to: :@service

def initialize(service:) @service = service end end

Now view can call component.total

Wrapper Methods

Use when:

- Need to transform data

- Need to add caching

- Need different method names

- Need to handle errors

class Component < ViewComponent::Base def total @service.calculate_total rescue ServiceError 0 end end

attr_reader Exposure

Expose the underlying object directly

Use sparingly - breaks encapsulation

class Component < ViewComponent::Base attr_reader :service

def initialize(service:) @service = service end end

View calls: component.service.calculate_total

Rails Request Cycle

Request → Route → Controller#action → Controller → Service/Model (business logic) → Controller → sets @instance_variables → Controller → renders View → View → calls methods on @variables → View → renders Components → Component → accesses only its own methods

Key Insight: Each layer can only access what the previous layer explicitly provides. Views can't magically access service internals.

Implementation Order

Always implement in dependency order (bottom-up):

1. Database migrations (if needed)
2. Models (foundation)
3. Services (business logic)
4. Components (presentation wrappers)
5. Controllers (orchestration)
6. Views (final layer)
7. Tests (verify everything works)

Rationale: Each layer depends on the ones below it. Implementing bottom-up ensures dependencies exist before they're used.

Code Quality Standards

Method Size

• Maximum 15 lines per method

• Single responsibility per method

• Extract complex logic to private helper methods

Class Size

• Models: max 200 lines

• Controllers: max 100 lines

• Services: max 150 lines

Parameter Count

• Maximum 4 parameters

• Use keyword arguments for 2+ parameters

• Use Parameter Objects for complex cases

Form Objects (Expanded)

Basic Form Object

app/forms/user_registration_form.rb

class UserRegistrationForm include ActiveModel::Model include ActiveModel::Attributes

attribute :email, :string attribute :password, :string attribute :password_confirmation, :string attribute :first_name, :string attribute :last_name, :string attribute :accept_terms, :boolean

validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP } validates :password, presence: true, length: { minimum: 8 } validates :password_confirmation, presence: true validates :first_name, :last_name, presence: true validates :accept_terms, acceptance: true validate :passwords_match

def save return false unless valid?

ActiveRecord::Base.transaction do
  @user = User.create!(
    email: email,
    password: password,
    first_name: first_name,
    last_name: last_name
  )

  @profile = @user.create_profile!(
    full_name: "#{first_name} #{last_name}"
  )

  SendWelcomeEmailJob.perform_later(@user)
end

true

rescue ActiveRecord::RecordInvalid => e errors.add(:base, e.message) false end

attr_reader :user, :profile

private

def passwords_match return if password == password_confirmation

errors.add(:password_confirmation, "doesn't match password")

end end

Controller usage

def create @form = UserRegistrationForm.new(registration_params)

if @form.save redirect_to @form.user, notice: 'Registration successful' else render :new, status: :unprocessable_entity end end

Multi-Step Wizard Form

app/forms/checkout_wizard.rb

class CheckoutWizard include ActiveModel::Model

STEPS = [:shipping, :payment, :confirmation].freeze

attr_accessor :current_step attr_reader :order

delegate :shipping_address, :billing_address, :payment_method, :shipping_address=, :billing_address=, :payment_method=, to: :order

validates :shipping_address, presence: true, if: :shipping_step? validates :payment_method, presence: true, if: :payment_step?

def initialize(order, current_step: :shipping) @order = order @current_step = current_step.to_sym end

def next_step return if last_step?

self.current_step = STEPS[STEPS.index(current_step) + 1]

end

def previous_step return if first_step?

self.current_step = STEPS[STEPS.index(current_step) - 1]

end

def save return false unless valid?

order.save

end

def first_step? current_step == STEPS.first end

def last_step? current_step == STEPS.last end

private

def shipping_step? current_step == :shipping end

def payment_step? current_step == :payment end end

Decorators (Expanded)

Draper Decorator Pattern

Gemfile

gem 'draper'

app/decorators/application_decorator.rb

class ApplicationDecorator < Draper::Decorator delegate_all

def created_at h.content_tag(:time, object.created_at.strftime("%B %d, %Y"), datetime: object.created_at.iso8601) end end

app/decorators/user_decorator.rb

class UserDecorator < ApplicationDecorator def full_name "#{object.first_name} #{object.last_name}" end

def profile_link h.link_to full_name, h.user_path(object), class: 'user-link' end

def avatar if object.avatar.attached? h.image_tag object.avatar.variant(resize_to_limit: [100, 100]) else h.image_tag 'default-avatar.png', alt: full_name end end

def status_badge css_class = object.active? ? 'badge-success' : 'badge-secondary' status_text = object.active? ? 'Active' : 'Inactive'

h.content_tag(:span, status_text, class: "badge #{css_class}")

end

def member_since "Member since #{object.created_at.strftime('%B %Y')}" end end

Controller usage

def show @user = User.find(params[:id]).decorate end

View usage

<%= @user.profile_link %> <%= @user.avatar %> <%= @user.status_badge %>

SimpleDelegator Pattern (Without Gems)

app/decorators/user_decorator.rb

class UserDecorator < SimpleDelegator def initialize(user, view_context) super(user) @view_context = view_context end

def full_name "#{first_name} #{last_name}" end

def profile_link h.link_to full_name, h.user_path(self) end

def formatted_created_at created_at.strftime("%B %d, %Y") end

private

def h @view_context end end

Controller

def show user = User.find(params[:id]) @user = UserDecorator.new(user, view_context) end

Presenters (Expanded)

View-Specific Presenter

app/presenters/dashboard_presenter.rb

class DashboardPresenter def initialize(user, view_context) @user = user @view_context = view_context end

def welcome_message time_of_day = Time.current.hour < 12 ? 'Morning' : 'Afternoon' "Good #{time_of_day}, #{@user.first_name}!" end

def recent_orders @recent_orders ||= @user.orders.recent.limit(5).map do |order| OrderPresenter.new(order, @view_context) end end

def total_spent h.number_to_currency(@user.orders.sum(:total)) end

def activity_feed @user.activities.recent.limit(10).map do |activity| { icon: activity_icon(activity), text: activity_text(activity), time: h.time_ago_in_words(activity.created_at) } end end

def stats { total_orders: @user.orders.count, total_spent: total_spent, favorite_category: @user.favorite_category&.name || 'N/A', member_since: @user.created_at.year } end

private

def h @view_context end

def activity_icon(activity) case activity.action when 'order_placed' then 'shopping-cart' when 'review_posted' then 'star' when 'profile_updated' then 'user' else 'activity' end end

def activity_text(activity) case activity.action when 'order_placed' "You placed order ##{activity.target_id}" when 'review_posted' "You reviewed #{activity.target.product.name}" when 'profile_updated' "You updated your profile" end end end

Controller

def dashboard @presenter = DashboardPresenter.new(current_user, view_context) end

View

<h1><%= @presenter.welcome_message %></h1>

<div class="stats"> <% @presenter.stats.each do |key, value| %> <div class="stat"> <span class="label"><%= key.to_s.humanize %></span> <span class="value"><%= value %></span> </div> <% end %> </div>

Collection Presenter

app/presenters/users_index_presenter.rb

class UsersIndexPresenter def initialize(users, view_context, filters: {}) @users = users @view_context = view_context @filters = filters end

def users @decorated_users ||= @users.map { |u| UserDecorator.new(u, h) } end

def total_count @users.total_count end

def pagination h.paginate(@users) end

def active_filters @filters.select { |_, v| v.present? } end

def filter_summary return "All users" if active_filters.empty?

parts = []
parts << "Role: #{@filters[:role]}" if @filters[:role]
parts << "Status: #{@filters[:status]}" if @filters[:status]
parts.join(', ')

end

def export_link h.link_to 'Export CSV', h.users_path(format: :csv, **@filters), class: 'btn btn-secondary' end

private

def h @view_context end end

Repository Pattern

Basic Repository

app/repositories/user_repository.rb

class UserRepository class << self def find(id) User.find(id) end

def find_by_email(email)
  User.find_by(email: email)
end

def active_users
  User.where(active: true).order(created_at: :desc)
end

def search(query)
  User.where('name ILIKE ? OR email ILIKE ?', "%#{query}%", "%#{query}%")
end

def with_recent_orders(days: 30)
  User.joins(:orders)
      .where('orders.created_at > ?', days.days.ago)
      .distinct
end

def create(attributes)
  User.create(attributes)
end

def update(user, attributes)
  user.update(attributes)
end

def destroy(user)
  user.destroy
end

end end

Service using repository

class UserRegistrationService def initialize(repository: UserRepository) @repository = repository end

def call(attributes) user = @repository.create(attributes)

if user.persisted?
  SendWelcomeEmailJob.perform_later(user)
  Result.success(user)
else
  Result.failure(user.errors)
end

end end

Repository with Complex Queries

app/repositories/order_repository.rb

class OrderRepository class << self def pending_orders Order.where(status: 'pending').order(created_at: :asc) end

def overdue_orders(threshold: 3.days)
  Order.where(status: 'pending')
       .where('created_at < ?', threshold.ago)
end

def user_orders(user, status: nil)
  scope = user.orders

  scope = scope.where(status: status) if status.present?
  scope.order(created_at: :desc)
end

def revenue_by_month(year: Time.current.year)
  Order.where(status: 'completed')
       .where('EXTRACT(YEAR FROM created_at) = ?', year)
       .group("DATE_TRUNC('month', created_at)")
       .sum(:total)
end

def top_customers(limit: 10)
  User.joins(:orders)
      .where(orders: { status: 'completed' })
      .group('users.id')
      .select('users.*, SUM(orders.total) as total_spent')
      .order('total_spent DESC')
      .limit(limit)
end

end end

PORO (Plain Old Ruby Object) Conventions

Value Objects

app/models/money.rb

class Money include Comparable

attr_reader :amount, :currency

def initialize(amount, currency: 'USD') @amount = BigDecimal(amount.to_s) @currency = currency end

def +(other) validate_currency!(other) Money.new(amount + other.amount, currency: currency) end

def -(other) validate_currency!(other) Money.new(amount - other.amount, currency: currency) end

def *(multiplier) Money.new(amount * multiplier, currency: currency) end

def <=>(other) validate_currency!(other) amount <=> other.amount end

def to_s format('%s%.2f', currency_symbol, amount) end

def ==(other) amount == other.amount && currency == other.currency end

private

def validate_currency!(other) return if currency == other.currency

raise ArgumentError, "Cannot operate on different currencies"

end

def currency_symbol case currency when 'USD' then '$' when 'EUR' then '€' when 'GBP' then '£' else currency end end end

Usage

price = Money.new(19.99) tax = price * 0.08 total = price + tax # => $21.59

Data Transfer Objects (DTOs)

app/models/user_dto.rb

class UserDTO attr_reader :id, :email, :full_name, :role

def initialize(id:, email:, full_name:, role:) @id = id @email = email @full_name = full_name @role = role end

def self.from_model(user) new( id: user.id, email: user.email, full_name: "#{user.first_name} #{user.last_name}", role: user.role ) end

def to_h { id: id, email: email, full_name: full_name, role: role } end end

Or using Ruby 3.2+ Data class

UserDTO = Data.define(:id, :email, :full_name, :role) do def self.from_model(user) new( id: user.id, email: user.email, full_name: "#{user.first_name} #{user.last_name}", role: user.role ) end end

Result Objects

app/models/result.rb

class Result attr_reader :value, :error

def initialize(success:, value: nil, error: nil) @success = success @value = value @error = error end

def self.success(value = nil) new(success: true, value: value) end

def self.failure(error) new(success: false, error: error) end

def success? @success end

def failure? !@success end

def on_success yield value if success? self end

def on_failure yield error if failure? self end end

Service using Result object

class CreateUserService def call(params) user = User.new(params)

if user.save
  Result.success(user)
else
  Result.failure(user.errors)
end

end end

Usage

result = CreateUserService.new.call(user_params)

result .on_success { |user| redirect_to user } .on_failure { |errors| render :new }

Policy Objects

app/policies/post_visibility_policy.rb

class PostVisibilityPolicy def initialize(user, post) @user = user @post = post end

def visible? return true if @post.published? return true if @user&.admin? return true if @post.user_id == @user&.id

false

end

def editable? return true if @user&.admin? return true if @post.user_id == @user&.id

false

end end

Usage in controller

def show @post = Post.find(params[:id]) policy = PostVisibilityPolicy.new(current_user, @post)

unless policy.visible? redirect_to root_path, alert: 'Not authorized' end end

Quick Reference

Before Writing Any Code

Check existing patterns

ls app/services/ ls app/models/ grep -r 'class.Service' app/ --include='.rb' -l | head -10

Check naming conventions

head -30 $(find app/services -name '*.rb' | head -1)

Check dependencies

cat Gemfile | grep -v '^#' | grep -v '^$'

Common File Locations

app/models/ - ActiveRecord models app/controllers/ - Controllers app/services/ - Service objects app/components/ - ViewComponents app/queries/ - Query objects app/forms/ - Form objects app/presenters/ - Presenters app/decorators/ - Decorators app/serializers/ - API serializers app/jobs/ - Background jobs app/mailers/ - Action Mailers app/channels/ - Action Cable channels app/repositories/ - Repository pattern objects app/policies/ - Policy objects (business rules)