examples/rails-app-CLAUDE.md
Rama main · réplica de lectura del repositorio original.
# 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
```ruby
# 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
```ruby
# 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
```ruby
# 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
```ruby
# 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
```ruby
# 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)
```ruby
# 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
```bash
# 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
```bash
# 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
```bash
# 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