37signals-rails

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 Priority Category Impact Prefix 1 Architecture Fundamentals CRITICAL arch- 2 Controllers & REST CRITICAL ctrl- 3 Domain Modeling HIGH model- 4 State Management HIGH state- 5 Database & Infrastructure HIGH db- 6 Views & Frontend MEDIUM view- 7 Code Style MEDIUM style- 8 Testing MEDIUM 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 File Description references/_sections.md Category definitions and ordering assets/templates/_template.md Template for new rules metadata.json Version and reference information