Modern Rails 8 Architecture Patterns

Architecture Decision Tree

Where should this code go?
|
+- View/display formatting?       -> Presenter (@presenter-agent)
+- Complex business logic?        -> Service Object (@service-agent)
+- Complex database query?        -> Query Object (@query-agent)
+- Shared behavior across models? -> Concern (/rails-concern skill)
+- Authorization logic?           -> Policy (@policy-agent)
+- Reusable UI with logic?        -> ViewComponent (@viewcomponent-agent)
+- Async/background work?         -> Job (@job-agent, /solid-queue-setup skill)
+- Complex form (multi-model)?    -> Form Object (@form-agent)
+- Transactional email?           -> Mailer (@mailer-agent)
+- Real-time/WebSocket?           -> Channel (/action-cable-patterns skill)
+- Data validation only?          -> Model (@model-agent)
+- HTTP request/response only?    -> Controller (@controller-agent)

Layer Responsibilities

When NOT to Abstract

When TO Abstract

See /extraction-timing skill for detailed extraction guidance.

Core Patterns

Skinny Controllers

# GOOD: Thin controller delegates to service
class OrdersController < ApplicationController
  def create
    result = Orders::CreateService.call(user: current_user, params: order_params)
    if result.success?
      redirect_to result.data, notice: t(".success")
    else
      flash.now[:alert] = result.error
      render :new, status: :unprocessable_entity
    end
  end
end

Result Objects for Services

All services return a consistent Result object:

Result = Data.define(:success, :data, :error) do
  def success? = success
  def failure? = !success
end

Multi-Tenancy by Default

# GOOD: Scoped through account
def index
  @events = current_account.events.recent
end

Rails 8 Specific Features

Testing Strategy by Layer

New Feature Checklist

1. Model - Define data structure (@migration-agent, @model-agent)
2. Policy - Add authorization rules (@policy-agent)
3. Service - Create for complex logic (@service-agent)
4. Query - Add for complex queries (@query-agent)
5. Controller - Keep it thin (@controller-agent)
6. Presenter - Format for display (@presenter-agent)
7. Component - Build reusable UI (@viewcomponent-agent)
8. Mailer - Add transactional emails (@mailer-agent)
9. Job - Add background processing (@job-agent)

References

• See [layer-interactions.md](references/layer-interactions.md) for layer communication patterns
• See [service-patterns.md](references/service-patterns.md) for service object patterns
• See [query-patterns.md](references/query-patterns.md) for query object patterns
• See [error-handling.md](references/error-handling.md) for error handling strategies
• See [testing-strategy.md](references/testing-strategy.md) for comprehensive testing