rubyn-code 0.1.0

data/skills/rails/multitenancy.md

@@ -0,0 +1,207 @@
+# Rails: Multitenancy
+
+## Pattern
+
+Multitenancy allows a single application instance to serve multiple organizations (tenants) with data isolation. Choose row-based tenancy (shared tables with a tenant_id column) for simplicity, or schema-based (separate PostgreSQL schemas per tenant) for stronger isolation.
+
+### Row-Based Tenancy (Most Common)
+
+```ruby
+# Every tenanted model has an organization_id
+class Order < ApplicationRecord
+  belongs_to :organization
+  belongs_to :user
+
+  # Default scope is tempting but dangerous — use explicit scoping instead
+end
+
+class User < ApplicationRecord
+  belongs_to :organization
+  has_many :orders
+end
+
+# Set the current tenant per request
+class ApplicationController < ActionController::Base
+  before_action :set_current_organization
+
+  private
+
+  def set_current_organization
+    Current.organization = current_user&.organization
+  end
+end
+
+# Use Current attributes (Rails 5.2+) for request-scoped tenant
+class Current < ActiveSupport::CurrentAttributes
+  attribute :user, :organization
+end
+```
+
+```ruby
+# Scoping all queries to the current tenant
+# Option A: Explicit scoping in controllers
+class OrdersController < ApplicationController
+  def index
+    @orders = Current.organization.orders.recent
+  end
+
+  def show
+    @order = Current.organization.orders.find(params[:id])
+  end
+end
+
+# Option B: acts_as_tenant gem (automatic scoping)
+# Gemfile: gem "acts_as_tenant"
+class Order < ApplicationRecord
+  acts_as_tenant :organization
+  # Automatically adds: default_scope { where(organization_id: ActsAsTenant.current_tenant.id) }
+  # Automatically validates: validates :organization_id, presence: true
+  # Automatically sets: before_validation { self.organization_id = ActsAsTenant.current_tenant.id }
+end
+
+# Controller setup
+class ApplicationController < ActionController::Base
+  set_current_tenant_through_filter
+  before_action :set_tenant
+
+  private
+
+  def set_tenant
+    set_current_tenant(current_user.organization)
+  end
+end
+
+# Now ALL queries are automatically scoped — no leaks possible
+Order.all        # => WHERE organization_id = 42 (automatic)
+Order.find(123)  # => WHERE id = 123 AND organization_id = 42 (automatic)
+```
+
+### Database Constraints for Safety
+
+```ruby
+# Migration — ensure tenant isolation at the database level
+class AddOrganizationToOrders < ActiveRecord::Migration[8.0]
+  def change
+    add_reference :orders, :organization, null: false, foreign_key: true, index: true
+
+    # Composite index for tenant-scoped queries
+    add_index :orders, [:organization_id, :created_at]
+    add_index :orders, [:organization_id, :status]
+
+    # Unique constraints scoped to tenant
+    add_index :orders, [:organization_id, :reference], unique: true
+    # Order references are unique WITHIN an organization, not globally
+  end
+end
+```
+
+### Testing Multitenancy
+
+```ruby
+# RSpec
+RSpec.describe Order, type: :model do
+  let(:org_a) { create(:organization) }
+  let(:org_b) { create(:organization) }
+
+  around do |example|
+    ActsAsTenant.with_tenant(org_a) { example.run }
+  end
+
+  it "scopes queries to the current tenant" do
+    order_a = create(:order, organization: org_a)
+
+    ActsAsTenant.with_tenant(org_b) do
+      order_b = create(:order, organization: org_b)
+      expect(Order.all).to eq([order_b])  # Only sees org_b's orders
+      expect(Order.all).not_to include(order_a)
+    end
+
+    expect(Order.all).to eq([order_a])  # Back to org_a
+  end
+end
+
+# Minitest
+class OrderTest < ActiveSupport::TestCase
+  setup do
+    @org = organizations(:acme)
+    ActsAsTenant.current_tenant = @org
+  end
+
+  teardown do
+    ActsAsTenant.current_tenant = nil
+  end
+
+  test "orders are scoped to current tenant" do
+    order = Order.create!(reference: "ORD-001", user: users(:alice))
+    assert_equal @org, order.organization
+  end
+end
+```
+
+### Schema-Based Tenancy (Stronger Isolation)
+
+```ruby
+# Each tenant gets their own PostgreSQL schema
+# Gem: apartment or acts_as_tenant with schema support
+
+# With apartment gem (simpler):
+# Gemfile: gem "ros-apartment", require: "apartment"
+
+# config/initializers/apartment.rb
+Apartment.configure do |config|
+  config.excluded_models = %w[Organization User] # Shared tables
+  config.tenant_names = -> { Organization.pluck(:subdomain) }
+end
+
+# Switching schemas
+Apartment::Tenant.switch("acme") do
+  # All queries hit the "acme" schema
+  Order.all  # => SELECT * FROM acme.orders
+end
+
+# Request middleware sets tenant from subdomain
+class ApplicationController < ActionController::Base
+  before_action :set_tenant
+
+  private
+
+  def set_tenant
+    subdomain = request.subdomain
+    organization = Organization.find_by!(subdomain: subdomain)
+    Apartment::Tenant.switch!(organization.subdomain)
+  end
+end
+```
+
+## Decision Matrix
+
+| Factor | Row-Based | Schema-Based |
+|---|---|---|
+| Setup complexity | Low | Medium-High |
+| Query performance | Good with indexes | Slightly better (smaller tables) |
+| Data isolation | Application-enforced | Database-enforced |
+| Cross-tenant queries | Easy (remove scope) | Hard (must switch schemas) |
+| Tenant count | Unlimited | <1000 (each schema has overhead) |
+| Migrations | Run once | Run per schema |
+| Backups | One database | Per-schema or full DB |
+
+**Recommendation:** Start with row-based + `acts_as_tenant`. It's simpler, handles 95% of use cases, and you can migrate to schema-based later if you need stronger isolation.
+
+## When To Apply
+
+- **SaaS applications** where multiple companies share one deployment.
+- **Any app with an Organization/Account/Company model** that owns other data.
+- **Rubyn itself** — the API server uses row-based tenancy with organization_id on projects, interactions, and credit_ledger.
+
+## When NOT To Apply
+
+- **Single-tenant apps.** If there's only one organization, skip the complexity.
+- **B2C apps without organizations.** Users owning their own data is just `user_id` scoping, not multitenancy.
+- **Don't add tenancy "just in case."** Add it when the second tenant appears, not before.
+
+## Critical Safety Rules
+
+1. **Never use `default_scope` for tenancy manually.** Use `acts_as_tenant` which handles it safely, or use explicit scoping. Hand-rolled default scopes are the #1 source of data leaks.
+2. **Always scope `find` calls.** `Order.find(params[:id])` without tenant scoping lets any user access any order by guessing IDs.
+3. **Background jobs must set the tenant.** Jobs run outside the request cycle. Pass `organization_id` to every job and set the tenant in `perform`.
+4. **Console access defaults to no tenant.** `rails console` has no request context. Use `ActsAsTenant.with_tenant(org) { ... }` explicitly.

data/skills/rails/n_plus_one.md

@@ -0,0 +1,151 @@
+# Rails: N+1 Query Prevention
+
+## Pattern
+
+Always preload associated records before iterating over a collection that accesses those associations. Use `includes` for most cases, `preload` when you need to force separate queries, and `eager_load` when you need to filter or sort by the association.
+
+```ruby
+# CORRECT: Preload associations before iteration
+class OrdersController < ApplicationController
+  def index
+    @orders = current_user.orders
+                          .includes(:line_items, :shipping_address, line_items: :product)
+                          .order(created_at: :desc)
+                          .page(params[:page])
+  end
+end
+```
+
+```erb
+<%# This now executes 3-4 queries total, not 1 + N + N + N %>
+<% @orders.each do |order| %>
+  <p><%= order.shipping_address.city %></p>
+  <% order.line_items.each do |item| %>
+    <p><%= item.product.name %> x <%= item.quantity %></p>
+  <% end %>
+<% end %>
+```
+
+The three preloading methods and when to use each:
+
+```ruby
+# includes: Rails picks the strategy (usually 2 queries, switches to LEFT JOIN if you filter)
+Order.includes(:line_items).where(line_items: { product_id: 5 })
+
+# preload: Always separate queries. Use when includes tries a JOIN and you want separate queries.
+Order.preload(:line_items).order(created_at: :desc)
+
+# eager_load: Always LEFT OUTER JOIN. Use when you need to WHERE or ORDER BY the association.
+Order.eager_load(:line_items).where("line_items.quantity > ?", 5)
+```
+
+Enable `strict_loading` on models or associations to catch N+1 queries during development:
+
+```ruby
+# On a model — raises if any lazy-loaded association is accessed
+class Order < ApplicationRecord
+  self.strict_loading_by_default = true # Rails 7+
+
+  has_many :line_items
+end
+
+# On a specific query
+orders = Order.strict_loading.all
+orders.first.line_items # => raises ActiveRecord::StrictLoadingViolationError
+
+# On a specific association
+class Order < ApplicationRecord
+  has_many :line_items, strict_loading: true
+end
+```
+
+## Why This Is Good
+
+- **Predictable query count.** With `includes`, a page listing 25 orders with line items and products executes 3-4 queries regardless of how many records exist. Without it, you execute 1 + 25 + 25 + 25 = 76 queries.
+- **Scales linearly.** The query count depends on the number of associations, not the number of records. 25 orders or 2,500 orders — same number of queries.
+- **`strict_loading` catches mistakes early.** Lazy-loaded associations silently work in development but crush production databases. Strict loading turns silent performance bugs into loud development errors.
+- **No code change needed in views/serializers.** The fix is in the query, not in the template. The view code stays the same — it just runs faster.
+
+## Anti-Pattern
+
+Loading a collection and letting Rails lazy-load associations on each iteration:
+
+```ruby
+class OrdersController < ApplicationController
+  def index
+    @orders = current_user.orders.order(created_at: :desc).page(params[:page])
+  end
+end
+```
+
+```erb
+<%# This triggers N+1 queries: 1 for orders, then 1 per order for each association %>
+<% @orders.each do |order| %>
+  <p><%= order.user.name %></p>           <%# N queries %>
+  <p><%= order.shipping_address.city %></p> <%# N queries %>
+  <% order.line_items.each do |item| %>     <%# N queries %>
+    <p><%= item.product.name %></p>         <%# N * M queries %>
+  <% end %>
+<% end %>
+```
+
+## Why This Is Bad
+
+- **Query count explodes.** 25 orders × 4 associations = 101 queries for one page load. With nested associations (line_items → product), it's even worse.
+- **Invisible in development.** With 5 seed records, 21 queries feel instant. In production with 50 records per page, the same code makes 201 queries and takes 3 seconds.
+- **Database connection saturation.** Each N+1 query is a round trip to the database. At scale, this saturates the connection pool and causes request queuing for other users.
+- **Log noise.** Your development log fills with repetitive SELECT statements, burying actual issues.
+
+## When To Apply
+
+- **Every time you iterate over a collection and access an association.** This is not optional. Any `@records.each` that touches an association needs preloading.
+- **In serializers and API responses.** JSON serialization that includes associated data triggers the same N+1 if not preloaded.
+- **In background jobs.** Jobs that process batches of records with associations need preloading too — they just waste database time silently instead of slowing a web response.
+- **In mailer views.** Mailers often render templates with associated data. Preload before passing records to the mailer.
+
+## When NOT To Apply
+
+- **Single record lookups.** `Order.find(params[:id])` followed by `@order.line_items` is two queries. That's fine — it's not N+1, it's 1+1.
+- **When you only need IDs.** Use `@order.line_item_ids` which uses a single pluck query. No need to preload full records.
+- **Counter caches.** If you only need `@order.line_items.count`, add a `counter_cache: true` to the association instead of preloading.
+
+## Edge Cases
+
+**You're not sure which associations the view will access:**
+Use the `bullet` gem in development. It detects N+1 queries at runtime and tells you exactly which `includes` to add.
+
+```ruby
+# Gemfile
+group :development do
+  gem 'bullet'
+end
+
+# config/environments/development.rb
+config.after_initialize do
+  Bullet.enable = true
+  Bullet.alert = true
+  Bullet.rails_logger = true
+end
+```
+
+**The association has a scope or condition:**
+`includes` works with scoped associations. Define the scope on the association, not inline.
+
+```ruby
+# Model
+has_many :active_line_items, -> { where(cancelled: false) }, class_name: "LineItem"
+
+# Controller
+Order.includes(:active_line_items)
+```
+
+**You preloaded but some records don't have the association:**
+That's fine. `includes` handles empty associations gracefully — it just returns an empty collection. No error, no extra query.
+
+**Deeply nested associations:**
+Pass a hash to `includes` for nested preloading. Each level adds one query, not one query per record.
+
+```ruby
+Order.includes(line_items: { product: :category })
+# 4 queries: orders, line_items, products, categories
+```

data/skills/rails/presenters.md

@@ -0,0 +1,244 @@
+# Rails: Presenters / View Objects
+
+## Pattern
+
+When display logic accumulates in views, helpers, or models, extract it into a presenter — a plain Ruby object that wraps a model and adds formatting, display logic, and view-specific computed values. The model stays focused on data; the presenter handles how data is shown.
+
+```ruby
+# app/presenters/order_presenter.rb
+class OrderPresenter < SimpleDelegator
+  def formatted_total
+    "$#{format('%.2f', total / 100.0)}"
+  end
+
+  def formatted_date
+    created_at.strftime("%B %d, %Y")
+  end
+
+  def status_badge
+    color = case status
+            when "pending" then "yellow"
+            when "confirmed" then "blue"
+            when "shipped" then "indigo"
+            when "delivered" then "green"
+            when "cancelled" then "red"
+            else "gray"
+            end
+    { text: status.titleize, color: color }
+  end
+
+  def shipping_estimate
+    return "Delivered" if delivered?
+    return "Cancelled" if cancelled?
+    return "Ships within 24 hours" if confirmed?
+    return "Processing" if pending?
+    "Unknown"
+  end
+
+  def credit_card_display
+    return "No card on file" unless user.default_payment_method
+    "•••• #{user.default_payment_method.last_four}"
+  end
+
+  def line_item_count
+    "#{line_items.count} #{'item'.pluralize(line_items.count)}"
+  end
+
+  def can_cancel?
+    pending? || confirmed?
+  end
+
+  def can_edit?
+    pending?
+  end
+end
+```
+
+```ruby
+# Controller — wrap the model
+class OrdersController < ApplicationController
+  def show
+    order = current_user.orders.includes(:line_items, :user).find(params[:id])
+    @order = OrderPresenter.new(order)
+  end
+
+  def index
+    orders = current_user.orders.recent.includes(:line_items)
+    @orders = orders.map { |o| OrderPresenter.new(o) }
+  end
+end
+```
+
+```erb
+<%# View — uses presenter methods, no logic in the template %>
+<h1>Order <%= @order.reference %></h1>
+<p>Placed: <%= @order.formatted_date %></p>
+<p>Total: <%= @order.formatted_total %></p>
+<p><%= @order.line_item_count %></p>
+
+<span class="badge bg-<%= @order.status_badge[:color] %>">
+  <%= @order.status_badge[:text] %>
+</span>
+
+<p><%= @order.shipping_estimate %></p>
+<p>Payment: <%= @order.credit_card_display %></p>
+
+<% if @order.can_cancel? %>
+  <%= button_to "Cancel Order", order_cancellation_path(@order), method: :post %>
+<% end %>
+```
+
+### SimpleDelegator Explained
+
+```ruby
+# SimpleDelegator forwards ALL method calls to the wrapped object
+class OrderPresenter < SimpleDelegator
+  # __getobj__ returns the wrapped Order
+  # order.id, order.user, order.status — all work automatically
+  # You only define methods for display-specific behavior
+
+  def formatted_total
+    "$#{format('%.2f', total / 100.0)}"  # `total` delegates to the Order
+  end
+end
+
+presenter = OrderPresenter.new(order)
+presenter.id            # Delegated to order.id
+presenter.user          # Delegated to order.user
+presenter.formatted_total  # Defined on presenter
+presenter.is_a?(Order)  # true — SimpleDelegator preserves type
+```
+
+### Collection Presenter
+
+```ruby
+# app/presenters/order_collection_presenter.rb
+class OrderCollectionPresenter
+  include Enumerable
+
+  def initialize(orders)
+    @orders = orders
+  end
+
+  def each(&block)
+    @orders.map { |o| OrderPresenter.new(o) }.each(&block)
+  end
+
+  def total_revenue
+    "$#{format('%.2f', @orders.sum(:total) / 100.0)}"
+  end
+
+  def status_breakdown
+    @orders.group(:status).count.transform_keys(&:titleize)
+  end
+
+  def empty_message
+    "No orders yet. Your first order will appear here."
+  end
+end
+
+# Controller
+@orders = OrderCollectionPresenter.new(current_user.orders.recent)
+
+# View
+<p>Revenue: <%= @orders.total_revenue %></p>
+<% @orders.each do |order| %>
+  <p><%= order.formatted_total %></p>
+<% end %>
+```
+
+## Why This Is Good
+
+- **Models stay clean.** `Order` doesn't need `formatted_total`, `status_badge`, or `shipping_estimate`. Those are display concerns, not data concerns.
+- **Views stay logic-free.** No `<% if order.status == "pending" || order.status == "confirmed" %>` in templates. Just `<% if @order.can_cancel? %>`.
+- **Testable.** `OrderPresenter.new(build_stubbed(:order, total: 19_99)).formatted_total` — fast, isolated, no views or controllers needed.
+- **Reusable across formats.** The same presenter works in HTML views, JSON serializers, mailer templates, and PDF generators.
+- **`SimpleDelegator` is transparent.** The presenter IS the order for all purposes — it responds to every Order method. No explicit delegation for each attribute.
+
+## Anti-Pattern
+
+Display logic in the model or scattered across helpers:
+
+```ruby
+# BAD: Display logic on the model
+class Order < ApplicationRecord
+  def formatted_total
+    "$#{format('%.2f', total / 100.0)}"
+  end
+
+  def status_color
+    case status
+    when "pending" then "yellow"
+    when "shipped" then "blue"
+    end
+  end
+
+  def display_date
+    created_at.strftime("%B %d, %Y")
+  end
+end
+# The model now knows about dollar signs, colors, and date formatting
+
+# BAD: Logic in helpers (global namespace, hard to find, hard to test)
+module OrdersHelper
+  def order_status_badge(order)
+    color = order.status == "pending" ? "yellow" : "green"
+    content_tag(:span, order.status.titleize, class: "badge bg-#{color}")
+  end
+end
+
+# BAD: Logic in views
+<% if order.total > 200_00 %>
+  <span class="badge bg-gold">VIP Order</span>
+<% end %>
+<% if order.created_at > 30.days.ago %>
+  <span>Recent</span>
+<% end %>
+```
+
+## When To Apply
+
+- **A model has 3+ methods that only exist for display purposes.** `formatted_total`, `display_name`, `status_label` — these are presenter methods.
+- **Views have conditional logic based on model state.** `if order.pending? || order.confirmed?` → extract to `presenter.can_cancel?`.
+- **The same formatting appears in multiple views.** An order's total is formatted in the index, show, email, and PDF. One presenter method, used everywhere.
+- **Helper files are becoming catch-alls.** If `OrdersHelper` has 15 methods, it's a presenter in disguise.
+
+## When NOT To Apply
+
+- **One or two simple formatting methods.** If the model only has `def to_s; name; end`, that's fine on the model. Don't create a presenter for one method.
+- **Rails built-in helpers suffice.** `number_to_currency(order.total)` in a view is fine for a single use. A presenter is for when you're repeating the same formatting logic.
+- **API-only apps.** Use serializers instead of presenters. Serializers control the JSON output; presenters control HTML display. Different tools for different formats.
+
+## Edge Cases
+
+**Presenter + form helpers:**
+`SimpleDelegator` preserves the wrapped object's class, so `form_with model: @order` works even when `@order` is an `OrderPresenter`. Rails form helpers use the underlying model for URL generation and param naming.
+
+**Presenter in serializers (API):**
+Don't use presenters in JSON APIs. Use a dedicated serializer class instead — it controls the exact shape of the JSON output without inheriting display-specific methods.
+
+**Nested presenters:**
+```ruby
+class OrderPresenter < SimpleDelegator
+  def presented_line_items
+    line_items.map { |li| LineItemPresenter.new(li) }
+  end
+end
+```
+
+**Alternative: Plain class instead of SimpleDelegator:**
+```ruby
+class OrderPresenter
+  attr_reader :order
+  delegate :id, :reference, :status, :user, :line_items, :created_at, to: :order
+
+  def initialize(order)
+    @order = order
+  end
+
+  def formatted_total
+    "$#{format('%.2f', order.total / 100.0)}"
+  end
+end
+```
+This is more explicit (you declare exactly which methods delegate) but more verbose. Use `SimpleDelegator` unless you need to restrict the interface.