Layered Rails

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 implementation pattern fits.

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

Common Layer Violations

The Specification Test

Diagnostic for misplaced code:

1. List every responsibility the object handles
2. For each, ask: "Does this belong to this layer's primary concern?"
3. 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.

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?"

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
  NO ↓

Does it orchestrate multiple models or services?
  YES → Application layer
    One transaction boundary? → Plain Operation Object
    Needs typed inputs and validations? → ActiveInteraction
  NO ↓

Is it a business rule about a single model?
  YES → Domain layer (keep in model or concern)
    Has state transitions? → State Machine
    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:

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 to Add Layers

Default to simplicity. Add a layer only when it removes demonstrated complexity.

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

References

• Business logic and transaction guidance
• Pattern catalog
• Extraction methodology