37signals-rails-style

# 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

| Gem/Pattern            | Why                               |
|------------------------|-----------------------------------|
| `devise`               | Auth is ~150 lines of custom code |
| `pundit`/`cancancan`   | Authorization lives in models     |
| `dry-rb`, `interactor` | Over-engineered                   |
| `view_component`       | ERB partials are fine             |
| `sidekiq`, `redis`     | Use Solid Queue (database-backed) |
| `graphql`              | REST with Turbo is sufficient     |

---

## Routing: Everything is CRUD

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

```ruby
# 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.

```ruby
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:

```ruby
# 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:

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

### Concern Structure

```ruby
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

```ruby
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:

```ruby
# 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.