37signals Rails Best Practices

Comprehensive coding principles and conventions for Ruby on Rails applications, as practiced at 37signals (Basecamp, HEY, Fizzy). Contains 56 rules across 8 categories, prioritized by architectural impact. Derived from official 37signals sources: the Fizzy codebase, STYLE.md, AGENTS.md, the Rails Doctrine, DHH's "On Writing Software Well" series, and the unofficial 37signals style guide (265 Fizzy PRs).

When to Apply

Reference these guidelines when:

• Writing new Rails controllers, models, or views
• Deciding between gems and vanilla Rails
• Modeling state and database schema
• Setting up background jobs, caching, or real-time features
• Reviewing code for 37signals-style conventions
• Refactoring toward rich domain models
• Choosing authentication or authorization approach
• Adding Stimulus controllers or Turbo patterns

Rule Categories by Priority

arch-

ctrl-

model-

state-

db-

view-

style-

test-

Quick Reference

1. Architecture Fundamentals (CRITICAL)

• arch-rich-models

  - Rich Domain Models Over Service Objects

• arch-vanilla-rails

  - Vanilla Rails is Plenty

• arch-avoid-patterns

  - Deliberately Avoided Patterns and Gems

• arch-earn-abstractions

  - Earn Abstractions Through Rule of Three

• arch-build-before-gems

  - Build It Yourself Before Reaching for Gems

• arch-ship-to-learn

  - Start Simple — Add Complexity Only After Validation

• arch-domain-facades

  - Domain Models as Facades Over Internal Complexity

• arch-single-business-layer

  - Single Layer for Business Logic

• arch-custom-auth

  - Custom Passwordless Auth Over Devise

2. Controllers & REST (CRITICAL)

• ctrl-crud-only

  - CRUD Controllers Over Custom Actions

• ctrl-model-as-resources

  - Model Non-CRUD Operations as Separate Resources

• ctrl-thin-controllers

  - Thin Controllers with Rich Domain Models

• ctrl-params-expect

  - Use params.expect() for Parameter Validation

• ctrl-controller-concerns

  - Controller Concerns for Cross-Cutting Behavior

• ctrl-nested-resources

  - Nested Resources with scope module

3. Domain Modeling (HIGH)

• model-concerns

  - Concerns for Horizontal Code Sharing

• model-normalizes

  - Use normalizes Macro for Data Cleaning

• model-store-accessor

  - Use store_accessor for JSON Column Access

• model-delegated-type

  - Use delegated_type for Polymorphism

• model-counter-caches

  - Counter Caches to Prevent N+1 Count Queries

• model-touch-chains

  - Touch Chains for Cache Invalidation

• model-callbacks-auxiliary

  - Callbacks for Auxiliary Complexity

• model-event-tracking

  - Polymorphic Event Model for Activity Tracking

• model-poro-namespacing

  - Namespace POROs Under Parent Models

4. State Management (HIGH)

• state-records-over-booleans

  - Records as State Over Boolean Columns

• state-timestamps

  - Timestamps for State Transitions

• state-enums

  - Enums for Categorical States

• state-db-constraints

  - Database Constraints Over ActiveRecord Validations

• state-write-time

  - Compute at Write Time Not Read Time

5. Database & Infrastructure (HIGH)

• db-backed-everything

  - Database-Backed Everything

• db-solid-queue

  - Solid Queue for Background Jobs

• db-solid-cable

  - Solid Cable for Real-Time Pub/Sub

• db-solid-cache

  - Solid Cache for Application Caching

• db-multi-tenancy

  - Path-Based Multi-Tenancy with Current.account

• db-uuid-primary-keys

  - UUIDs as Primary Keys

• db-no-foreign-keys

  - No Foreign Key Constraints

6. Views & Frontend (MEDIUM)

• view-turbo-frames

  - Turbo Frames for Scoped Page Fragments

• view-turbo-streams

  - Turbo Streams for Real-Time Updates

• view-stimulus-targets

  - Stimulus Targets Over CSS Selectors

• view-stimulus-design

  - Stimulus Controller Design Principles

• view-helpers-not-partials

  - Extract Logic to Helpers Not Partials

• view-progressive-enhancement

  - Progressive Enhancement as Primary Pattern

• view-fragment-caching

  - Fragment Caching for View Performance

• view-http-caching

  - HTTP Caching with fresh_when and ETags

7. Code Style (MEDIUM)

• style-conditionals

  - Expanded Conditionals Over Guard Clauses

• style-method-ordering

  - Methods Ordered by Call Sequence

• style-positive-names

  - Use Positive Names for Methods and Scopes

• style-naming-return-values

  - Method Names Reflect Return Values

• style-visibility-modifiers

  - Visibility Modifier Formatting

• style-bang-methods

  - Bang Methods Only When Non-Bang Exists

• style-async-naming

  - Use _later and _now Suffixes for Async Operations

8. Testing (MEDIUM)

• test-minitest

  - Minitest Over RSpec

• test-fixtures

  - Database Fixtures Over FactoryBot

• test-no-damage

  - No Test-Induced Design Damage

• test-no-system-tests

  - Integration Tests Over System Tests

• test-behavior

  - Test Behavior Not Implementation

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files