Layered Rails Architecture Skill

Layered Rails Architecture

Audience: Rails developers working on applications that have outgrown single-file patterns. Goal: Know which layer code belongs in, when to extract, and which existing skill handles the implementation.

Four-Layer Architecture

Presentation  →  Application  →  Domain  →  Infrastructure
(HTTP/UI)        (Orchestration)  (Business)   (Persistence/APIs)

Core rule: Lower layers MUST NOT depend on higher layers. Data flows top-to-bottom only.

Layer Responsibilities

| Layer | Owns | Does NOT Own | |-------|------|-------------| | Presentation | HTTP concerns, params, rendering, channels, mailers | Business logic, direct DB queries | | Application | Orchestration across models, authorization, form validation | Persistence details, rendering | | Domain | Business rules, validations, associations, value objects | HTTP context, request objects, Current.* | | Infrastructure | ActiveRecord, external APIs, file storage, caching | Business rules, presentation |

Common Layer Violations

| Violation | Why It's Wrong | Fix | |-----------|---------------|-----| | Current.user in model | Domain depends on presentation context | Pass user as explicit parameter | | request param in service | Application depends on presentation | Extract needed values before calling service | | Pricing calc in controller | Business logic in presentation | Move to model method or service | | All logic in services, anemic models | Domain layer is hollow | Keep domain logic in models; services orchestrate | | Model sends emails directly | Domain depends on infrastructure side-effects | Use callbacks only for data transforms; extract delivery |

The Specification Test

Diagnostic for misplaced code:

List every responsibility the object handles
For each, ask: "Does this belong to this layer's primary concern?"
If NO → extract to the appropriate layer

Example: A User model that handles authentication, avatar processing, notification preferences, and activity logging.

Authentication → Domain (keep)
Avatar processing → Infrastructure (extract to service/job)
Notification preferences → Domain (keep as concern)
Activity logging → Infrastructure (extract to observer/event)

See references/extraction-signals.md for the full methodology.

Callback Scoring

Rate each callback 1-5. Extract anything scoring 1-2.

| Score | Type | Example | Action | |-------|------|---------|--------| | 5 | Transformer | before_validation :normalize_email | Keep | | 4 | Normalizer | before_save :strip_whitespace | Keep | | 4 | Utility | after_create :update_counter_cache | Keep | | 2 | Observer | after_save :notify_admin | Consider extracting | | 1 | Operation | after_create :send_welcome_email, :provision_account | Extract |

Rule of thumb: If removing the callback would break the model's own data integrity → keep. If it triggers external side-effects → extract.

Pattern Selection

"Where should this code go?"

| Situation | Pattern | Layer | Skill | |-----------|---------|-------|-------| | Complex multi-model form | Form Object | Presentation | — | | Request param filtering | Filter Object | Presentation | — | | View-specific formatting | Presenter / ViewComponent | Presentation | viewcomponent-coder | | Authorization rules | Policy Object | Application | action-policy-coder | | Business operation (one-time) | Service / Interaction | Application | active-interaction-coder | | Multi-model orchestration | Service Object | Application | active-interaction-coder | | State lifecycle management | State Machine | Domain | aasm-coder | | Complex reusable query | Query Object | Domain | — | | Immutable concept (Money, DateRange) | Value Object | Domain | — | | Shared model behavior | Concern | Domain | — | | Typed configuration | Config Object | Infrastructure | anyway-config-coder | | Domain events / audit trail | Event Sourcing | Infrastructure | event-sourcing-coder | | JSON-backed attributes | Store Model | Domain | store-model-coder |

Decision Tree

Is it about HTTP/params/rendering?
  YES → Presentation layer
    Multi-model form? → Form Object
    Filtering params? → Filter Object
    Formatting for view? → Presenter or ViewComponent
  NO ↓

Is it authorization?
  YES → Policy Object (action-policy-coder)
  NO ↓

Does it orchestrate multiple models/services?
  YES → Application layer
    One-time operation? → Service/Interaction (active-interaction-coder)
    Needs typed inputs? → ActiveInteraction (active-interaction-coder)
  NO ↓

Is it a business rule about a single model?
  YES → Domain layer (keep in model or concern)
    Has state transitions? → AASM (aasm-coder)
    Reusable query? → Query Object
    Immutable value? → Value Object
  NO ↓

Is it about persistence/external APIs/caching?
  YES → Infrastructure layer

Services as Waiting Rooms

app/services/ is a temporary staging area, not a permanent home.

Services that survive should eventually reveal the real abstraction they represent
If a service wraps a single model operation → it probably belongs in the model
If a service coordinates 3+ models → it's a legitimate orchestrator
If a service grows complex → look for Form Object, Policy, or Query Object hiding inside

Smell test: If app/services/ has 50+ files and no subdirectories, the waiting room has become permanent storage.

Extraction Signals

When to extract code from existing locations:

| Signal | Threshold | Action | |--------|-----------|--------| | Method length | > 15 lines | Extract method or object | | External API call in model | Any | Extract to service/gateway | | God object | High churn × high complexity | Decompose (see references/extraction-signals.md) | | Spec exceeds layer concern | Specification test fails | Extract to appropriate layer | | Callback score | 1-2/5 | Extract to service or event handler | | Duplicated query logic | 2+ locations | Extract Query Object | | Current.* in model | Any usage | Pass as explicit parameter |

See references/extraction-signals.md for the complete methodology.

Model Organization

Recommended ordering within model files:

class Order < ApplicationRecord
  # 1. Extensions/DSL (has_secure_password, acts_as_*)
  # 2. Associations
  # 3. Enums
  # 4. Normalizations
  # 5. Validations
  # 6. Scopes
  # 7. Callbacks (transformers/normalizers only — score 4-5)
  # 8. Delegations
  # 9. Public methods
  # 10. Private methods
end

When Layered vs DHH Style

This skill complements dhh-coder, not replaces it.

| Situation | Use | |-----------|-----| | Small/medium app, standard CRUD | dhh-coder — keep it simple | | Complex domain, multiple bounded contexts | layered-rails — add structure | | Authorization beyond simple checks | action-policy-coder via layered guidance | | Fat model with 500+ lines | layered-rails extraction signals | | Standard controller actions | dhh-coder — 7 REST actions | | Multi-step business operation | active-interaction-coder via layered guidance |

Default to simplicity. Reach for layered patterns only when complexity demands it.

Success Checklist

[ ] No reverse dependencies (lower layers don't reference higher)
[ ] Models don't access Current attributes
[ ] Services don't accept request/controller objects
[ ] Controllers contain only HTTP concerns
[ ] Domain logic lives in models, not leaked into services
[ ] All callbacks score 4+ (or extracted)
[ ] Concerns group by behavior, not by artifact type
[ ] Each abstraction belongs to exactly one layer

Cross-References

| Need | Skill | |------|-------| | Authorization policies | action-policy-coder | | Typed business operations | active-interaction-coder | | State machines | aasm-coder | | Operations + state routing | business-logic-coder | | ViewComponents | viewcomponent-coder | | Typed configuration | anyway-config-coder | | Event sourcing / audit | event-sourcing-coder | | JSON attributes | store-model-coder | | Refactoring execution | rails-refactorer | | DHH-style simplicity | dhh-coder | | Pattern catalog details | references/pattern-catalog.md | | Extraction methodology | references/extraction-signals.md |

Agent Skills: Layered Rails Architecture

Install this agent skill to your local

Skill Files