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

devise

pundit

cancancan

dry-rb

interactor

view_component

sidekiq

redis

graphql

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:

resolve

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

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.