rails-hyperdrive-layered-rails 0.1.0

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/anti-patterns/helpers.md

@@ -0,0 +1,66 @@
+# Helper Anti-Patterns
+
+Helpers doing work that belongs in templates or components.
+
+## HTML Construction in Helpers
+
+**Problem:** Helpers building HTML programmatically instead of providing logic for templates.
+
+```ruby
+# BAD: Helper constructs HTML
+module MessagesHelper
+  def message_tag(message, &)
+    tag.div id: dom_id(message),
+      class: "message #{"message--emoji" if message.plain_text_body.all_emoji?}",
+      data: {
+        controller: "reply",
+        user_id: message.creator_id,
+        message_id: message.id,
+        # ... many more data attributes
+      }, &
+  end
+end
+```
+
+**Issues:**
+- HTML structure hidden in Ruby code, harder to read and modify
+- No template preview, harder to collaborate with designers
+- Logic and markup tightly coupled
+- Testing requires rendering, not unit testable
+- Misses ViewComponent benefits (sidecar assets, previews, slots)
+
+**Signal:** Heavy use of `tag.div`, `tag.button`, `tag.span` or complex `content_tag` chains.
+
+**Fix:** Extract to ViewComponent with template.
+
+```ruby
+# GOOD: ViewComponent with template
+class MessageComponent < ViewComponent::Base
+  def initialize(message:)
+    @message = message
+  end
+
+  def emoji_only?
+    @message.plain_text_body.all_emoji?
+  end
+
+  def stimulus_data
+    {
+      controller: "reply",
+      user_id: @message.creator_id,
+      message_id: @message.id
+    }
+  end
+end
+```
+
+```erb
+<%# app/components/message_component.html.erb %>
+<div id="<%= dom_id(@message) %>"
+     class="message <%= "message--emoji" if emoji_only? %>"
+     data="<%= stimulus_data.to_json %>">
+  <%= content %>
+</div>
+```
+
+**Rule of thumb:** If a helper method has more than 2-3 `tag.*` calls or builds nested HTML structure, extract to ViewComponent.

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/anti-patterns/jobs.md

@@ -0,0 +1,71 @@
+# Job Anti-Patterns
+
+Background-job classes that add boilerplate without value.
+
+## Anemic Jobs
+
+**Problem:** Job classes that just delegate to a single model method.
+
+```ruby
+# BAD: Job is just a wrapper
+class NotifyRecipientsJob < ApplicationJob
+  discard_on ActiveJob::DeserializationError
+
+  def perform(notifiable)
+    notifiable.notify_recipients
+  end
+end
+
+# BAD: Model method just to enqueue job
+class Post < ApplicationRecord
+  def notify_recipients_later
+    NotifyRecipientsJob.perform_later(self)
+  end
+end
+```
+
+**Issues:**
+- Boilerplate job files cluttering `app/jobs`
+- Two places to maintain (job + model method)
+- Job class adds no value beyond async execution
+- Makes the jobs folder noisy, hiding complex jobs that need attention
+
+**Signal:** Job's `perform` method is a single line calling a method on the argument.
+
+**Fix:** Use the [active_job-performs](https://github.com/kaspth/active_job-performs) gem.
+
+```ruby
+# GOOD: Short form (no job options needed)
+class Post < ApplicationRecord
+  performs def notify_recipients
+    # Notification logic
+  end
+end
+
+# Usage
+post.notify_recipients_later
+```
+
+This generates:
+- `Post::NotifyRecipientsJob` automatically
+- `notify_recipients_later` instance method
+- `notify_recipients_later_bulk` class method (Rails 7.1+)
+
+**With options:**
+```ruby
+class Post < ApplicationRecord
+  performs :notify_recipients,
+           queue_as: :notifications,
+           discard_on: ActiveRecord::RecordNotFound
+
+  def notify_recipients
+    # ...
+  end
+end
+```
+
+**When to keep separate job class:**
+- Job has complex logic beyond single method call
+- Job processes multiple records with custom batching
+- Job needs extensive retry/error handling configuration
+- Job is triggered from multiple unrelated models

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/anti-patterns/layer-violations.md

@@ -0,0 +1,176 @@
+# Layer Violations
+
+Cross-layer dependencies that break unidirectional data flow.
+
+## Contents
+
+- Current Attributes in Models
+- Request Objects in Services
+- Notifications in Models
+- Business Logic in Controllers
+
+## Current Attributes in Models
+
+**Problem:** Models depend on presentation-layer context.
+
+```ruby
+# BAD
+class Post < ApplicationRecord
+  def destroy
+    self.deleted_by = Current.user  # Hidden dependency!
+    super
+  end
+end
+```
+
+**Issues:**
+- Background jobs lose Current context (silent bugs)
+- Callbacks can overwrite Current mid-iteration
+- Hidden dependency makes testing harder
+- Violates no-reverse-dependencies rule
+
+**Fix:** Use explicit parameters.
+
+```ruby
+# GOOD
+class Post < ApplicationRecord
+  def destroy_by(user:)
+    self.deleted_by = user
+    destroy
+  end
+end
+```
+
+## Request Objects in Services
+
+**Problem:** Application layer depends on presentation layer.
+
+```ruby
+# BAD
+class HandleEventService
+  param :request
+
+  def call
+    event_type = request.headers["X-Event-Type"]
+    payload = JSON.parse(request.body.read)
+    # ...
+  end
+end
+```
+
+**Fix:** Extract value object in controller, pass to service.
+
+```ruby
+# GOOD
+class GithubCallbacksController < ApplicationController
+  def create
+    event = GithubEvent.from_request(request)
+    HandleEventService.call(event:)
+  end
+end
+
+class HandleEventService
+  param :event  # Value object, not request
+
+  def call
+    # Work with clean domain object
+  end
+end
+```
+
+## Notifications in Models
+
+**Problem:** Model triggers notifications, crossing into application layer.
+
+```ruby
+# BAD
+class License < ApplicationRecord
+  def prolong
+    update!(status: :active, expires_at: 1.year.from_now)
+    LicenseDelivery.with(license: self).purchased.deliver_later
+  end
+end
+```
+
+**Issues:**
+- Domain layer depends on application layer (reverse dependency)
+- Model has side effects beyond state management
+- Harder to test model in isolation
+- Notification may fire unexpectedly from different call sites
+
+**Fix:** Trace the call chain, move notification to existing orchestrator.
+
+```ruby
+# GOOD: Service handles side effects
+class StripeEventManager
+  def handle_invoice_paid(invoice)
+    # ... find license, create payment record ...
+    license.prolong
+    LicenseDelivery.with(license:).purchased.deliver_later
+  end
+end
+
+class License < ApplicationRecord
+  def prolong
+    update!(status: :active, expires_at: 1.year.from_now)
+  end
+end
+```
+
+**Resolution process:**
+1. Find the caller (controller, service, job)
+2. If orchestrator exists → move notification there
+3. If no orchestrator → suggest service/form/controller based on context
+
+## Business Logic in Controllers
+
+**Problem:** Presentation layer doing domain work.
+
+```ruby
+# BAD
+class OrdersController < ApplicationController
+  def create
+    @order = Order.new(order_params)
+    @order.total = @order.items.sum { |i| i.price * i.quantity }
+    @order.total *= 0.9 if @order.customer.vip?
+    @order.total += calculate_shipping(@order)
+
+    if @order.save
+      OrderMailer.confirmation(@order).deliver_later
+      redirect_to @order
+    else
+      render :new
+    end
+  end
+end
+```
+
+**Fix:** Move domain logic to model, orchestration to service if needed.
+
+```ruby
+# GOOD
+class Order < ApplicationRecord
+  before_validation :calculate_total
+
+  private
+
+  def calculate_total
+    self.total = items.sum(&:subtotal)
+    self.total *= 0.9 if customer.vip?
+    self.total += shipping_cost
+  end
+end
+
+class OrdersController < ApplicationController
+  def create
+    @order = Order.new(order_params)
+
+    if @order.save
+      OrderMailer.confirmation(@order).deliver_later
+      redirect_to @order
+    else
+      render :new
+    end
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/anti-patterns/service-objects.md

@@ -0,0 +1,131 @@
+# Service Object Anti-Patterns
+
+Common mistakes when introducing service objects.
+
+## Contents
+
+- Anemic Models
+- Bag of Random Objects
+- Premature Abstraction
+
+## Anemic Models
+
+**Problem:** All logic moved to services, models become data containers.
+
+```ruby
+# BAD - Anemic model
+class Order < ApplicationRecord
+  # Just associations and validations, no behavior
+end
+
+class CalculateOrderTotalService
+  def call(order)
+    total = order.items.sum { |i| i.price * i.quantity }
+    total *= 0.9 if order.customer.vip?
+    order.update!(total:)
+  end
+end
+
+class ApplyDiscountService
+  def call(order, code)
+    discount = Discount.find_by(code:)
+    order.update!(discount_amount: discount.amount)
+  end
+end
+```
+
+**Fix:** Keep domain logic in models. Services orchestrate, models know their business rules.
+
+```ruby
+# GOOD
+class Order < ApplicationRecord
+  def calculate_total
+    self.total = items.sum(&:subtotal)
+    apply_vip_discount if customer.vip?
+  end
+
+  def apply_discount(code)
+    discount = Discount.find_by(code:)
+    self.discount_amount = discount.amount
+  end
+end
+```
+
+## Bag of Random Objects
+
+**Problem:** No conventions, each service is unique.
+
+```ruby
+# BAD - No consistency
+class UserRegistration
+  def perform(attrs)
+    # returns user or nil
+  end
+end
+
+class OrderProcessor
+  def self.process!(order_id)
+    # raises on failure
+  end
+end
+
+class SendNewsletterJob
+  def run(newsletter, subscribers)
+    # returns count
+  end
+end
+```
+
+**Fix:** Establish conventions.
+
+```ruby
+# GOOD - Consistent interface
+class ApplicationService
+  extend Dry::Initializer
+  def self.call(...) = new(...).call
+end
+
+class RegisterUserService < ApplicationService
+  param :attrs
+  def call
+    # Returns result object
+  end
+end
+
+class ProcessOrderService < ApplicationService
+  param :order_id
+  def call
+    # Returns result object
+  end
+end
+```
+
+## Premature Abstraction
+
+**Problem:** Creating abstractions before patterns emerge.
+
+```ruby
+# BAD - Over-engineered from day one
+class BaseCommand
+  include CommandPattern
+  include ResultMonad
+  include TransactionWrapper
+end
+
+class CreateUserCommand < BaseCommand
+  # Complex infrastructure for simple operation
+end
+```
+
+**Fix:** Wait for patterns to emerge. Start simple.
+
+```ruby
+# GOOD - Simple first
+class CreateUserService
+  def self.call(params)
+    User.create!(params)
+  end
+end
+
+# Extract patterns AFTER you see repetition
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/anti-patterns/testing.md

@@ -0,0 +1,37 @@
+# Testing Anti-Patterns
+
+Tests that verify the wrong layer's responsibilities.
+
+## Testing Wrong Layer
+
+**Problem:** Controller tests verify business logic.
+
+```ruby
+# BAD
+describe OrdersController do
+  it "applies VIP discount" do
+    post :create, params: { items: [...] }
+    expect(Order.last.total).to eq(90)  # Testing domain logic!
+  end
+end
+```
+
+**Fix:** Test business logic in model specs.
+
+```ruby
+# GOOD
+describe Order do
+  it "applies VIP discount" do
+    order = build(:order, customer: vip_customer)
+    order.calculate_total
+    expect(order.total).to eq(90)
+  end
+end
+
+describe OrdersController do
+  it "creates order and redirects" do
+    post :create, params: { items: [...] }
+    expect(response).to redirect_to(Order.last)
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/core/architecture-layers.md

@@ -0,0 +1,204 @@
+# Architecture Layers
+
+## Contents
+
+- The Four Layers (Presentation, Application, Domain, Infrastructure)
+- The Four Layering Rules
+- Mapping Rails Components to Layers
+- Applying Layered Architecture in Practice
+- Common Layering Mistakes
+
+## The Four Layers (Presentation, Application, Domain, Infrastructure)
+
+Rails applications are organized into four architecture layers with unidirectional data flow:
+
+| Layer | Responsibility | Rails Examples |
+|-------|----------------|----------------|
+| **Presentation** | Handle user interactions, present information | Controllers, Views, Channels, Mailers |
+| **Application** | Organize domain objects for use cases | Service objects, Form objects, Policy objects |
+| **Domain** | Entities, rules, invariants, application state | Models, Value objects, Domain events |
+| **Infrastructure** | Supporting technologies | Active Record, API clients, File storage |
+
+```
+Presentation → Application → Domain → Infrastructure
+```
+
+## The Four Layering Rules
+
+### Rule 1: Unidirectional Data Flow
+
+Data flows from top to bottom only. Arrows in the architecture always point downward.
+
+### Rule 2: No Reverse Dependencies
+
+Lower layers must not depend on higher layers. A domain object should never depend on a controller or request object.
+
+**Violations:**
+
+```ruby
+# BAD: Service (Application) depends on request (Presentation)
+class HandleEventService
+  param :request  # Reverse dependency!
+end
+
+# BAD: Model (Domain) depends on Current (Presentation context)
+class Post < ApplicationRecord
+  def destroy
+    self.deleted_by = Current.user  # Hidden dependency!
+    super
+  end
+end
+```
+
+**Correct:**
+
+```ruby
+# GOOD: Service accepts domain objects only
+class HandleEventService
+  param :event  # Value object, not request
+
+  def call
+    user = User.find_by(gh_id: event.user_id)
+    # ...
+  end
+end
+
+# GOOD: Model method accepts explicit parameters
+class Post < ApplicationRecord
+  def destroy_by(user:)
+    self.deleted_by = user
+    destroy
+  end
+end
+```
+
+### Rule 3: Abstraction Boundaries
+
+Every abstraction layer must belong to a single architecture layer. An abstraction cannot span multiple architecture layers.
+
+**Evaluating abstractions:**
+- Does this object depend on objects from a higher layer? → Extract or refactor
+- Does this object's responsibility match its architecture layer? → Move if not
+
+### Rule 4: Minimize Inter-Layer Connections
+
+Fewer connections = looser coupling = better testability and reusability.
+
+**Good layering:**
+```ruby
+# Controller (Presentation) → Service (Application) → Model (Domain)
+class PostsController
+  def publish
+    PublishPostService.call(post_id: params[:id], user: current_user)
+    redirect_to posts_path
+  end
+end
+
+class PublishPostService
+  def call
+    post = Post.find(post_id)
+    post.publish!(by: user)  # Domain logic stays in model
+  end
+end
+```
+
+**Caveat — Architecture Sinkhole:** If you reduce connections to minimum (each layer only talks to adjacent layer), you may create objects that just proxy data through layers with no modification.
+
+```ruby
+# BAD: Service does nothing but proxy
+class FindPostService
+  def call(id)
+    Post.find(id)  # No value added, just pass-through
+  end
+end
+```
+
+## Mapping Rails Components to Layers
+
+### Presentation Layer
+
+**Purpose:** Handle user interactions, present information
+
+**Includes:**
+- Controllers (HTTP request/response)
+- Views (HTML rendering)
+- Channels (WebSocket connections)
+- Mailers (email composition)
+- API serializers
+- Form objects (user input handling)
+- Filter objects (request parameter transformation)
+- Presenters (view-specific logic)
+
+**Primary concerns:**
+- Request parsing and validation
+- Authentication
+- Response formatting
+- User interface logic
+
+### Application Layer
+
+**Purpose:** Organize domain objects for specific use cases
+
+**Includes:**
+- Service objects (business operations)
+- Policy objects (authorization)
+- Interactors/Commands
+
+**Primary concerns:**
+- Orchestrating domain objects
+- Transaction boundaries
+- Use-case specific logic
+
+**Warning:** This layer is often overused. Don't strip all logic from models into services (anemic models anti-pattern).
+
+### Domain Layer
+
+**Purpose:** Entities, rules, invariants, application state
+
+**Includes:**
+- Models (business entities)
+- Value objects (immutable concepts)
+- Domain events
+- Query objects (data retrieval logic)
+- Concerns (shared behaviors)
+
+**Primary concerns:**
+- Business rules and invariants
+- Entity relationships
+- Data transformations
+- Domain-specific calculations
+
+### Infrastructure Layer
+
+**Purpose:** Supporting technologies
+
+**Includes:**
+- Active Record (database access)
+- API clients (external services)
+- File storage adapters
+- Message queue adapters
+- Cache implementations
+
+**Primary concerns:**
+- Persistence
+- External communication
+- Technical implementations
+
+## Applying Layered Architecture in Practice
+
+When designing or refactoring code:
+
+1. **Identify the architecture layer** the code belongs to
+2. **Check dependencies** — does it depend on higher layers?
+3. **Apply specification test** — do tests verify appropriate responsibilities?
+4. **Extract if needed** — move code to the correct layer
+
+## Common Layering Mistakes
+
+| Mistake | Problem | Solution |
+|---------|---------|----------|
+| Current in models | Hidden dependency on presentation context | Pass as explicit parameter |
+| Request in services | Service depends on HTTP layer | Extract value object from request |
+| Mailer in callbacks | Model triggers presentation-layer code | Use events or move to controller |
+| SQL in controllers | Presentation doing infrastructure work | Use model scopes or query objects |
+| Business logic in views | Presentation doing domain work | Use presenters or model methods |