everything-claude-code/examples/rails-app-CLAUDE.md

Rails Application: Project CLAUDE.md

Real-world example for a Rails 8 monolithic web application with Hotwire, ViewComponent, and the Solid stack. Copy this to your project root and customize for your service.

Project Overview

Stack: Ruby 3.3+, Rails 8.x, PostgreSQL 16, SolidQueue, SolidCache, SolidCable, Hotwire (Turbo + Stimulus), ViewComponent, Tailwind CSS, RSpec, FactoryBot, Capybara, Kamal

Architecture: Full-stack Rails monolith. Server-rendered with Hotwire for interactivity rather than an SPA. Database-backed Solid stack replaces Redis for background jobs, cache, and WebSockets. ViewComponent for testable view logic. Service objects for business operations. Deployed via Kamal to self-managed Linux hosts.

Critical Rules

Ruby Conventions

• # frozen_string_literal: true at the top of every Ruby file
• Modern hash syntax (key:) over hash rockets (:key =>) unless the key is not a symbol
• Double quotes by default; single quotes only when the string contains a double quote
• Two-space indentation, no tabs
• Use bin/ wrappers (bin/rails, bin/rspec, bin/rubocop) instead of bundle exec directly
• RuboCop is authoritative; either fix the code or update the config in a PR that explains why
• No puts, pp, debugger, or binding.pry in committed code; use Rails.logger.<level> for logging

Database

• Eager load associations by default to prevent N+1 queries
• Avoid default_scope; use named scopes that callers opt into
• Use .includes, .preload, or .eager_load depending on need to avoid N+1 queries
• Counter caches on any has_many where the count is displayed in lists
• Callbacks for data normalization only (before_validation :normalize_email); anything with side effects belongs in a service
• Migrations are reversible by default; document any one-way migration explicitly

# BAD: N+1 query
posts = Post.published
posts.each { |post| post.author.name }  # one query per post

# GOOD: Single query with eager load
posts = Post.published.includes(:author)
posts.each { |post| post.author.name }

Authentication and Authorization

• Authentication via the Rails 8 generated authentication system (bin/rails generate authentication) or Devise for more complex flows
• Session-based auth for full-stack pages, token-based for any embedded API endpoints
• Authorization via Pundit; every controller action has an authorize call or an explicit skip_authorization with a documented reason
• Strong parameters always; never params.permit!
• CSRF protection enabled by default; only disable per action with explicit justification

Background Jobs

• SolidQueue is the default in Rails 8; Sidekiq remains acceptable for high-throughput cases
• Pass IDs to jobs, not records; this avoids ActiveJob::DeserializationError when records are deleted between enqueue and execute
• perform methods must be idempotent; assume they will run more than once
• Declare retry behavior explicitly with retry_on and discard_on
• Name jobs by action (SendInvoiceJob, ExportAccountingJob), not by noun
• For jobs touching external systems, pair the local idempotency check with an API-level idempotency token, and consider row-level locking (with_lock) for high-concurrency scenarios

Views and Hotwire

• Hotwire (Turbo + Stimulus) before reaching for a JavaScript framework
• ViewComponent for any view logic that has conditionals, accepts multiple parameters, or appears in more than three places
• ERB partials for simple presentation; no business logic in views
• Tailwind utility classes for styling; avoid custom CSS unless utilities cannot express the design
• Turbo Frames for partial page updates; Turbo Streams for server-driven multi-update responses

Real-time and ActionCable

• SolidCable is the Rails 8 default pub/sub backend; no Redis required
• Authenticate connections in ApplicationCable::Connection#connect; never trust the client to identify itself
• Authorize subscriptions in each channel's subscribed method before calling stream_from
• Prefer Turbo Stream broadcasts (broadcasts_to, broadcast_replace_later_to) for view updates over hand-written channels
• Treat ActionCable broadcasts as public; never include sensitive data the subscriber should not see

Deployment Setup

Production deploys via Kamal:

• config/deploy.yml is the source of truth for servers, registry, and environment config
• .kamal/secrets references secrets from the host environment; the file is committed, the secrets are not
• Production hosts are Docker-capable machines (typically Linux) with SSH access from the deploying machine
• Migrations run as part of the deploy lifecycle; no manual migration step

Error Handling

• Service objects return Result objects on success and failure; do not raise across service boundaries
• Rescue expected errors inside the service and capture them on the result
• Custom domain errors live in a dedicated location (app/errors/ or lib/errors/, autoloaded as configured); one error class per failure mode
• Never expose internal error details to clients; user-facing errors come from explicit messages, not exception strings
• Use rescue_from sparingly in controllers; let the default Rails error handling do its job

Code Style

• No emojis in code or comments
• Max line length 120 characters (RuboCop default)
• Classes PascalCase, methods and variables snake_case, constants UPPER_SNAKE_CASE
• Controllers stay under 80 lines; models stay under 200 lines; anything longer needs extraction
• Service objects under app/services/, namespaced by domain (Invoices::Create, not InvoiceCreator)

File Structure

app/
  models/                # ActiveRecord models. Persistence and domain logic close to the data.
  controllers/           # HTTP request handling. Thin orchestration only.
  views/                 # ERB templates. No business logic.
  components/            # ViewComponent classes. View logic that needs tests.
  services/              # Service objects under domain namespaces.
  forms/                 # Form objects for multi-model forms.
  queries/               # Query objects for reusable, composable ActiveRecord queries.
  jobs/                  # Background jobs. SolidQueue or Sidekiq.
  mailers/               # ActionMailer classes.
  channels/              # ActionCable channels. Real-time WebSocket connections.
  policies/              # Pundit authorization policies, one per resource.
  errors/                # Custom domain error classes.
config/
  routes.rb
  database.yml
  credentials/
    production.yml.enc   # Encrypted production credentials.
  deploy.yml             # Kamal deploy configuration.
db/
  migrate/               # Migrations, committed and reversible.
  seeds.rb
spec/
  models/
  services/
  components/
  system/                # Capybara system tests.
  factories/             # FactoryBot definitions.
  support/               # Shared spec helpers.

Key Patterns

Service Object Pattern

# app/services/invoices/create.rb
module Invoices
  class Create
    Result = Data.define(:success?, :invoice, :errors)

    def self.call(...) = new(...).call

    def initialize(params:, user:)
      @params = params
      @user = user
    end

    def call
      invoice = build_invoice

      ApplicationRecord.transaction do
        invoice.save!
      end

      begin
        send_notifications(invoice)
      rescue StandardError => e
        Rails.logger.error("Notification dispatch failed for invoice #{invoice.id}: #{e.message}")
      end

      Result.new(success?: true, invoice: invoice, errors: nil)
    rescue ActiveRecord::RecordInvalid => e
      Result.new(success?: false, invoice: e.record, errors: e.record.errors)
    end

    private

    attr_reader :params, :user

    def build_invoice
      invoice = user.invoices.new(params.except(:line_items))
      invoice.line_items.build(params[:line_items])
      invoice.total = invoice.line_items.sum(&:amount)
      invoice
    end

    def send_notifications(invoice)
      InvoiceMailer.created(invoice).deliver_later
      ExportAccountingJob.perform_later(invoice.id)
    end
  end
end

Skinny Controller Pattern

# app/controllers/invoices_controller.rb
class InvoicesController < ApplicationController
  before_action :require_authentication  # Rails 8 generator default; use authenticate_user! with Devise

  def create
    authorize Invoice

    result = Invoices::Create.call(params: invoice_params, user: current_user)

    if result.success?
      redirect_to result.invoice, notice: "Invoice created"
    else
      @invoice = result.invoice
      render :new, status: :unprocessable_entity
    end
  end

  private

  def invoice_params
    params.require(:invoice).permit(:customer_id, line_items: %i[description amount])
  end
end

Query Object Pattern

# app/queries/invoices/overdue.rb
module Invoices
  class Overdue
    def self.call(...) = new(...).call

    def initialize(scope: Invoice.all, as_of: Time.current)
      @scope = scope
      @as_of = as_of
    end

    def call
      scope
        .where(status: :sent)
        .where(due_date: ..as_of)
        .where.not(id: paid_invoice_ids)
        .includes(:customer, :line_items)
    end

    private

    attr_reader :scope, :as_of

    def paid_invoice_ids
      Payment.where(created_at: ..as_of).pluck(:invoice_id)
    end
  end
end

Background Job Pattern

# app/jobs/export_accounting_job.rb
class ExportAccountingJob < ApplicationJob
  queue_as :exports

  retry_on AccountingApi::TransientError, wait: :polynomially_longer, attempts: 5
  discard_on AccountingApi::PermanentError

  def perform(invoice_id)
    invoice = Invoice.find(invoice_id)
    return if invoice.exported_at.present?  # local idempotency check

    idempotency_key = "invoice-export-#{invoice.id}"
    AccountingApi.export(invoice, idempotency_key: idempotency_key)
    invoice.update!(exported_at: Time.current)
  end
end

Test Pattern (RSpec)

# spec/services/invoices/create_spec.rb
require "rails_helper"

RSpec.describe Invoices::Create do
  let(:user) { create(:user) }
  let(:customer) { create(:customer, user: user) }
  let(:params) do
    {
      customer_id: customer.id,
      line_items: [{ description: "Consulting", amount: 100_000 }]  # $1,000.00 in cents
    }
  end

  describe ".call" do
    it "creates an invoice with the expected total" do
      result = described_class.call(params: params, user: user)

      expect(result).to be_success
      expect(result.invoice).to be_persisted
      expect(result.invoice.total).to eq(100_000)
    end

    it "enqueues a notification email" do
      expect {
        described_class.call(params: params, user: user)
      }.to have_enqueued_mail(InvoiceMailer, :created)
    end

    it "returns errors when validation fails" do
      result = described_class.call(params: params.merge(customer_id: nil), user: user)

      expect(result).not_to be_success
      expect(result.errors[:customer]).to include("must exist")
    end
  end
end

Environment Variables

# Rails
RAILS_ENV=production
RAILS_MASTER_KEY=                  # decrypts config/credentials/production.yml.enc
SECRET_KEY_BASE=                   # auto-generated; never commit

# Database
DATABASE_URL=postgres://user:pass@host:5432/myapp_production

# SolidQueue, SolidCache, SolidCable
# These default to the primary database; configure a separate one for higher load:
QUEUE_DATABASE_URL=postgres://user:pass@host:5432/myapp_queue
CACHE_DATABASE_URL=postgres://user:pass@host:5432/myapp_cache

# Kamal deploy
KAMAL_REGISTRY_PASSWORD=
KAMAL_DEPLOY_USER=

# Application secrets (also storable in Rails encrypted credentials)
STRIPE_API_KEY=
SENTRY_DSN=

For most secrets, prefer Rails encrypted credentials (bin/rails credentials:edit -e production) over environment variables. ENV vars are appropriate for infrastructure config that varies per host; credentials are appropriate for application secrets that travel with the codebase.

Testing Strategy

# Run the full suite
bin/rspec

# Run a single file or directory
bin/rspec spec/services/invoices/
bin/rspec spec/services/invoices/create_spec.rb

# Run only the last failures
bin/rspec --only-failures

# Run with random ordering (default) seeded for reproducibility
bin/rspec --seed 12345

# Run system tests
bin/rspec spec/system/

# Coverage report (SimpleCov)
COVERAGE=true bin/rspec

Coverage target is 90% line coverage as a floor, not a goal. Sharp tests with 85% beat exhaustive tests with 100%. System tests use Capybara with the rack_test driver by default and switch to headless Chrome only when JavaScript is required.

ECC Workflow

# Planning
/plan "Add invoice PDF export with line item subtotals"

# Test-first development
/tdd                    # RSpec-based TDD workflow

# Review
/code-review            # General quality check
/security-scan          # Brakeman + dependency audit

# Verification
/verify                 # Lint, type-check, test, security scan in one pass

Git Workflow

• Branch from main, named <type>/<short-description> (e.g., feat/invoice-pdf-export, fix/n-plus-one-on-dashboard)
• Conventional commits style: feat: new features, fix: bug fixes, refactor: code changes
• Pull requests required for changes to main; review according to your team's policy and CI must be green to merge
• Squash on merge; the merged commit message must be coherent and well-formed
• Never force-push to main; force-pushing feature branches is fine
• CI runs RuboCop, Brakeman, RSpec, and bundle audit on every PR