feat(skills): Add dhh-rails-style skill for 37signals Rails conventions
Router-pattern skill with sectioned references: - controllers.md: REST mapping, concerns, Turbo, API patterns - models.md: Concerns, state records, callbacks, scopes - frontend.md: Turbo, Stimulus, CSS architecture - architecture.md: Routing, auth, jobs, caching, config - gems.md: What they use vs avoid, decision framework Based on analysis of Fizzy (Campfire) codebase. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,341 @@
|
||||
# Architecture - DHH Rails Style
|
||||
|
||||
<routing>
|
||||
## Routing
|
||||
|
||||
Everything maps to CRUD. Nested resources for related actions:
|
||||
|
||||
```ruby
|
||||
Rails.application.routes.draw do
|
||||
resources :boards do
|
||||
resources :cards do
|
||||
resource :closure
|
||||
resource :goldness
|
||||
resource :not_now
|
||||
resources :assignments
|
||||
resources :comments
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Multi-tenancy** via URL (not subdomain):
|
||||
```ruby
|
||||
# /{account_id}/boards/...
|
||||
scope "/:account_id" do
|
||||
resources :boards
|
||||
end
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- No subdomain DNS complexity
|
||||
- Deep links work naturally
|
||||
- Middleware extracts account_id, moves to SCRIPT_NAME
|
||||
- `Current.account` available everywhere
|
||||
</routing>
|
||||
|
||||
<authentication>
|
||||
## Authentication
|
||||
|
||||
Custom passwordless magic link auth (~150 lines total):
|
||||
|
||||
```ruby
|
||||
# app/models/session.rb
|
||||
class Session < ApplicationRecord
|
||||
belongs_to :user
|
||||
|
||||
before_create { self.token = SecureRandom.urlsafe_base64(32) }
|
||||
end
|
||||
|
||||
# app/models/magic_link.rb
|
||||
class MagicLink < ApplicationRecord
|
||||
belongs_to :user
|
||||
|
||||
before_create do
|
||||
self.code = SecureRandom.random_number(100_000..999_999).to_s
|
||||
self.expires_at = 15.minutes.from_now
|
||||
end
|
||||
|
||||
def expired?
|
||||
expires_at < Time.current
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Why not Devise:**
|
||||
- ~150 lines vs massive dependency
|
||||
- No password storage liability
|
||||
- Simpler UX for users
|
||||
- Full control over flow
|
||||
|
||||
**Bearer token** for APIs:
|
||||
```ruby
|
||||
module Authentication
|
||||
extend ActiveSupport::Concern
|
||||
|
||||
included do
|
||||
before_action :authenticate
|
||||
end
|
||||
|
||||
private
|
||||
def authenticate
|
||||
if bearer_token = request.headers["Authorization"]&.split(" ")&.last
|
||||
Current.session = Session.find_by(token: bearer_token)
|
||||
else
|
||||
Current.session = Session.find_by(id: cookies.signed[:session_id])
|
||||
end
|
||||
|
||||
redirect_to login_path unless Current.session
|
||||
end
|
||||
end
|
||||
```
|
||||
</authentication>
|
||||
|
||||
<background_jobs>
|
||||
## Background Jobs
|
||||
|
||||
Jobs are shallow wrappers calling model methods:
|
||||
|
||||
```ruby
|
||||
class NotifyWatchersJob < ApplicationJob
|
||||
def perform(card)
|
||||
card.notify_watchers
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Naming convention:**
|
||||
- `_later` suffix for async: `card.notify_watchers_later`
|
||||
- `_now` suffix for immediate: `card.notify_watchers_now`
|
||||
|
||||
```ruby
|
||||
module Watchable
|
||||
def notify_watchers_later
|
||||
NotifyWatchersJob.perform_later(self)
|
||||
end
|
||||
|
||||
def notify_watchers_now
|
||||
NotifyWatchersJob.perform_now(self)
|
||||
end
|
||||
|
||||
def notify_watchers
|
||||
watchers.each do |watcher|
|
||||
WatcherMailer.notification(watcher, self).deliver_later
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Database-backed** with Solid Queue:
|
||||
- No Redis required
|
||||
- Same transactional guarantees as your data
|
||||
- Simpler infrastructure
|
||||
</background_jobs>
|
||||
|
||||
<current_attributes>
|
||||
## Current Attributes
|
||||
|
||||
Use `Current` for request-scoped state:
|
||||
|
||||
```ruby
|
||||
# app/models/current.rb
|
||||
class Current < ActiveSupport::CurrentAttributes
|
||||
attribute :session, :user, :account, :request_id
|
||||
|
||||
delegate :user, to: :session, allow_nil: true
|
||||
|
||||
def account=(account)
|
||||
super
|
||||
Time.zone = account&.time_zone || "UTC"
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
Set in controller:
|
||||
```ruby
|
||||
class ApplicationController < ActionController::Base
|
||||
before_action :set_current_request
|
||||
|
||||
private
|
||||
def set_current_request
|
||||
Current.session = authenticated_session
|
||||
Current.account = Account.find(params[:account_id])
|
||||
Current.request_id = request.request_id
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
Use throughout app:
|
||||
```ruby
|
||||
class Card < ApplicationRecord
|
||||
belongs_to :creator, default: -> { Current.user }
|
||||
end
|
||||
```
|
||||
</current_attributes>
|
||||
|
||||
<caching>
|
||||
## Caching
|
||||
|
||||
**HTTP caching** with ETags:
|
||||
```ruby
|
||||
fresh_when etag: [@card, Current.user.timezone]
|
||||
```
|
||||
|
||||
**Fragment caching:**
|
||||
```erb
|
||||
<% cache card do %>
|
||||
<%= render card %>
|
||||
<% end %>
|
||||
```
|
||||
|
||||
**Russian doll caching:**
|
||||
```erb
|
||||
<% cache @board do %>
|
||||
<% @board.cards.each do |card| %>
|
||||
<% cache card do %>
|
||||
<%= render card %>
|
||||
<% end %>
|
||||
<% end %>
|
||||
<% end %>
|
||||
```
|
||||
|
||||
**Cache invalidation** via `touch: true`:
|
||||
```ruby
|
||||
class Card < ApplicationRecord
|
||||
belongs_to :board, touch: true
|
||||
end
|
||||
```
|
||||
|
||||
**Solid Cache** - database-backed:
|
||||
- No Redis required
|
||||
- Consistent with application data
|
||||
- Simpler infrastructure
|
||||
</caching>
|
||||
|
||||
<configuration>
|
||||
## Configuration
|
||||
|
||||
**ENV.fetch with defaults:**
|
||||
```ruby
|
||||
# config/application.rb
|
||||
config.active_job.queue_adapter = ENV.fetch("QUEUE_ADAPTER", "solid_queue").to_sym
|
||||
config.cache_store = ENV.fetch("CACHE_STORE", "solid_cache").to_sym
|
||||
```
|
||||
|
||||
**Multiple databases:**
|
||||
```yaml
|
||||
# config/database.yml
|
||||
production:
|
||||
primary:
|
||||
<<: *default
|
||||
cable:
|
||||
<<: *default
|
||||
migrations_paths: db/cable_migrate
|
||||
queue:
|
||||
<<: *default
|
||||
migrations_paths: db/queue_migrate
|
||||
cache:
|
||||
<<: *default
|
||||
migrations_paths: db/cache_migrate
|
||||
```
|
||||
|
||||
**Switch between SQLite and MySQL via ENV:**
|
||||
```ruby
|
||||
adapter = ENV.fetch("DATABASE_ADAPTER", "sqlite3")
|
||||
```
|
||||
|
||||
**CSP extensible via ENV:**
|
||||
```ruby
|
||||
config.content_security_policy do |policy|
|
||||
policy.default_src :self
|
||||
policy.script_src :self, *ENV.fetch("CSP_SCRIPT_SRC", "").split(",")
|
||||
end
|
||||
```
|
||||
</configuration>
|
||||
|
||||
<testing>
|
||||
## Testing
|
||||
|
||||
**Minitest**, not RSpec:
|
||||
```ruby
|
||||
class CardTest < ActiveSupport::TestCase
|
||||
test "closing a card creates a closure" do
|
||||
card = cards(:one)
|
||||
|
||||
card.close
|
||||
|
||||
assert card.closed?
|
||||
assert_not_nil card.closure
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Fixtures** instead of factories:
|
||||
```yaml
|
||||
# test/fixtures/cards.yml
|
||||
one:
|
||||
title: First Card
|
||||
board: main
|
||||
creator: alice
|
||||
|
||||
two:
|
||||
title: Second Card
|
||||
board: main
|
||||
creator: bob
|
||||
```
|
||||
|
||||
**Integration tests** for controllers:
|
||||
```ruby
|
||||
class CardsControllerTest < ActionDispatch::IntegrationTest
|
||||
test "closing a card" do
|
||||
card = cards(:one)
|
||||
sign_in users(:alice)
|
||||
|
||||
post card_closure_path(card)
|
||||
|
||||
assert_response :success
|
||||
assert card.reload.closed?
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Tests ship with features** - same commit, not TDD-first but together.
|
||||
|
||||
**Regression tests for security fixes** - always.
|
||||
</testing>
|
||||
|
||||
<events>
|
||||
## Event Tracking
|
||||
|
||||
Events are the single source of truth:
|
||||
|
||||
```ruby
|
||||
class Event < ApplicationRecord
|
||||
belongs_to :creator, class_name: "User"
|
||||
belongs_to :eventable, polymorphic: true
|
||||
|
||||
serialize :particulars, coder: JSON
|
||||
end
|
||||
```
|
||||
|
||||
**Eventable concern:**
|
||||
```ruby
|
||||
module Eventable
|
||||
extend ActiveSupport::Concern
|
||||
|
||||
included do
|
||||
has_many :events, as: :eventable, dependent: :destroy
|
||||
end
|
||||
|
||||
def record_event(action, particulars = {})
|
||||
events.create!(
|
||||
creator: Current.user,
|
||||
action: action,
|
||||
particulars: particulars
|
||||
)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Webhooks driven by events** - events are the canonical source.
|
||||
</events>
|
||||
@@ -0,0 +1,164 @@
|
||||
# Controllers - DHH Rails Style
|
||||
|
||||
<rest_mapping>
|
||||
## Everything Maps to CRUD
|
||||
|
||||
Custom actions become new resources. Instead of verbs on existing resources, create noun resources:
|
||||
|
||||
```ruby
|
||||
# Instead of this:
|
||||
POST /cards/:id/close
|
||||
DELETE /cards/:id/close
|
||||
POST /cards/:id/archive
|
||||
|
||||
# Do this:
|
||||
POST /cards/:id/closure # create closure
|
||||
DELETE /cards/:id/closure # destroy closure
|
||||
POST /cards/:id/archival # create archival
|
||||
```
|
||||
|
||||
**Real examples from 37signals:**
|
||||
```ruby
|
||||
resources :cards do
|
||||
resource :closure # closing/reopening
|
||||
resource :goldness # marking important
|
||||
resource :not_now # postponing
|
||||
resources :assignments # managing assignees
|
||||
end
|
||||
```
|
||||
|
||||
Each resource gets its own controller with standard CRUD actions.
|
||||
</rest_mapping>
|
||||
|
||||
<controller_concerns>
|
||||
## Concerns for Shared Behavior
|
||||
|
||||
Controllers use concerns extensively. Common patterns:
|
||||
|
||||
**CardScoped** - loads @card, @board, provides render_card_replacement
|
||||
```ruby
|
||||
module CardScoped
|
||||
extend ActiveSupport::Concern
|
||||
|
||||
included do
|
||||
before_action :set_card
|
||||
end
|
||||
|
||||
private
|
||||
def set_card
|
||||
@card = Card.find(params[:card_id])
|
||||
@board = @card.board
|
||||
end
|
||||
|
||||
def render_card_replacement
|
||||
render turbo_stream: turbo_stream.replace(@card)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**BoardScoped** - loads @board
|
||||
**CurrentRequest** - populates Current with request data
|
||||
**CurrentTimezone** - wraps requests in user's timezone
|
||||
**FilterScoped** - handles complex filtering
|
||||
**TurboFlash** - flash messages via Turbo Stream
|
||||
**ViewTransitions** - disables on page refresh
|
||||
</controller_concerns>
|
||||
|
||||
<turbo_responses>
|
||||
## Turbo Stream Responses
|
||||
|
||||
Use Turbo Streams for partial updates:
|
||||
|
||||
```ruby
|
||||
class Cards::ClosuresController < ApplicationController
|
||||
include CardScoped
|
||||
|
||||
def create
|
||||
@card.close
|
||||
render_card_replacement
|
||||
end
|
||||
|
||||
def destroy
|
||||
@card.reopen
|
||||
render_card_replacement
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
For complex updates, use morphing:
|
||||
```ruby
|
||||
render turbo_stream: turbo_stream.morph(@card)
|
||||
```
|
||||
</turbo_responses>
|
||||
|
||||
<api_patterns>
|
||||
## API Design
|
||||
|
||||
Same controllers, different format. Convention for responses:
|
||||
|
||||
```ruby
|
||||
def create
|
||||
@card = Card.create!(card_params)
|
||||
|
||||
respond_to do |format|
|
||||
format.html { redirect_to @card }
|
||||
format.json { head :created, location: @card }
|
||||
end
|
||||
end
|
||||
|
||||
def update
|
||||
@card.update!(card_params)
|
||||
|
||||
respond_to do |format|
|
||||
format.html { redirect_to @card }
|
||||
format.json { head :no_content }
|
||||
end
|
||||
end
|
||||
|
||||
def destroy
|
||||
@card.destroy
|
||||
|
||||
respond_to do |format|
|
||||
format.html { redirect_to cards_path }
|
||||
format.json { head :no_content }
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Status codes:**
|
||||
- Create: 201 Created + Location header
|
||||
- Update: 204 No Content
|
||||
- Delete: 204 No Content
|
||||
- Bearer token authentication
|
||||
</api_patterns>
|
||||
|
||||
<http_caching>
|
||||
## HTTP Caching
|
||||
|
||||
Extensive use of ETags and conditional GETs:
|
||||
|
||||
```ruby
|
||||
class CardsController < ApplicationController
|
||||
def show
|
||||
@card = Card.find(params[:id])
|
||||
fresh_when etag: [@card, Current.user.timezone]
|
||||
end
|
||||
|
||||
def index
|
||||
@cards = @board.cards.preloaded
|
||||
fresh_when etag: [@cards, @board.updated_at]
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
Key insight: Times render server-side in user's timezone, so timezone must affect the ETag to prevent serving wrong times to other timezones.
|
||||
|
||||
**ApplicationController global etag:**
|
||||
```ruby
|
||||
class ApplicationController < ActionController::Base
|
||||
etag { "v1" } # Bump to invalidate all caches
|
||||
end
|
||||
```
|
||||
|
||||
Use `touch: true` on associations for cache invalidation.
|
||||
</http_caching>
|
||||
@@ -0,0 +1,207 @@
|
||||
# Frontend - DHH Rails Style
|
||||
|
||||
<turbo_patterns>
|
||||
## Turbo Patterns
|
||||
|
||||
**Turbo Streams** for partial updates:
|
||||
```erb
|
||||
<%# app/views/cards/closures/create.turbo_stream.erb %>
|
||||
<%= turbo_stream.replace @card %>
|
||||
```
|
||||
|
||||
**Morphing** for complex updates:
|
||||
```ruby
|
||||
render turbo_stream: turbo_stream.morph(@card)
|
||||
```
|
||||
|
||||
**Fragment caching** with `cached: true`:
|
||||
```erb
|
||||
<%= render partial: "card", collection: @cards, cached: true %>
|
||||
```
|
||||
|
||||
**No ViewComponents** - standard partials work fine.
|
||||
</turbo_patterns>
|
||||
|
||||
<stimulus_controllers>
|
||||
## Stimulus Controllers
|
||||
|
||||
52 controllers in Fizzy, split 62% reusable, 38% domain-specific.
|
||||
|
||||
**Characteristics:**
|
||||
- Single responsibility per controller
|
||||
- Configuration via values/classes
|
||||
- Events for communication
|
||||
- Private methods with #
|
||||
- Most under 50 lines
|
||||
|
||||
**Examples:**
|
||||
|
||||
```javascript
|
||||
// copy-to-clipboard (25 lines)
|
||||
import { Controller } from "@hotwired/stimulus"
|
||||
|
||||
export default class extends Controller {
|
||||
static values = { content: String }
|
||||
|
||||
copy() {
|
||||
navigator.clipboard.writeText(this.contentValue)
|
||||
this.#showFeedback()
|
||||
}
|
||||
|
||||
#showFeedback() {
|
||||
this.element.classList.add("copied")
|
||||
setTimeout(() => this.element.classList.remove("copied"), 1500)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// auto-click (7 lines)
|
||||
import { Controller } from "@hotwired/stimulus"
|
||||
|
||||
export default class extends Controller {
|
||||
connect() {
|
||||
this.element.click()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// toggle-class (31 lines)
|
||||
import { Controller } from "@hotwired/stimulus"
|
||||
|
||||
export default class extends Controller {
|
||||
static classes = ["toggle"]
|
||||
static values = { open: { type: Boolean, default: false } }
|
||||
|
||||
toggle() {
|
||||
this.openValue = !this.openValue
|
||||
}
|
||||
|
||||
openValueChanged() {
|
||||
this.element.classList.toggle(this.toggleClass, this.openValue)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// dialog (64 lines) - for modal dialogs
|
||||
// local-save (59 lines) - localStorage persistence
|
||||
// drag-and-drop (150 lines) - the largest, still reasonable
|
||||
```
|
||||
</stimulus_controllers>
|
||||
|
||||
<css_architecture>
|
||||
## CSS Architecture
|
||||
|
||||
Vanilla CSS with modern features, no preprocessors.
|
||||
|
||||
**CSS @layer** for cascade control:
|
||||
```css
|
||||
@layer reset, base, components, modules, utilities;
|
||||
|
||||
@layer reset {
|
||||
*, *::before, *::after { box-sizing: border-box; }
|
||||
}
|
||||
|
||||
@layer base {
|
||||
body { font-family: var(--font-sans); }
|
||||
}
|
||||
|
||||
@layer components {
|
||||
.btn { /* button styles */ }
|
||||
}
|
||||
|
||||
@layer modules {
|
||||
.card { /* card module styles */ }
|
||||
}
|
||||
|
||||
@layer utilities {
|
||||
.hidden { display: none; }
|
||||
}
|
||||
```
|
||||
|
||||
**OKLCH color system** for perceptual uniformity:
|
||||
```css
|
||||
:root {
|
||||
--color-primary: oklch(60% 0.15 250);
|
||||
--color-success: oklch(65% 0.2 145);
|
||||
--color-warning: oklch(75% 0.15 85);
|
||||
--color-danger: oklch(55% 0.2 25);
|
||||
}
|
||||
```
|
||||
|
||||
**Dark mode** via CSS variables:
|
||||
```css
|
||||
:root {
|
||||
--bg: oklch(98% 0 0);
|
||||
--text: oklch(20% 0 0);
|
||||
}
|
||||
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root {
|
||||
--bg: oklch(15% 0 0);
|
||||
--text: oklch(90% 0 0);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Native CSS nesting:**
|
||||
```css
|
||||
.card {
|
||||
padding: var(--space-4);
|
||||
|
||||
& .title {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
&:hover {
|
||||
background: var(--bg-hover);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**~60 minimal utilities** vs Tailwind's hundreds.
|
||||
|
||||
**Modern features used:**
|
||||
- `@starting-style` for enter animations
|
||||
- `color-mix()` for color manipulation
|
||||
- `:has()` for parent selection
|
||||
- Logical properties (`margin-inline`, `padding-block`)
|
||||
- Container queries
|
||||
</css_architecture>
|
||||
|
||||
<view_patterns>
|
||||
## View Patterns
|
||||
|
||||
**Standard partials** - no ViewComponents:
|
||||
```erb
|
||||
<%# app/views/cards/_card.html.erb %>
|
||||
<article id="<%= dom_id(card) %>" class="card">
|
||||
<%= render "cards/header", card: card %>
|
||||
<%= render "cards/body", card: card %>
|
||||
<%= render "cards/footer", card: card %>
|
||||
</article>
|
||||
```
|
||||
|
||||
**Fragment caching:**
|
||||
```erb
|
||||
<% cache card do %>
|
||||
<%= render "cards/card", card: card %>
|
||||
<% end %>
|
||||
```
|
||||
|
||||
**Collection caching:**
|
||||
```erb
|
||||
<%= render partial: "card", collection: @cards, cached: true %>
|
||||
```
|
||||
|
||||
**Simple component naming** - no strict BEM:
|
||||
```css
|
||||
.card { }
|
||||
.card .title { }
|
||||
.card .actions { }
|
||||
.card.golden { }
|
||||
.card.closed { }
|
||||
```
|
||||
</view_patterns>
|
||||
@@ -0,0 +1,167 @@
|
||||
# Gems - DHH Rails Style
|
||||
|
||||
<what_they_use>
|
||||
## What 37signals Uses
|
||||
|
||||
**Core Rails stack:**
|
||||
- turbo-rails, stimulus-rails, importmap-rails
|
||||
- propshaft (asset pipeline)
|
||||
|
||||
**Database-backed services (Solid suite):**
|
||||
- solid_queue - background jobs
|
||||
- solid_cache - caching
|
||||
- solid_cable - WebSockets/Action Cable
|
||||
|
||||
**Authentication & Security:**
|
||||
- bcrypt (for any password hashing needed)
|
||||
|
||||
**Their own gems:**
|
||||
- geared_pagination (cursor-based pagination)
|
||||
- lexxy (rich text editor)
|
||||
- mittens (mailer utilities)
|
||||
|
||||
**Utilities:**
|
||||
- rqrcode (QR code generation)
|
||||
- redcarpet + rouge (Markdown rendering)
|
||||
- web-push (push notifications)
|
||||
|
||||
**Deployment & Operations:**
|
||||
- kamal (Docker deployment)
|
||||
- thruster (HTTP/2 proxy)
|
||||
- mission_control-jobs (job monitoring)
|
||||
- autotuner (GC tuning)
|
||||
</what_they_use>
|
||||
|
||||
<what_they_avoid>
|
||||
## What They Deliberately Avoid
|
||||
|
||||
**Authentication:**
|
||||
```
|
||||
devise → Custom ~150-line auth
|
||||
```
|
||||
Why: Full control, no password liability with magic links, simpler.
|
||||
|
||||
**Authorization:**
|
||||
```
|
||||
pundit/cancancan → Simple role checks in models
|
||||
```
|
||||
Why: Most apps don't need policy objects. A method on the model suffices:
|
||||
```ruby
|
||||
class Board < ApplicationRecord
|
||||
def editable_by?(user)
|
||||
user.admin? || user == creator
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Background Jobs:**
|
||||
```
|
||||
sidekiq → Solid Queue
|
||||
```
|
||||
Why: Database-backed means no Redis, same transactional guarantees.
|
||||
|
||||
**Caching:**
|
||||
```
|
||||
redis → Solid Cache
|
||||
```
|
||||
Why: Database is already there, simpler infrastructure.
|
||||
|
||||
**Search:**
|
||||
```
|
||||
elasticsearch → Custom sharded search
|
||||
```
|
||||
Why: Built exactly what they need, no external service dependency.
|
||||
|
||||
**View Layer:**
|
||||
```
|
||||
view_component → Standard partials
|
||||
```
|
||||
Why: Partials work fine. ViewComponents add complexity without clear benefit for their use case.
|
||||
|
||||
**API:**
|
||||
```
|
||||
GraphQL → REST with Turbo
|
||||
```
|
||||
Why: REST is sufficient when you control both ends. GraphQL complexity not justified.
|
||||
|
||||
**Factories:**
|
||||
```
|
||||
factory_bot → Fixtures
|
||||
```
|
||||
Why: Fixtures are simpler, faster, and encourage thinking about data relationships upfront.
|
||||
</what_they_avoid>
|
||||
|
||||
<decision_framework>
|
||||
## Decision Framework
|
||||
|
||||
Before adding a gem, ask:
|
||||
|
||||
1. **Can vanilla Rails do this?**
|
||||
- ActiveRecord can do most things Sequel can
|
||||
- ActionMailer handles email fine
|
||||
- ActiveJob works for most job needs
|
||||
|
||||
2. **Is the complexity worth it?**
|
||||
- 150 lines of custom code vs. 10,000-line gem
|
||||
- You'll understand your code better
|
||||
- Fewer upgrade headaches
|
||||
|
||||
3. **Does it add infrastructure?**
|
||||
- Redis? Consider database-backed alternatives
|
||||
- External service? Consider building in-house
|
||||
- Simpler infrastructure = fewer failure modes
|
||||
|
||||
4. **Is it from someone you trust?**
|
||||
- 37signals gems: battle-tested at scale
|
||||
- Well-maintained, focused gems: usually fine
|
||||
- Kitchen-sink gems: probably overkill
|
||||
|
||||
**The philosophy:**
|
||||
> "Build solutions before reaching for gems."
|
||||
|
||||
Not anti-gem, but pro-understanding. Use gems when they genuinely solve a problem you have, not a problem you might have.
|
||||
</decision_framework>
|
||||
|
||||
<gem_patterns>
|
||||
## Gem Usage Patterns
|
||||
|
||||
**Pagination:**
|
||||
```ruby
|
||||
# geared_pagination - cursor-based
|
||||
class CardsController < ApplicationController
|
||||
def index
|
||||
@cards = @board.cards.geared(page: params[:page])
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Markdown:**
|
||||
```ruby
|
||||
# redcarpet + rouge
|
||||
class MarkdownRenderer
|
||||
def self.render(text)
|
||||
Redcarpet::Markdown.new(
|
||||
Redcarpet::Render::HTML.new(filter_html: true),
|
||||
autolink: true,
|
||||
fenced_code_blocks: true
|
||||
).render(text)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Background jobs:**
|
||||
```ruby
|
||||
# solid_queue - no Redis
|
||||
class ApplicationJob < ActiveJob::Base
|
||||
queue_as :default
|
||||
# Just works, backed by database
|
||||
end
|
||||
```
|
||||
|
||||
**Caching:**
|
||||
```ruby
|
||||
# solid_cache - no Redis
|
||||
# config/environments/production.rb
|
||||
config.cache_store = :solid_cache_store
|
||||
```
|
||||
</gem_patterns>
|
||||
@@ -0,0 +1,214 @@
|
||||
# Models - DHH Rails Style
|
||||
|
||||
<model_concerns>
|
||||
## Concerns for Horizontal Behavior
|
||||
|
||||
Models heavily use concerns. A typical Card model includes 14+ concerns:
|
||||
|
||||
```ruby
|
||||
class Card < ApplicationRecord
|
||||
include Assignable
|
||||
include Attachments
|
||||
include Broadcastable
|
||||
include Closeable
|
||||
include Colored
|
||||
include Eventable
|
||||
include Golden
|
||||
include Mentions
|
||||
include Multistep
|
||||
include Pinnable
|
||||
include Postponable
|
||||
include Readable
|
||||
include Searchable
|
||||
include Taggable
|
||||
include Watchable
|
||||
end
|
||||
```
|
||||
|
||||
Each concern is self-contained with associations, scopes, and methods.
|
||||
|
||||
**Naming:** Adjectives describing capability (`Closeable`, `Publishable`, `Watchable`)
|
||||
</model_concerns>
|
||||
|
||||
<state_records>
|
||||
## State as Records, Not Booleans
|
||||
|
||||
Instead of boolean columns, create separate records:
|
||||
|
||||
```ruby
|
||||
# Instead of:
|
||||
closed: boolean
|
||||
is_golden: boolean
|
||||
postponed: boolean
|
||||
|
||||
# Create records:
|
||||
class Card::Closure < ApplicationRecord
|
||||
belongs_to :card
|
||||
belongs_to :creator, class_name: "User"
|
||||
end
|
||||
|
||||
class Card::Goldness < ApplicationRecord
|
||||
belongs_to :card
|
||||
belongs_to :creator, class_name: "User"
|
||||
end
|
||||
|
||||
class Card::NotNow < ApplicationRecord
|
||||
belongs_to :card
|
||||
belongs_to :creator, class_name: "User"
|
||||
end
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Automatic timestamps (when it happened)
|
||||
- Track who made changes
|
||||
- Easy filtering via joins and `where.missing`
|
||||
- Enables rich UI showing when/who
|
||||
|
||||
**In the model:**
|
||||
```ruby
|
||||
module Closeable
|
||||
extend ActiveSupport::Concern
|
||||
|
||||
included do
|
||||
has_one :closure, dependent: :destroy
|
||||
end
|
||||
|
||||
def closed?
|
||||
closure.present?
|
||||
end
|
||||
|
||||
def close(creator: Current.user)
|
||||
create_closure!(creator: creator)
|
||||
end
|
||||
|
||||
def reopen
|
||||
closure&.destroy
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**Querying:**
|
||||
```ruby
|
||||
Card.joins(:closure) # closed cards
|
||||
Card.where.missing(:closure) # open cards
|
||||
```
|
||||
</state_records>
|
||||
|
||||
<callbacks>
|
||||
## Callbacks - Used Sparingly
|
||||
|
||||
Only 38 callback occurrences across 30 files in Fizzy. Guidelines:
|
||||
|
||||
**Use for:**
|
||||
- `after_commit` for async work
|
||||
- `before_save` for derived data
|
||||
- `after_create_commit` for side effects
|
||||
|
||||
**Avoid:**
|
||||
- Complex callback chains
|
||||
- Business logic in callbacks
|
||||
- Synchronous external calls
|
||||
|
||||
```ruby
|
||||
class Card < ApplicationRecord
|
||||
after_create_commit :notify_watchers_later
|
||||
before_save :update_search_index, if: :title_changed?
|
||||
|
||||
private
|
||||
def notify_watchers_later
|
||||
NotifyWatchersJob.perform_later(self)
|
||||
end
|
||||
end
|
||||
```
|
||||
</callbacks>
|
||||
|
||||
<scopes>
|
||||
## Scope Naming
|
||||
|
||||
Standard scope names:
|
||||
|
||||
```ruby
|
||||
class Card < ApplicationRecord
|
||||
scope :chronologically, -> { order(created_at: :asc) }
|
||||
scope :reverse_chronologically, -> { order(created_at: :desc) }
|
||||
scope :alphabetically, -> { order(title: :asc) }
|
||||
scope :latest, -> { reverse_chronologically.limit(10) }
|
||||
|
||||
# Standard eager loading
|
||||
scope :preloaded, -> { includes(:creator, :assignees, :tags) }
|
||||
|
||||
# Parameterized
|
||||
scope :indexed_by, ->(column) { order(column => :asc) }
|
||||
scope :sorted_by, ->(column, direction = :asc) { order(column => direction) }
|
||||
end
|
||||
```
|
||||
</scopes>
|
||||
|
||||
<poros>
|
||||
## Plain Old Ruby Objects
|
||||
|
||||
POROs namespaced under parent models:
|
||||
|
||||
```ruby
|
||||
# app/models/event/description.rb
|
||||
class Event::Description
|
||||
def initialize(event)
|
||||
@event = event
|
||||
end
|
||||
|
||||
def to_s
|
||||
# Presentation logic for event description
|
||||
end
|
||||
end
|
||||
|
||||
# app/models/card/eventable/system_commenter.rb
|
||||
class Card::Eventable::SystemCommenter
|
||||
def initialize(card)
|
||||
@card = card
|
||||
end
|
||||
|
||||
def comment(message)
|
||||
# Business logic
|
||||
end
|
||||
end
|
||||
|
||||
# app/models/user/filtering.rb
|
||||
class User::Filtering
|
||||
# View context bundling
|
||||
end
|
||||
```
|
||||
|
||||
**NOT used for service objects.** Business logic stays in models.
|
||||
</poros>
|
||||
|
||||
<verbs_predicates>
|
||||
## Method Naming
|
||||
|
||||
**Verbs** - Actions that change state:
|
||||
```ruby
|
||||
card.close
|
||||
card.reopen
|
||||
card.gild # make golden
|
||||
card.ungild
|
||||
board.publish
|
||||
board.archive
|
||||
```
|
||||
|
||||
**Predicates** - Queries derived from state:
|
||||
```ruby
|
||||
card.closed? # closure.present?
|
||||
card.golden? # goldness.present?
|
||||
board.published?
|
||||
```
|
||||
|
||||
**Avoid** generic setters:
|
||||
```ruby
|
||||
# Bad
|
||||
card.set_closed(true)
|
||||
card.update_golden_status(false)
|
||||
|
||||
# Good
|
||||
card.close
|
||||
card.ungild
|
||||
```
|
||||
</verbs_predicates>
|
||||
Reference in New Issue
Block a user