source_monitor 0.2.0 → 0.3.0

data/.claude/skills/rails-architecture/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: rails-architecture
+description: Guides modern Rails 8 code architecture decisions and patterns. Use when deciding where to put code, choosing between patterns (service objects vs concerns vs query objects), designing feature architecture, refactoring for better organization, or when user mentions architecture, code organization, design patterns, or layered design.
+allowed-tools: Read, Glob, Grep
+---
+
+# Modern Rails 8 Architecture Patterns
+
+## Project Conventions
+- **Testing:** Minitest + fixtures (NEVER RSpec or FactoryBot)
+- **Components:** ViewComponents for reusable UI (partials OK for simple one-offs)
+- **Authorization:** Pundit policies (deny by default)
+- **Jobs:** Solid Queue, shallow jobs, `_later`/`_now` naming
+- **Frontend:** Hotwire (Turbo + Stimulus) + Tailwind CSS
+- **State:** State-as-records for business state (booleans only for technical flags)
+- **Architecture:** Rich models first, service objects for multi-model orchestration
+- **Routing:** Everything-is-CRUD (new resource over new action)
+- **Quality:** RuboCop (omakase) + Brakeman
+
+## Architecture Decision Tree
+
+```
+Where should this code go?
+│
+├─ Is it data validation, associations, or simple business logic?
+│   └─ → Model (rich models first!)
+│
+├─ Is it shared behavior across models?
+│   └─ → Concern
+│
+├─ Is it business state tracking (who/when/why)?
+│   └─ → State Record (see: state-records pattern)
+│
+├─ Does it orchestrate 3+ models or call external APIs?
+│   └─ → Service Object (with Result pattern)
+│
+├─ Is it a complex database query (3+ joins, aggregations)?
+│   └─ → Query Object
+│
+├─ Is it view/display formatting?
+│   └─ → Presenter (SimpleDelegator)
+│
+├─ Is it authorization logic?
+│   └─ → Pundit Policy
+│
+├─ Is it reusable UI with logic?
+│   └─ → ViewComponent
+│
+├─ Is it async/background work?
+│   └─ → Shallow Job (Solid Queue)
+│
+├─ Is it a complex form (multi-model, wizard)?
+│   └─ → Form Object
+│
+├─ Is it a transactional email?
+│   └─ → Mailer
+│
+└─ Is it HTTP request/response handling only?
+    └─ → Controller (keep it thin!)
+```
+
+## Hybrid Philosophy: Models First, Services When Needed
+
+### The Rule of Three
+- **1 model affected** → Keep logic in the model
+- **2 models affected** → Consider a concern or model method
+- **3+ models affected** → Extract to a service object
+
+### Rich Models (Default)
+Models handle validations, associations, scopes, simple derived attributes, and single-model business logic. This is where most code belongs.
+
+```ruby
+class Order < ApplicationRecord
+  include Closeable  # State-as-records concern
+
+  belongs_to :user
+  has_many :line_items, dependent: :destroy
+
+  validates :total_cents, presence: true, numericality: { greater_than: 0 }
+
+  scope :recent, -> { order(created_at: :desc) }
+  scope :pending, -> { where.missing(:closure) }
+
+  def add_item(product, quantity: 1)
+    line_items.create!(product: product, quantity: quantity, price_cents: product.price_cents)
+    recalculate_total!
+  end
+
+  private
+
+  def recalculate_total!
+    update!(total_cents: line_items.sum("price_cents * quantity"))
+  end
+end
+```
+
+### Service Objects (When Justified)
+Use only when logic spans 3+ models, calls external APIs, or orchestrates complex workflows.
+
+```ruby
+module Orders
+  class CheckoutService
+    def call(user:, cart:, payment_method_id:)
+      order = nil
+
+      ActiveRecord::Base.transaction do
+        order = user.orders.create!(total_cents: cart.total_cents)
+        cart.items.each { |item| order.add_item(item.product, quantity: item.quantity) }
+        Inventory::ReserveService.new.call(order: order)
+      end
+
+      Payments::ChargeService.new.call(order: order, payment_method_id: payment_method_id)
+      OrderMailer.confirmation(order).deliver_later
+      Result.new(success: true, data: order)
+    rescue ActiveRecord::RecordInvalid => e
+      Result.new(success: false, error: e.message)
+    end
+  end
+end
+```
+
+## Everything-is-CRUD Routing
+
+Prefer creating a new resource over adding custom actions:
+
+```ruby
+# GOOD: New resource for publishing
+resources :posts do
+  resource :publication, only: [:create, :destroy]
+end
+# POST /posts/:post_id/publication → Publications#create
+# DELETE /posts/:post_id/publication → Publications#destroy
+
+# BAD: Custom action
+resources :posts do
+  member do
+    post :publish
+    post :unpublish
+  end
+end
+```
+
+## Layer Responsibilities
+
+| Layer | Responsibility | Should NOT contain |
+|-------|---------------|-------------------|
+| **Controller** | HTTP, params, authorize, render | Business logic, queries |
+| **Model** | Data, validations, relations, scopes | Display logic, HTTP |
+| **Concern** | Shared model/controller behavior | Unrelated cross-cutting logic |
+| **Service** | Multi-model orchestration, external APIs | HTTP, display logic |
+| **Query** | Complex database queries, reports | Business logic |
+| **Presenter** | View formatting, badges | Business logic, queries |
+| **Policy** | Authorization rules | Business logic |
+| **Component** | Reusable UI encapsulation | Business logic |
+| **Job** | Async delegation (shallow!) | Business logic |
+
+## Project Directory Structure
+
+```
+app/
+├── channels/            # Action Cable channels
+├── components/          # ViewComponents (UI + logic)
+├── controllers/
+│   └── concerns/        # Shared controller behavior
+├── forms/               # Form objects
+├── jobs/                # Background jobs (Solid Queue)
+├── mailers/             # Action Mailer classes
+├── models/
+│   └── concerns/        # Shared model behavior
+├── policies/            # Pundit authorization
+├── presenters/          # View formatting
+├── queries/             # Complex queries
+├── services/            # Business logic (use sparingly)
+│   └── result.rb        # Shared Result class
+└── views/
+    └── components/      # ViewComponent templates
+```
+
+## When NOT to Abstract
+
+| Situation | Keep It Simple | Don't Create |
+|-----------|----------------|--------------|
+| Simple CRUD (< 10 lines) | Keep in controller | Service object |
+| Used only once | Inline the code | Abstraction |
+| Simple query with 1-2 conditions | Model scope | Query object |
+| Basic text formatting | Helper method | Presenter |
+| Single model form | `form_with model:` | Form object |
+| Simple partial without logic | Partial | ViewComponent |
+
+## When TO Abstract
+
+| Signal | Action |
+|--------|--------|
+| Same code in 3+ places | Extract to concern/service |
+| Controller action > 15 lines | Extract to service |
+| Model > 300 lines | Extract concerns |
+| Complex conditionals | Extract to policy/service |
+| Query joins 3+ tables | Extract to query object |
+| Form spans multiple models | Extract to form object |
+| Partial has > 5 lines of logic | Use ViewComponent |
+
+## Result Object Pattern
+
+All services return a consistent Result:
+
+```ruby
+# app/services/result.rb
+class Result
+  attr_reader :data, :error, :code
+
+  def initialize(success:, data: nil, error: nil, code: nil)
+    @success = success
+    @data = data
+    @error = error
+    @code = code
+  end
+
+  def success? = @success
+  def failure? = !@success
+
+  def self.success(data = nil) = new(success: true, data: data)
+  def self.failure(error, code: nil) = new(success: false, error: error, code: code)
+end
+```
+
+## Testing Strategy by Layer
+
+| Layer | Test Type | Location | Focus |
+|-------|-----------|----------|-------|
+| Model | Unit | `test/models/` | Validations, scopes, methods |
+| Service | Unit | `test/services/` | Business logic, edge cases |
+| Query | Unit | `test/queries/` | Query results, correctness |
+| Presenter | Unit | `test/presenters/` | Formatting, HTML output |
+| Controller | Integration | `test/controllers/` | HTTP flow, authorization |
+| Component | Component | `test/components/` | Rendering, variants |
+| Policy | Unit | `test/policies/` | Authorization rules |
+| System | E2E | `test/system/` | Critical user paths |
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| God Model | Model > 500 lines | Extract concerns |
+| Fat Controller | Logic in controllers | Move to models/services |
+| Premature Service | Service for 3 lines | Keep in model |
+| Callback Hell | Complex model callbacks | Use services for orchestration |
+| Boolean State | `approved: true` | State-as-records |
+| N+1 Queries | Unoptimized queries | Use `.includes()` |
+
+## References
+
+- See [layer-interactions.md](reference/layer-interactions.md) for layer communication patterns
+- See [service-patterns.md](reference/service-patterns.md) for service object patterns
+- See [query-patterns.md](reference/query-patterns.md) for query object patterns
+- See [error-handling.md](reference/error-handling.md) for error handling strategies
+- See [testing-strategy.md](reference/testing-strategy.md) for comprehensive testing
+- See [multi-tenancy.md](reference/multi-tenancy.md) for multi-tenant patterns
+- See [event-tracking.md](reference/event-tracking.md) for domain event patterns
+- See [state-records.md](reference/state-records.md) for state-as-records patterns

data/.claude/skills/rails-architecture/reference/error-handling.md

@@ -0,0 +1,333 @@
+# Error Handling Strategies
+
+## Result Object Pattern (Preferred)
+
+Services return Result objects instead of raising exceptions:
+
+```ruby
+# app/services/result.rb
+class Result
+  attr_reader :data, :error, :code
+
+  def initialize(success:, data: nil, error: nil, code: nil)
+    @success = success
+    @data = data
+    @error = error
+    @code = code
+  end
+
+  def success? = @success
+  def failure? = !@success
+
+  # Pattern matching support (Ruby 3+)
+  def deconstruct_keys(keys)
+    { success: @success, data: @data, error: @error, code: @code }
+  end
+end
+```
+
+## Error Code System
+
+### Define Error Codes
+
+```ruby
+module Orders
+  class CreateService
+    ERROR_CODES = {
+      empty_cart: :empty_cart,
+      out_of_stock: :out_of_stock,
+      payment_declined: :payment_declined,
+      invalid_coupon: :invalid_coupon,
+      validation_failed: :validation_failed
+    }.freeze
+
+    MESSAGES = {
+      empty_cart: "Your cart is empty",
+      out_of_stock: "One or more items are out of stock",
+      payment_declined: "Your payment was declined",
+      invalid_coupon: "The coupon code is invalid",
+      validation_failed: "Please check your order details"
+    }.freeze
+  end
+end
+```
+
+### Return Typed Errors
+
+```ruby
+def call(params)
+  return error(:empty_cart) if params[:items].empty?
+  return error(:out_of_stock) unless inventory_available?(params[:items])
+
+  order = create_order(params)
+  success(order)
+rescue PaymentGateway::Declined
+  error(:payment_declined)
+rescue ActiveRecord::RecordInvalid => e
+  error(:validation_failed, e.message)
+end
+
+private
+
+def error(code, details = nil)
+  message = self.class::MESSAGES[code]
+  message = "#{message}: #{details}" if details
+  Result.new(success: false, error: message, code: code)
+end
+```
+
+## Controller Error Handling
+
+### Handle by Error Code
+
+```ruby
+class OrdersController < ApplicationController
+  def create
+    result = Orders::CreateService.new.call(order_params)
+
+    if result.success?
+      redirect_to result.data, notice: t(".success")
+    else
+      handle_error(result)
+    end
+  end
+
+  private
+
+  def handle_error(result)
+    case result.code
+    when :empty_cart
+      redirect_to cart_path, alert: result.error
+    when :out_of_stock
+      flash.now[:alert] = result.error
+      @out_of_stock = true
+      render :new, status: :unprocessable_entity
+    when :payment_declined
+      redirect_to payment_path, alert: result.error
+    else
+      flash.now[:alert] = result.error
+      render :new, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+### Pattern Matching (Ruby 3+)
+
+```ruby
+def create
+  case Orders::CreateService.new.call(order_params)
+  in { success: true, data: order }
+    redirect_to order, notice: t(".success")
+  in { code: :empty_cart }
+    redirect_to cart_path, alert: t(".empty_cart")
+  in { code: :payment_declined, error: message }
+    redirect_to payment_path, alert: message
+  in { error: message }
+    flash.now[:alert] = message
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+## API Error Responses
+
+### Consistent Error Format
+
+```ruby
+# app/controllers/api/base_controller.rb
+module Api
+  class BaseController < ApplicationController
+    private
+
+    def render_error(result, status: :unprocessable_entity)
+      render json: {
+        error: {
+          code: result.code,
+          message: result.error,
+          details: result.data # Optional additional context
+        }
+      }, status: status
+    end
+
+    def render_success(data, status: :ok)
+      render json: { data: data }, status: status
+    end
+  end
+end
+```
+
+### HTTP Status Mapping
+
+```ruby
+ERROR_STATUS_MAP = {
+  not_found: :not_found,
+  unauthorized: :unauthorized,
+  forbidden: :forbidden,
+  validation_failed: :unprocessable_entity,
+  conflict: :conflict,
+  rate_limited: :too_many_requests
+}.freeze
+
+def render_service_result(result)
+  if result.success?
+    render_success(result.data)
+  else
+    status = ERROR_STATUS_MAP.fetch(result.code, :unprocessable_entity)
+    render_error(result, status: status)
+  end
+end
+```
+
+## Exception Handling Layers
+
+### Service Layer (Catch and Wrap)
+
+```ruby
+class ExternalApiService
+  def call(params)
+    response = client.request(params)
+    success(response.data)
+  rescue Faraday::TimeoutError
+    error(:timeout, "External service timed out")
+  rescue Faraday::ConnectionFailed
+    error(:connection_failed, "Could not connect to service")
+  rescue JSON::ParserError
+    error(:invalid_response, "Invalid response from service")
+  end
+end
+```
+
+### Controller Layer (Rescue From)
+
+```ruby
+class ApplicationController < ActionController::Base
+  rescue_from ActiveRecord::RecordNotFound, with: :not_found
+  rescue_from Pundit::NotAuthorizedError, with: :forbidden
+
+  private
+
+  def not_found
+    respond_to do |format|
+      format.html { render "errors/not_found", status: :not_found }
+      format.json { render json: { error: "Not found" }, status: :not_found }
+    end
+  end
+
+  def forbidden
+    respond_to do |format|
+      format.html { redirect_to root_path, alert: t("errors.forbidden") }
+      format.json { render json: { error: "Forbidden" }, status: :forbidden }
+    end
+  end
+end
+```
+
+### Global Error Handler
+
+```ruby
+# config/initializers/error_handler.rb
+Rails.application.config.exceptions_app = ->(env) {
+  ErrorsController.action(:show).call(env)
+}
+
+# app/controllers/errors_controller.rb
+class ErrorsController < ApplicationController
+  skip_before_action :authenticate_user!
+
+  def show
+    @status = request.env["PATH_INFO"].delete("/").to_i
+    render status: @status
+  end
+end
+```
+
+## Validation Errors
+
+### Model Validations to Result
+
+```ruby
+def call(params)
+  record = Model.new(params)
+
+  if record.save
+    success(record)
+  else
+    validation_error(record)
+  end
+end
+
+def validation_error(record)
+  Result.new(
+    success: false,
+    error: record.errors.full_messages.join(", "),
+    code: :validation_failed,
+    data: record.errors.to_hash
+  )
+end
+```
+
+### Display Validation Errors
+
+```ruby
+# In controller
+if result.failure? && result.code == :validation_failed
+  @errors = result.data # Hash of field => [messages]
+end
+
+# In view
+<% if @errors&.dig(:email) %>
+  <p class="text-red-500"><%= @errors[:email].join(", ") %></p>
+<% end %>
+```
+
+## Logging Errors
+
+```ruby
+class ApplicationService
+  private
+
+  def error(code, message = nil, exception: nil)
+    log_error(code, message, exception)
+    Result.new(success: false, error: message || default_message(code), code: code)
+  end
+
+  def log_error(code, message, exception)
+    Rails.logger.error({
+      service: self.class.name,
+      error_code: code,
+      message: message,
+      exception: exception&.class&.name,
+      backtrace: exception&.backtrace&.first(5)
+    }.to_json)
+  end
+end
+```
+
+## Error Tracking Integration
+
+```ruby
+# With Sentry/Rollbar
+def error(code, message = nil, exception: nil)
+  if exception && should_report?(code)
+    Sentry.capture_exception(exception, extra: { code: code, message: message })
+  end
+
+  Result.new(success: false, error: message, code: code)
+end
+
+def should_report?(code)
+  # Don't report expected errors
+  ![:validation_failed, :not_found, :unauthorized].include?(code)
+end
+```
+
+## Checklist
+
+- [ ] Services return Result objects
+- [ ] Error codes are typed symbols
+- [ ] Controllers handle errors by code
+- [ ] API responses have consistent format
+- [ ] Unexpected errors logged with context
+- [ ] Sensitive data not exposed in errors
+- [ ] User-facing messages use I18n