37signals/DHH Rails Style Guide

37signals/​DHH Rails Style Guide

Core Philosophy

• "Vanilla Rails is plenty." Maximize what Rails gives you, minimize dependencies, resist abstractions until necessary.
• Rich domain models over service objects
• CRUD controllers over custom actions
• Concerns for horizontal code sharing
• Records as state over boolean columns
• Database-backed everything (no Redis)
• Build it yourself before reaching for gems

---

Dependencies

Use

• Rails (edge), turbo-rails, stimulus-rails, importmap-rails, propshaft, solid_queue, solid_cache, solid_cable (database-backed, NO Redis), geared_pagination, bcrypt, rqrcode, redcarpet

Avoid

---

Routing: Everything is CRUD

Every action maps to a CRUD verb. Create new resources instead of custom actions:

# Avoid: Custom actions
resources :cards do
  post :close
end

# Good: State changes as resources
resources :cards do
  resource :closure      # POST to close, DELETE to reopen
  resource :pin          # POST to pin, DELETE to unpin
  resource :watch        # POST to watch, DELETE to unwatch
end

Use scope module: for namespaced nested resources. Use resolve for custom polymorphic URL generation.

---

Controllers

Thin Controllers, Rich Models

Controllers orchestrate; business logic lives in models.

def create
  @card.close  # All logic in model
  respond_to do |format|
    format.turbo_stream { render_card_replacement }
    format.json { head :no_content }
  end
end

Controller Concerns

Use concerns for shared behavior:

• Resource scoping: CardScoped, BoardScoped - load parent resources via before_action
• Request context: CurrentRequest - populate Current with request data
• Security: BlockSearchEngineIndexing, RequestForgeryProtection
• Turbo helpers: TurboFlash - flash messages via Turbo Stream

Authorization

Check permissions in controller, define permission logic in model:

# Controller
before_action :ensure_permission_to_administer_card, only: [:destroy]

# Model
def can_administer_card?(card)
  admin? || card.creator == self
end

---

Models & Concerns

Heavy Use of Concerns

Each concern is self-contained with associations, scopes, and methods:

class Card < ApplicationRecord
  include Assignable, Closeable, Eventable, Pinnable, Watchable
end

Concern Structure

module Card::Closeable
  extend ActiveSupport::Concern

  included do
    has_one :closure, dependent: :destroy
    scope :closed, -> { joins(:closure) }
    scope :open, -> { where.missing(:closure) }
  end

  def closed? = closure.present?

  def close(user: Current.user)
    create_closure!(user: user) unless closed?
  end
end

Default Values via Lambdas

belongs_to :account, default: -> { board.account }
belongs_to :creator, class_name: "User", default: -> { Current.user }

Current for Request Context

Use ActiveSupport::CurrentAttributes for session, user, identity, account, and request metadata.

POROs (Plain Old Ruby Objects)

Namespace under parent model: Event::Description, Card::Eventable::SystemCommenter

Use for:

• Presentation logic - formatting for display
• Complex operations - multi-step processes
• View context bundling - collecting UI state

POROs are model-adjacent, NOT controller-adjacent (that would be a service object).

---

State as Records, Not Booleans

Create separate records instead of boolean columns:

# Separate record gives you: timestamp, who did it, easy scoping
class Closure < ApplicationRecord
  belongs_to :card, touch: true
  belongs_to :user, optional: true
end

card.closure.present?     # Is it closed?
card.closure.user         # Who closed it?
card.closure.created_at   # When?

# Scoping
Card.closed  # joins(:closure)
Card.open    # where.missing(:closure)

Examples: Closure, Pin, Watch, Publication, Goldness

---

Authentication

Custom passwordless magic link auth (~150 lines). No Devise.

Key components:

• Authentication concern with require_authentication, resume_session, start_new_session_for
• Session model (belongs_to identity)
• MagicLink model with expiration and consumption
• Bearer token authentication for API access

---

Views & Turbo/​Hotwire

• Turbo Streams for partial updates (turbo_stream.replace, turbo_stream.before)
• Morphing for complex updates (method: :morph)
• Partials over ViewComponents - standard ERB partials with caching
• Stimulus controllers - single-purpose, small (~50 lines), static values/static classes for config, this.dispatch() for events, this.#privateMethod() for private methods

---

Background Jobs

• Shallow jobs, rich models - jobs just call model methods
• _later and _now convention - mark_as_read_later queues job, mark_as_read_now executes immediately
• Solid Queue - database-backed, no Redis
• Recurring jobs via config/​recurring.yml

---

Testing

• Request specs for controllers (not controller specs)
• Ship tests with features in the same commit
• Use change { }, as: :turbo_stream, as: :json

---

What They Avoid

• No service objects - use model methods
• No form objects (usually) - exception: Signup as ActiveModel
• No decorators/​presenters - use view helpers
• No GraphQL - REST with Turbo

---

Naming Conventions

Methods

• Verbs for actions: close, reopen, publish
• Predicates for state: closed?, published?

Concerns

Adjectives describing capability: Closeable, Publishable, Watchable, Searchable

Controllers

Nouns matching the resource: Cards::ClosuresController, Boards::PublicationsController

Scopes

• Ordering: chronologically, reverse_chronologically, alphabetically, latest
• Preloading: preloaded as standard name for eager loading
• Parameterized: indexed_by(index), sorted_by(sort)

---

Caching

HTTP Caching

• fresh_when etag: [...] for conditional GET
• Global etag { "v1" } in ApplicationController (bump to bust caches)
• Concern-level ETags for timezone, authentication

Fragment Caching

• cache card do in views
• cached: true for collection rendering
• touch: true on associations for cache invalidation

---

Database Patterns

• UUIDs for primary keys
• Every model has account_id for multi-tenancy
• URL-based multi-tenancy: /​{account_id}/​boards/​...
• No foreign key constraints - removed for flexibility

---

CSS Architecture

• Vanilla CSS no Sass, PostCSS, or Tailwind.
• CSS Cascade Layers @layer reset, base, components, modules, utilities
• OKLCH color system with CSS variables
• Modern features @starting-style, color-mix(), :has(), native nesting, container queries

---

API Design

• Same controllers, different format via respond_to
• Response codes: Create → 201 Created + Location, Update/​Delete → 204 No Content
• Bearer token authentication

---

Callbacks

Use sparingly:

• after_commit :relay_later, on: :create for async work
• before_save :set_defaults for derived data
• Avoid complex chains, avoid synchronous external calls

---

Summary

1. Start with vanilla Rails - Don't add abstractions until you feel the pain
2. Models are rich - Business logic lives in models, not services
3. Controllers are thin - Just orchestration and response formatting
4. Everything is CRUD - New resource over new action
5. State is records - Not boolean columns
6. Concerns are compositions - Horizontal behavior sharing
7. Build before buying - Auth, search, jobs - all custom
8. Database is king - No Redis, no Elasticsearch
9. Test with fixtures - Deterministic, fast, simple
10. Ship incrementally - Many small commits
11. Tests ship with features - Not TDD, not afterthought, but together
12. Refactor toward consistency - Establish patterns, then update old code
13. CSS uses the platform - Native layers, nesting, OKLCH - no preprocessors
14. Design tokens everywhere - CSS variables for colors, spacing, typography

The best code is the code you don't write. The second best is the code that's obviously correct.