I started this newsletter to share technical solutions - code snippets, debugging wins, elegant patterns.

But here’s what happened: I stopped caring about how I solved technical problems and became obsessed with why those problems existed in the first place.

The interesting question isn’t “how do I implement feature X” - it’s “why are we building this when nobody asked for it?” The breakthrough isn’t a clever algorithm - it’s recognizing the organizational dysfunction that makes simple features take months.

So I’m putting Snippets of Code on hiatus. Not because I failed to maintain it, but because maintaining it would mean ignoring what I actually care about now.

If you want to follow where this leads:

Join me at Snippets Press, where I’m documenting the messy journey from developer to business owner - building a sustainable technical business while challenging the conventional wisdom that got us all burned out in the first place.

Real metrics. Real failures. Real businesses. No hustle porn.

https://snippetsoftext.substack.com/subscribe

Thanks for reading, Rafa

A critical feature was blocked for three weeks. Not because of technical complexity—because one service needed permission data that lived in another service, and we had no safe way to bridge that gap.

In this issue, I’ll take you through two approaches to solving cross-service data dependencies: synchronous API calls versus event-driven state replication. No architectural theory—just real trade-offs, actual implementations, and lessons learned.

What you’ll learn:

• How to design secure cross-service communication patterns

• Why permission logic duplication creates security nightmares

• Event modeling as an alternative to synchronous service calls

• Trade-offs between consistency models in distributed systems

The Problem

Here’s what we were dealing with—a feature blocked by service boundaries:

# payment-service needs to check if users can access billing data
# but authorization data lives in user-service
# and we have architectural constraints

class BillingController < ApplicationController
  def show
    # How do we verify user has permission to view billing?
    # user-service owns permission data
    # payment-service can’t directly access user-service database
    # duplicating permission logic would create security issues
    
    # Option 1: Synchronous API call to user-service?
    # Option 2: Replicate permission state via events?
    # Option 3: Share database? (please no)
  end
end

Warning Signs:

• Critical features blocked by service boundary constraints

• Temptation to share databases across services

• No established pattern for cross-service authorization

• Complex permission rules that change frequently

• Security compliance requirements for permission auditing

From Service Isolation to Communication

Understanding Why Sharing Data Is Hard

The naive approach: just query the other service’s database directly.

Before (Database Coupling - WRONG):

# In payment-service (BAD APPROACH)
class PermissionChecker
  def can_access_billing?(user_id)
    # Directly accessing user-service database
    ActiveRecord::Base.establish_connection(
      adapter: ‘postgresql’,
      host: ‘user-service-db.internal’,
      database: ‘users_production’
    )
    
    # Now we’re tightly coupled to user-service internals
    # Schema changes break us
    # Can’t evolve services independently
    # Violates microservices principles
  end
end

Why This Fails:

• Services can’t evolve database schemas independently

• No clear ownership boundaries

• Security becomes impossible to audit

• Violates microservices isolation principles

• Impossible to scale services separately

Impact:

• Rejected immediately despite deadline pressure

• Started exploring proper service communication patterns

Solution A - Synchronous API Authentication

The first approach: create a secure API endpoint that validates permissions.

The Implementation:

# In user-service: expose permission check API
module Api
  module V1
    class PermissionsController < BaseController
      before_action :authenticate_service!
      
      def check
        validator = PermissionValidator.new(
          user_id: params[:user_id],
          resource: params[:resource],
          action: params[:action],
          context: params[:context]
        )
        
        unless validator.valid?
          return render json: {
            error: ‘Invalid request’,
            details: validator.errors
          }, status: :bad_request
        end
        
        result = PermissionService.check(
          user_id: params[:user_id],
          resource: params[:resource],
          action: params[:action],
          context: params[:context] || default_context
        )
        
        audit_check(result)
        render json: format_response(result)
      end
      
      private
      
      def authenticate_service!
        provided = request.headers[’X-Service-Token’]
        expected = Settings.service_tokens[request.headers[’X-Service-Name’]]
        
        unless secure_compare(provided, expected)
          render json: { error: ‘Unauthorized service’ }, 
                 status: :unauthorized
        end
      end
      
      def default_context
        User.find(params[:user_id]).default_organization_id
      end
      
      def audit_check(result)
        PermissionAuditLog.create!(
          requesting_service: request.headers[’X-Service-Name’],
          user_id: params[:user_id],
          resource: params[:resource],
          action: params[:action],
          decision: result.granted?,
          timestamp: Time.current
        )
      end
    end
  end
end

# In payment-service: call the API
class PermissionClient
  def can_access?(user_id:, resource:, action:)
    response = HTTP
      .headers(
        ‘X-Service-Token’ => service_token,
        ‘X-Service-Name’ => ‘payment-service’
      )
      .get(
        “#{user_service_url}/api/v1/permissions/check”,
        params: {
          user_id: user_id,
          resource: resource,
          action: action
        }
      )
      
    handle_response(response)
  end
  
  private
  
  def service_token
    Settings.user_service.token
  end
end

Pros:

• ✅ Simple to understand and implement

• ✅ Real-time permission checks (always current)

• ✅ No data duplication

• ✅ Clear audit trail

• ✅ Single source of truth for permissions

Cons:

• ❌ Network latency on every check (45ms average)

• ❌ Creates runtime dependency (user-service down = payments broken)

• ❌ Doesn’t scale well for high-throughput scenarios

• ❌ Cascading failures possible

• ❌ No offline capability

When This Works:

• Low-frequency permission checks

• Strong consistency requirements

• Simple deployment topology

• Acceptable latency budget

• Services in same data center

Step 3:Step 3:Step 3:Step 3:Solution B - Event-Driven State Replication

The alternative approach: replicate permission state via events.

The Event Modeling Approach:

# Define domain events
module Events
  class PermissionGranted < Event
    attributes :user_id, :resource, :action, :granted_by, :context
  end
  
  class PermissionRevoked < Event
    attributes :user_id, :resource, :action, :revoked_by, :context
  end
  
  class UserRoleChanged < Event
    attributes :user_id, :old_role, :new_role, :changed_by
  end
end

# In user-service: publish permission changes
class GrantPermissionCommand
  def execute(user_id:, resource:, action:, granted_by:)
    permission = Permission.create!(
      user_id: user_id,
      resource: resource,
      action: action,
      granted_by: granted_by
    )
    
    # Publish event to message bus
    EventBus.publish(
      Events::PermissionGranted.new(
        user_id: user_id,
        resource: resource,
        action: action,
        granted_by: granted_by,
        context: current_context
      )
    )
    
    permission
  end
end

# In payment-service: maintain local permission cache
class PermissionProjection
  include EventSubscriber
  
  subscribes_to Events::PermissionGranted,
                 Events::PermissionRevoked,
                 Events::UserRoleChanged
  
  def on_permission_granted(event)
    LocalPermission.upsert(
      user_id: event.user_id,
      resource: event.resource,
      action: event.action,
      granted_at: event.occurred_at
    )
  end
  
  def on_permission_revoked(event)
    LocalPermission.where(
      user_id: event.user_id,
      resource: event.resource,
      action: event.action
    ).delete_all
  end
  
  def on_user_role_changed(event)
    # Rebuild permissions for user based on new role
    RebuildUserPermissionsJob.perform_later(event.user_id)
  end
end

# Local permission checking (no network call)
class LocalPermissionChecker
  def can_access?(user_id:, resource:, action:)
    LocalPermission.exists?(
      user_id: user_id,
      resource: resource,
      action: action
    )
  end
end

The Event Modeling Diagram:

[User-Service State]
      |
      | Permission Changed
      ↓
[PermissionGranted Event] → Message Bus
      |
      ↓
[Payment-Service Projection]
      |
      ↓
[Local Permission Cache]

Pros:

• ✅ Zero latency permission checks (local data)

• ✅ Services independent (user-service down = payments still work)

• ✅ Scales horizontally without synchronization

• ✅ Offline capability built-in

• ✅ Natural audit log through event stream

Cons:

• ❌ Eventual consistency (permission changes delayed)

• ❌ More complex implementation

• ❌ Data duplication across services

• ❌ Event replay needed for new services

• ❌ Potential for inconsistent state if events lost

When This Works:

• High-frequency permission checks

• Can tolerate eventual consistency

• Need offline capability

• High-availability requirements

• Services deployed across regions

There’s no universally correct answer. The choice depends on your consistency requirements and failure modes.

Ask these questions:

• How often do permissions change versus how often are they checked?

• What happens if permission data is temporarily stale?

• What’s the cost of a network call versus maintaining replicated state?

• Which failure mode is worse: stale permissions or unavailable checks?

For our billing scenario, we chose the synchronous API because:

• Permission checks were infrequent (once per session)

• Strong consistency was required (security-critical)

• Network latency was acceptable

• Simple deployment topology

For a different service (content delivery with millions of requests), we chose event-driven because:

• Permission checks happened millions of times per day

• Eventual consistency was acceptable

• Network latency was unacceptable

• Services deployed globally

Real Numbers From Both Implementations

Synchronous API Approach:

• Permission check latency: 45ms p50, 120ms p99

• Availability: 99.9% (dependent on user-service)

• Implementation time: 2 days

• Complexity: Low

• Zero data replication overhead

Event-Driven Approach:

• Permission check latency: <1ms (local lookup)

• Availability: 99.99% (independent of user-service)

• Implementation time: 1 week

• Complexity: High

• Eventual consistency window: 100ms average

• Storage overhead: 50MB per service replica

How to Decide?

def choose_approach(requirements)
  if requirements.strong_consistency_required? &&
     requirements.low_check_frequency? &&
     requirements.acceptable_latency?(50.milliseconds)
    :synchronous_api
  elsif requirements.high_throughput? &&
        requirements.eventual_consistency_acceptable? &&
        requirements.independent_service_deployments?
    :event_driven_replication
  else
    # Hybrid: cache with TTL + fallback to API
    :cached_with_api_fallback
  end
end

In practice, we often use both:

class HybridPermissionChecker
  def can_access?(user_id:, resource:, action:)
    # Try local cache first
    cached = permission_cache.get(cache_key(user_id, resource, action))
    return cached if cached.present?
    
    # Cache miss: call API
    result = api_client.check_permission(
      user_id: user_id,
      resource: resource,
      action: action
    )
    
    # Cache result with TTL
    permission_cache.set(
      cache_key(user_id, resource, action),
      result,
      expires_in: 5.minutes
    )
    
    result
  end
  
  private
  
  def cache_key(user_id, resource, action)
    “permission:#{user_id}:#{resource}:#{action}”
  end
end

This gives you:

• Fast lookups (cached)

• Strong consistency (cache TTL)

• Graceful degradation (cache during outages)

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • Map your cross-service data dependencies

   • Identify services sharing databases

   • Calculate permission check frequency in your services

2. Next Steps

   • Implement one synchronous service-to-service API

   • Prototype event-driven replication for high-frequency checks

   • Measure actual latency and consistency requirements

   • Document your consistency model for team

Analyze your microservices:

# Questions to answer
- Which services need data owned by other services?
- Are you sharing databases across services?
- What’s your permission check frequency?
- Can you tolerate eventual consistency?
- What’s your actual latency budget?
- Which failure mode is worse for your domain?

Discussion Prompts:

• How do you currently handle cross-service authorization?

• Have you measured the cost of network latency versus data replication?

• What’s your strategy for handling inconsistent distributed state?

Useful Resources:

• Building Event-Driven Microservices - Comprehensive guide to event-driven architecture

• Martin Fowler on Microservices - Foundational microservices patterns

• Event Modeling - Visual approach to designing event-driven systems

Found this useful? Share it with someone wrestling with microservices communication. Reply with your approach to cross-service data access—I’m curious what patterns are working in production.

Happy coding!

Leave a comment

Tips and Notes:

• Note: There’s no universal “right” approach—consistency requirements determine architecture

• Pro Tip: Start with synchronous APIs, migrate to events when latency becomes a problem

• Remember: Event-driven systems trade complexity for performance—make sure the trade-off is worth it

I heard this in a code review last month. A junior developer had spent three days writing tests for ActiveRecord validations—code that Rails already guarantees works. The PR sat there with 47 test files for 12 lines of business logic.

You know that moment when you realize your team is optimizing for the wrong metric? This was mine.

In this issue, I’ll take you through the testing strategy that cut our test suite runtime by 60% while actually improving code quality. No testing dogma—just practical approaches to testing what matters.

What you’ll learn:

• Why test coverage percentage is a misleading metric

• The code-to-test ratio that signals problems

• How to identify what actually needs testing

• Practical strategies for sustainable test suites

The Problem

Here’s what we were dealing with—a testing culture gone wrong:

# Actual test from our codebase
RSpec.describe User do
  it “has a name” do
    user = User.new(name: “Test”)
    expect(user.name).to eq(”Test”)
  end
  
  it “validates presence of email” do
    user = User.new(email: nil)
    expect(user).to_not be_valid
  end
  
  # ... 45 more tests like this for basic Rails functionality
end

Warning Signs:

• Test suite taking 20+ minutes to run

• Developers avoiding running tests locally

• Breaking changes passing CI because tests were brittle

• Team morale dropping as test maintenance became a burden

• Code-to-test ratio exceeding 1:3 (one line of code, three lines of tests)

The Journey: From Coverage Theater to Meaningful Testing

Recognizing What Rails Already Tests

The first breakthrough: stop testing framework guarantees.

Before:

RSpec.describe Invoice do
  describe “associations” do
    it { should have_many(:line_items) }
    it { should belong_to(:customer) }
  end
  
  describe “validations” do
    it { should validate_presence_of(:total) }
    it { should validate_numericality_of(:total) }
  end
end

After:

RSpec.describe Invoice do
  describe “#calculate_total” do
    it “sums line item amounts including tax” do
      invoice = create(:invoice)
      invoice.line_items.create!(amount: 100, tax_rate: 0.1)
      invoice.line_items.create!(amount: 200, tax_rate: 0.1)
      
      expect(invoice.calculate_total).to eq(330)
    end
  end
end

Impact:

• Test file reduced from 150 lines to 30 lines

• Tests now focus on actual business logic

• Test maintenance time cut by 75%

Understanding the Testing Pyramid

The second realization: not all tests are created equal.

        /\
       /  \    E2E Tests (slow, expensive, broad)
      /____\
     /      \
    / Integration \ (medium speed, medium cost)
   /____________\
  /              \
 /   Unit Tests   \ (fast, cheap, narrow)
/__________________\

Before (Inverted Pyramid):

• 60% E2E tests (Capybara/Selenium)

• 30% integration tests

• 10% unit tests

• Result: 20-minute test suite

After (Proper Pyramid):

• 10% E2E tests (critical user paths only)

• 20% integration tests

• 70% unit tests

• Result: 3-minute test suite

Impact:

• 85% reduction in test suite runtime

• Faster feedback during development

• Easier to identify failure causes

The Code-to-Test Ratio Reality Check

The metric that actually matters: code-to-test ratio.

Healthy ratios:

• 1:1 to 1:2 is ideal (one line of code, one to two lines of tests)

• 1:2 to 1:3 signals growing problems

• Above 1:3 means serious issues with test redundancy

Our situation:

# Business logic: 15 lines
def process_refund(amount)
  return false if amount > total
  return false if already_refunded?
  
  create_refund_transaction(amount)
  update_balance(amount)
  notify_customer
  true
end

# Tests: 180 lines testing every possible path,
# including Rails validations, associations,
# and framework behavior

We were at 1:12 ratio. Twelve lines of tests for every line of business logic.

The Aha Moment

The breakthrough came when I asked: “What are we actually afraid will break?”

Not Rails associations. Not database constraints. Not framework validations.

The risky code: Business logic with conditionals, calculations, and state changes.

Real Numbers From This Experience

After implementing focused testing strategy:

• Test suite runtime: 20 minutes → 3 minutes (85% reduction)

• Test maintenance time: 8 hours/week → 1 hour/week

• Actual bugs caught in CI: Increased by 40%

• Developer satisfaction: Significantly improved

• Code-to-test ratio: 1:12 → 1:1.5

The Final Result

# Focus tests on business logic risk areas
RSpec.describe RefundProcessor do
  describe “#process” do
    it “prevents refunds exceeding original total” do
      processor = RefundProcessor.new(total: 100)
      
      expect(processor.process(150)).to be false
    end
    
    it “prevents duplicate refunds” do
      processor = RefundProcessor.new(total: 100)
      processor.process(50)
      
      expect(processor.process(50)).to be false
    end
    
    it “updates balance and notifies customer on success” do
      processor = RefundProcessor.new(total: 100)
      
      expect { processor.process(50) }
        .to change { processor.balance }.by(-50)
        .and have_enqueued_job(CustomerNotificationJob)
    end
  end
end

Key Improvements:

• Tests focus on business rules and edge cases

• No testing of framework guarantees

• Clear documentation of expected behavior

• Fast execution enables frequent running

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • Calculate your code-to-test ratio for one file

   • Identify tests that verify framework behavior

   • Check your test suite runtime

2. Next Steps

   • Remove one redundant test file this week

   • Add one unit test for complex business logic

   • Measure test suite improvement

   • Share findings with team

Your Turn!

The Testing Audit Challenge

Analyze your test suite:

# Calculate your ratios
total_code_lines = # Count actual business logic
total_test_lines = # Count all test code
ratio = total_test_lines / total_code_lines

# Audit one test file
framework_tests = # Tests verifying Rails/framework behavior  
business_tests = # Tests verifying your business logic
percentage_valuable = business_tests / (framework_tests + business_tests)

Discussion Prompts:

• What percentage of your tests verify framework behavior?

• How much time does your team spend maintaining tests vs. writing features?

• What’s your current code-to-test ratio?

Useful Resources:

• Testing Pyramid - Martin Fowler’s guide to test balance

• Rails Testing Handbook - Practical Rails testing strategies

• RSpec Best Practices - Community-driven RSpec guidelines

Found this useful? Share it with a developer drowning in test maintenance. Reply with your code-to-test ratio—I’m curious where most teams are.

Happy coding!

Leave a comment

Tips and Notes:

• Note: Coverage percentage is a vanity metric. Focus on covering risky code, not achieving arbitrary percentages.

• Pro Tip: If you’re testing Rails associations or validations, you’re testing the framework, not your application.

• Remember: Redundant tests lower team morale more than any other technical debt. Address them proactively.

When admins reset users’ authentication methods, those users received no notification.

They’d discover their security settings changed only when they tried to log in.

You know that moment when you realize a “simple” notification turns into a distributed systems problem? This was mine.

In this issue, I’ll take you through building an event-driven notification system that bridges services without coupling them.

No distributed systems theory—just real code, actual trade-offs, and lessons learned from production.

What you’ll learn:

• How to design async notification systems using message queues

• Why synchronous notification calls create cascading failures

• Patterns for producer-consumer event architectures

• Handling failures gracefully without blocking critical operations

The Problem

Here’s what we were dealing with—a security gap that seemed simple to fix:

# In auth-service: admin resets user’s 2FA
class TwoFactorResetController < ApplicationController
  def reset
    user = User.find(params[:user_id])
    user.two_factor_methods.destroy_all
    
    # TODO: notify user their 2FA was reset
    # But how?
    # - Can’t make sync HTTP call (might timeout, block critical operation)
    # - Can’t access email service directly (different service boundary)
    # - Can’t skip notification (security requirement)
    
    render json: { success: true }
  end
end

Warning Signs:

• Critical security operations lacking user notifications

• Synchronous HTTP calls blocking admin operations

• Service boundaries preventing direct email access

• No failure recovery if notifications fail

• Compliance requirements for security event notifications

From Synchronous Blocking to Async Events

Why Synchronous Notifications Fail

The naive approach: just make an HTTP call to the notification service.

Before (Synchronous HTTP - WRONG):

class TwoFactorResetController < ApplicationController
  def reset
    user = User.find(params[:user_id])
    user.two_factor_methods.destroy_all
    
    # Synchronous HTTP call (BAD)
    NotificationClient.send_email(
      to: user.email,
      template: ‘two_factor_reset’,
      data: { name: user.name }
    )
    
    render json: { success: true }
  rescue NotificationClient::Error => e
    # What do we do here?
    # - Rollback 2FA reset? (security operation already completed)
    # - Fail the whole request? (admin operation blocked by email issue)
    # - Log and continue? (user never gets notified)
  end
end

Why This Fails:

• Admin operations blocked by email service latency/failures

• 2FA reset and notification tightly coupled

• No retry mechanism if email fails

• Creates runtime dependency between services

• Timeout in notification service breaks security operations

Impact:

• Rejected this approach after simulating notification service outage

• Admin operations must never be blocked by notification failures

Designing the Event-Driven Architecture

The solution: decouple the security operation from notification delivery using events.

The Architecture:

┌─────────────────┐         ┌──────────────┐         ┌─────────────────┐
│  Auth Service   │         │ Message Bus  │         │ Email Service   │
│                 │         │   (Kafka)    │         │                 │
│  Reset 2FA      │────────▶│              │────────▶│ Send Email      │
│  Publish Event  │         │  Topic:      │         │ (SendGrid)      │
│                 │         │  security-   │         │                 │
└─────────────────┘         │  events      │         └─────────────────┘
                            │              │
                            │  DLQ:        │
                            │  security-   │
                            │  events-dlq  │
                            └──────────────┘

The Producer (Auth Service):

# Define event types
module Events
  module Security
    TWO_FACTOR_RESET = “security.two_factor.reset”
  end
end

# Define Kafka topics
module MessageBus
  module Topics
    def self.by_environment(base_name)
      “#{Rails.env}_#{base_name}”
    end
    
    SECURITY_EVENTS = by_environment(”security_events”)
    SECURITY_EVENTS_DLQ = by_environment(”security_events_dlq”)
  end
end

# Producer for 2FA reset events
class TwoFactorResetProducer
  def self.publish(user_identifier:, email:, role:, name:)
    event = {
      event_type: Events::Security::TWO_FACTOR_RESET,
      timestamp: Time.current.iso8601,
      resource: {
        user_identifier: user_identifier,
        email: email,
        role: role,
        name: name
      }
    }
    
    kafka_producer.produce(
      event.to_json,
      topic: MessageBus::Topics::SECURITY_EVENTS,
      key: user_identifier
    )
    
    true
  rescue => e
    # Log but don’t fail the operation
    ErrorLogger.log(
      error: e,
      context: “Failed to publish 2FA reset event”,
      user_identifier: user_identifier
    )
    
    # Return false but don’t raise - notification failure
    # shouldn’t block security operation
    false
  end
  
  private
  
  def self.kafka_producer
    @kafka_producer ||= Kafka.new(
      seed_brokers: ENV[’KAFKA_BROKERS’].split(’,’),
      client_id: ‘auth-service’
    ).async_producer
  end
end

# Updated controller using producer
class TwoFactorResetController < ApplicationController
  def reset
    user = User.find(params[:user_id])
    user.two_factor_methods.destroy_all
    
    # Publish event asynchronously
    TwoFactorResetProducer.publish(
      user_identifier: user.id,
      email: user.email,
      role: user.role,
      name: user.display_name
    )
    
    # Admin operation succeeds regardless of notification
    render json: { success: true }
  end
end

Key Design Decisions:

1. Fire-and-forget publishing: Admin operation never blocks

2. Graceful degradation: Log failures but continue

3. Event enrichment: Include all data consumer needs

4. Environment-specific topics: Prevent dev/prod mixing

5. Dead letter queue: Capture failed events for investigation

Impact:

• Admin operations now take 50ms instead of 200-500ms

• Zero coupling between security ops and email delivery

• Can retry failed notifications independently

• Email service outages don’t affect security operations

Building the Consumer (Email Service)

The consumer transforms security events into email notifications.

# Event handler for 2FA reset
class SecurityEventHandler
  ROLE_TEMPLATES = {
    ‘staff’ => ‘774f9baf-4250-483b-9ebb-4945c4c3b4c6’,
    ‘parent’ => ‘59ce8688-8c83-4caa-b2ac-94b9ad5722ee’,
    ‘student’ => ‘a1b2c3d4-5678-90ab-cdef-1234567890ab’
  }.freeze
  
  DEFAULT_TEMPLATE = ROLE_TEMPLATES[’staff’]
  
  def handle_two_factor_reset(event)
    resource = event[’resource’]
    
    template_id = ROLE_TEMPLATES.fetch(
      resource[’role’],
      DEFAULT_TEMPLATE
    )
    
    EmailSender.send_template(
      to: resource[’email’],
      template_id: template_id,
      substitutions: {
        user_name: resource[’name’]
      }
    )
    
    AuditLog.create!(
      event_type: ‘two_factor_reset_notification_sent’,
      user_identifier: resource[’user_identifier’],
      email: resource[’email’],
      timestamp: Time.current
    )
  rescue => e
    ErrorLogger.log(
      error: e,
      context: “Failed to send 2FA reset email”,
      event: event
    )
    
    # Re-raise to send to DLQ
    raise
  end
end

# Kafka consumer
class SecurityEventsConsumer
  def initialize
    @kafka = Kafka.new(
      seed_brokers: ENV[’KAFKA_BROKERS’].split(’,’),
      client_id: ‘email-service’
    )
    
    @consumer = @kafka.consumer(
      group_id: ‘email-service-security-events’
    )
    
    @consumer.subscribe(MessageBus::Topics::SECURITY_EVENTS)
  end
  
  def consume
    @consumer.each_message do |message|
      event = JSON.parse(message.value)
      
      case event[’event_type’]
      when Events::Security::TWO_FACTOR_RESET
        SecurityEventHandler.new.handle_two_factor_reset(event)
      else
        Rails.logger.warn(”Unknown event type: #{event[’event_type’]}”)
      end
      
    rescue => e
      ErrorLogger.log(
        error: e,
        message_offset: message.offset,
        partition: message.partition
      )
      
      # Send to DLQ
      dlq_producer.produce(
        message.value,
        topic: MessageBus::Topics::SECURITY_EVENTS_DLQ,
        key: message.key
      )
    end
  end
  
  private
  
  def dlq_producer
    @dlq_producer ||= @kafka.async_producer
  end
end

Consumer Features:

1. Role-based templates: Different emails for different user types

2. Graceful error handling: Failed messages go to DLQ, not lost

3. Audit logging: Track notification delivery

4. Unknown event handling: Log but don’t fail on unexpected events

5. Consumer groups: Multiple instances process in parallel

Impact:

• Email delivery decoupled from security operations

• Failed emails can be retried without re-executing security ops

• Different services can consume same events for different purposes

• Consumer can be scaled independently based on event volume

Handling the Feature Flag Dance

The unexpected complexity: coordinating feature flags across services.

# In auth-service: respect Kafka production flag
class TwoFactorResetProducer
  def self.publish(user_identifier:, email:, role:, name:)
    return false unless feature_enabled?
    
    # ... publish event
  end
  
  private
  
  def self.feature_enabled?
    Settings.kafka.event_production_enabled
  end
end

# In email-service: respect consumer flag
class SecurityEventsConsumer
  def consume
    return unless feature_enabled?
    
    # ... consume events
  end
  
  private
  
  def feature_enabled?
    Settings.kafka.event_consumption_enabled
  end
end

Deployment Strategy:

1. Deploy consumer first (deployed, flag off)

2. Enable consumer flag (consuming but no events yet)

3. Deploy producer (deployed, flag off)

4. Enable producer flag (events now flow through system)

5. Monitor for 24 hours

6. Remove flags after stability confirmed

Why This Order Matters:

If you deploy producer first and enable it, events will pile up with no consumer. When consumer eventually deploys, it processes huge backlog, potentially causing email storms.

The breakthrough: async notifications aren’t about making things faster—they’re about making critical operations reliable by decoupling them from ancillary concerns.

The principle: Security operations succeed or fail based on security logic, not email delivery status.

Some Numbers From This Implementation

After rolling out event-driven notifications:

• Admin operation latency: 200-500ms → 50ms (4-10x faster)

• Operation success rate: 97% → 99.9% (email failures no longer block)

• Email delivery reliability: Same (moved problem to consumer, not eliminated)

• System complexity: Increased (added message bus, consumers, DLQ handling)

• Debugging difficulty: Higher (distributed traces across services)

• Retry capability: None → Full (can replay events from Kafka)

Async vs Sync

Use synchronous notifications when:

• Notification failure should block the operation

• User needs immediate confirmation

• Operations are low-frequency

• Services share same deployment boundary

Use async events when:

• Operation success independent of notification

• Need retry capability

• High-frequency operations

• Multiple consumers need same event

• Services deployed independently

The Complete Flow

1. Admin clicks “Reset 2FA” in UI
2. Auth service resets 2FA methods in database
3. Auth service publishes event to Kafka (fire-and-forget)
4. Admin sees success immediately (operation completed)
5. Kafka persists event to topic
6. Email service consumer picks up event
7. Email service sends notification via SendGrid
8. If email fails: event goes to DLQ for investigation
9. If email succeeds: audit log created

Key Properties:

• Steps 1-4 complete in 50ms

• Steps 5-9 happen asynchronously

• Failure in steps 5-9 don’t affect steps 1-4

• Can replay/retry steps 5-9 independently

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • List all synchronous notification calls in critical paths

   • Identify operations blocked by notification failures

   • Check if your message bus has dead letter queues configured

2. Next Steps

   • Implement one async notification using events

   • Add dead letter queue handling for failed events

   • Create monitoring for consumer lag

   • Document event schemas for team

Your Turn!

The Notification Audit Challenge

Analyze your notification patterns:

# Questions to answer
- Which operations block on notification delivery?
- What’s your notification failure rate?
- How do you retry failed notifications?
- Can users recover from missed notifications?
- What’s your average notification latency?
- Do notification failures affect user operations?

Discussion Prompts:

• How do you currently handle notification failures?

• Have notification issues ever caused operation failures?

• What’s your strategy for notification retries?

What’s Next?

Next week: “Dead Letter Queues: The Error Handling Pattern You’re Missing” - Why successful systems need a place to put things that failed, and how to design DLQ processing that actually works.

Useful Resources:

• Kafka: The Definitive Guide - Comprehensive Kafka patterns

• Enterprise Integration Patterns - Message-based integration patterns

• AWS SQS Dead Letter Queues - DLQ concepts

Found this useful? Share it with someone building notification systems. Reply with your async notification patterns—I’m curious what message buses people are actually using in production.

Happy coding!

Share

Tips and Notes:

• Note: Async notifications trade immediacy for reliability—make sure that’s the right trade-off for your use case

• Pro Tip: Always deploy consumers before producers to avoid event backlogs

• Remember: Dead letter queues are not optional—failed messages need somewhere to go for investigation

Everyone thinks complex database queries are just a performance problem you can solve with better hardware.

I thought that too.

Last month, our monitoring alerts started screaming. One query was consuming 85% of database runtime. Users were abandoning pages. Support tickets were flooding in about timeouts.

The query looked reasonable in development. Clean JOINs, proper indexing, standard patterns. It worked fine with test data.

Then production traffic hit it like a freight train.

Here’s what we were dealing with: a webhook delivery system that tracked failed synchronization events for student records. The query had to identify which student entities had failed webhook deliveries.

SELECT COALESCE(deliveries.entity_id, delivery_entities.entity_id) AS entity_id
FROM webhook_deliveries deliveries
LEFT JOIN webhook_delivery_entities delivery_entities 
  ON deliveries.id = delivery_entities.webhook_delivery_id
WHERE (deliveries.entity_id IN (:student_ids) AND deliveries.entity_type = ‘Student’) 
   OR (delivery_entities.entity_id IN (:student_ids) AND delivery_entities.entity_type = ‘Student’)

Looks harmless, right?

Wrong.

In production, those IN clauses contained 975,000 UUIDs. The database was processing 47MB of data per request. The LEFT JOIN with OR conditions created execution plans that made the query planner weep.

Result: 14.94 seconds per request.

The original developer (me) made a classic mistake: optimizing for the wrong constraint.

I optimized for:

• Fewer database round trips

• Single query complexity

• “Elegant” SQL patterns

I should have optimized for:

• Query execution time under load

• Database memory usage

• Realistic data volumes

The insight: sometimes two simple queries beat one complex query by 500x.

The Counter-Intuitive Solution

Instead of fixing the complex query, I broke it into two simple ones:

# Query 1: Get failed entity IDs from main deliveries table
failed_from_deliveries = WebhookDelivery
  .where(status: ‘failed’, entity_type: ‘Student’)
  .where(created_at: date_range)
  .pluck(:entity_id)

# Query 2: Get failed entity IDs from junction table  
failed_from_entities = WebhookDeliveryEntity
  .joins(:webhook_delivery)
  .where(webhook_deliveries: { status: ‘failed’ })
  .where(entity_type: ‘Student’, created_at: date_range)
  .pluck(:entity_id)

# Combine and filter
all_failed = (failed_from_deliveries + failed_from_entities).uniq
student_ids.select { |id| all_failed.include?(id) }

“But that’s two database calls!”

Yes. And it’s 508x faster.

The Scaling Reality Check

I benchmarked both approaches across realistic data volumes:

Load Level UUIDs Original Query New Approach Improvement Small 1,000 13.26ms 1.53ms 8.7x Medium 325,000 2,950ms 12.25ms 241x Large 650,000 8,575ms 24.48ms 350x Production 975,000 14,943ms 29.37ms 509x

The pattern: as data volume increased, the performance gap widened exponentially.

The original query’s execution time scaled catastrophically. The new approach scaled almost linearly.

What I Learned About Database Performance

Lesson 1: Query planners have limits Complex queries with large IN clauses and OR conditions can overwhelm the database optimizer. Sometimes you need to help it by breaking things down.

Lesson 2: Memory pressure matters more than round trips The 47MB of UUID data being processed was the real bottleneck, not the network round trip for a second query.

Lesson 3: Test with realistic data volumes Our test database had 1,000 records. Production had nearly a million. The scaling characteristics were completely different.

Lesson 4: Simple often beats elegant Two straightforward queries with predictable execution plans outperformed one “clever” query by orders of magnitude.

The Caching Layer That Made It Bulletproof

Even with the optimized queries, I added a caching layer to handle traffic spikes:

def failed_entity_ids_for_organization(org, date_range: nil)
  cache_key = “failed_entities/#{org.id}/#{date_range&.first&.to_date}”
  
  Rails.cache.fetch(cache_key, expires_in: 5.minutes) do
    get_failed_entity_ids(org, date_range)
  end
end

The date-scoped cache keys were crucial. Instead of invalidating all cached data when any webhook delivery changed, we only invalidated data for specific days.

Result: 99% cache hit rate in production.

The Production Impact

After deployment:

• Database CPU utilization dropped from 95% to 15%

• Page load times went from 15+ seconds to under 500ms

• Support tickets about timeouts disappeared completely

• We could handle 10x more concurrent users

The query that was consuming 85% of database runtime now uses less than 1%.

What This Means for Your Systems

Stop optimizing for theoretical elegance. Start optimizing for production reality.

Your database doesn’t care how elegant your SQL looks. It cares about execution plans, memory usage, and I/O patterns.

Test with realistic data volumes, not toy datasets. Performance characteristics can change dramatically at scale.

Consider the total system load, not just individual query performance. Sometimes multiple simple queries create less overall system stress than one complex query.

Always have a caching strategy for expensive operations, even optimized ones.

Your Next Database Optimization

Look at your slowest queries in production. Ask yourself:

• Are you optimizing for elegance or performance?

• Have you tested with realistic data volumes?

• Could breaking complex queries into simple ones help?

• Do you have appropriate caching for expensive operations?

The query optimization that saved our database wasn’t about better SQL—it was about challenging assumptions about what “better” actually means.

This week’s experiment: benchmarking database query patterns at scale. What assumptions are you making about your system’s performance that might not hold at production volumes?

- Rafa

P.S. The most expensive performance optimization is the one you never measure. If you’re not benchmarking with realistic data, you’re optimizing blind.

You know that moment when you realize half your test suite is asserting the wrong things because nobody taught you the fundamental difference between testing state changes and testing message passing? This was mine.

In this issue, I’ll take you through the message classification system that transformed how we approach testing. No theory dumps – just real code, real problems, and real solutions.

🚀 What you’ll learn:

• How to identify incoming vs outgoing command messages

• When to test state changes vs message expectations

• Why mixing up these patterns creates fragile tests

• How proper message classification prevents over-testing and under-testing

The Problem

We had confused tests that mixed different assertion patterns, making our test suite both brittle and unreliable.

Here’s what we were dealing with:

# Confused test - mixing state and message assertions
RSpec.describe User, type: :model do
  describe '#activate!' do
    let(:user) { User.create!(email: 'test@example.com', active: false) }
    
    it 'activates the user and logs the event' do
      # Testing internal state change
      expect { user.activate! }.to change { user.active }.from(false).to(true)
      
      # Also testing external message sending (wrong!)
      expect(AuditLogger).to have_received(:log).with('user_activated', user.id)
      
      # And testing implementation details (also wrong!)
      expect(user).to have_received(:update!).with(active: true, activated_at: anything)
    end
  end
end

💡 Warning Signs:

• Tests asserting both state changes and message expectations in the same test

• Fragile tests that broke when implementation changed

• Over-mocked tests that didn’t actually verify behavior

• Confusion about what each test was actually validating

The Journey: From Problem to Solution

Step 1: Understanding Command Message Types

The Core Insight: Command messages create side-effects, but the location of those side-effects determines how you should test them.

Two Types:

• Incoming Command Messages → side-effects handled directly by the object under test

• Outgoing Command Messages → side-effects delegated to collaborators

Before:

# Mixed-up testing approach
it 'activates user and publishes event' do
  expect(user).to receive(:update!).with(active: true) # Wrong - testing implementation
  expect(EventBus).to receive(:publish) # Wrong category - should be separate test
  
  user.activate!
  
  expect(user).to be_active # Right assertion, wrong place
end

After:

# Clear separation of concerns
describe '#activate!' do
  it 'changes user state to active' do
    user.activate!
    
    expect(user).to be_active
    expect(user.activated_at).to be_within(1.second).of(Time.current)
  end
end

🎯 Impact:

• Tests became focused on single responsibilities

• Brittle mocking decreased dramatically

• Test failures pointed to actual problems, not implementation changes

Step 2: Properly Testing Outgoing Command Messages

The key realization was that outgoing commands don’t change the sender object - they delegate responsibility to collaborators.

Incoming Command Example:

# app/models/user.rb
class User < ActiveRecord::Base
  def activate!
    update!(active: true, activated_at: Time.current)
  end
end

# Test the direct side-effect on the object
RSpec.describe User do
  describe '#activate!' do
    let(:user) { User.create!(email: 'test@example.com', active: false) }
    
    it 'activates the user' do
      user.activate!
      
      expect(user).to be_active
      expect(user.activated_at).to be_within(1.second).of(Time.current)
    end
  end
end

Outgoing Command Example:

# app/models/invoice.rb
class Invoice < ActiveRecord::Base
  TOPIC_NAME = 'invoices'
  include Phobos::Producer
  
  def publish_event!(account_id:, year:, month:)
    publish(
      topic: TOPIC_NAME,
      payload: {
        account_id: account_id,
        year: year,
        month: month
      }.to_json,
      partition_key: account_id.to_s
    )
  end
end

# Test that the message was sent to the collaborator
RSpec.describe Invoice do
  describe '#publish_event!' do
    let(:invoice) { Invoice.create!(account_id: 123, year: 2025, month: 9) }
    
    it 'publishes to Kafka' do
      expect(invoice).to receive(:publish).with(
        topic: 'invoices',
        payload: { account_id: 123, year: 2025, month: 9 }.to_json,
        partition_key: '123'
      )
      
      invoice.publish_event!(account_id: 123, year: 2025, month: 9)
    end
  end
end

The Aha Moment

The breakthrough came when we realized we were testing the wrong contracts.

For incoming commands, the contract is: “This object’s state will change in a specific way.” For outgoing commands, the contract is: “This collaborator will receive a specific message.”

Real Numbers From This Experience

• Before: 40% of our tests were mixing assertion patterns

• After: Clear separation with focused, reliable tests

• Test maintenance: 60% reduction in brittle test failures

• Debug time: Cut test debugging time from hours to minutes

The Final Result

# Clean command message testing patterns

# Incoming Command: Test direct side-effects
class BankAccount
  def deposit(amount)
    self.balance += amount
    self.last_deposit_at = Time.current
    save!
  end
end

# Test the object's state change
RSpec.describe BankAccount do
  describe '#deposit' do
    let(:account) { BankAccount.create!(balance: 100) }
    
    it 'increases the balance and records timestamp' do
      account.deposit(50)
      
      expect(account.balance).to eq(150)
      expect(account.last_deposit_at).to be_within(1.second).of(Time.current)
    end
  end
end

# Outgoing Command: Test message sending
class OrderProcessor
  def fulfill_order(order)
    inventory_service.reserve_items(order.items)
    shipping_service.create_shipment(order)
    notification_service.send_confirmation(order.customer_email)
  end
end

# Test that collaborators receive the right messages
RSpec.describe OrderProcessor do
  describe '#fulfill_order' do
    let(:order) { double('order', items: ['item1'], customer_email: 'test@example.com') }
    let(:processor) { OrderProcessor.new }
    
    before do
      allow(processor).to receive(:inventory_service) { double('inventory') }
      allow(processor).to receive(:shipping_service) { double('shipping') }
      allow(processor).to receive(:notification_service) { double('notifications') }
    end
    
    it 'coordinates with all required services' do
      expect(processor.inventory_service).to receive(:reserve_items).with(['item1'])
      expect(processor.shipping_service).to receive(:create_shipment).with(order)
      expect(processor.notification_service).to receive(:send_confirmation).with('test@example.com')
      
      processor.fulfill_order(order)
    end
  end
end

🎉 Key Improvements:

• Clear distinction between internal state changes and external collaborations

• Tests that focus on the right contracts and responsibilities

• Reduced test fragility from over-mocking internal implementation

• Better test failure messages that point to actual problems

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • Review your recent tests and identify mixed assertion patterns

   • Separate state-change assertions from message-sending expectations

   • Remove mocks on the object under test for incoming command messages

2. Next Steps

   • Audit your test suite for command message classification

   • Create team guidelines for testing different message types

   • Refactor your most brittle tests using these patterns

Your Turn!

The Message Classification Challenge

How would you test these two methods differently?

class ShoppingCart
  # Method 1: Changes cart state directly
  def add_item(product, quantity)
    items << CartItem.new(product: product, quantity: quantity)
    self.total += (product.price * quantity)
    self.updated_at = Time.current
  end
  
  # Method 2: Delegates to external service
  def process_payment(payment_details)
    payment_service.charge(
      amount: total,
      card: payment_details[:card],
      customer_id: customer_id
    )
  end
end

💬 Discussion Prompts:

• What would you assert for add_item vs process_payment?

• Why would mocking be wrong for one but right for the other?

• How does this distinction help you write better tests?

🔧 Useful Resources:

• Practical Object-Oriented Design by Sandi Metz

• RSpec Best Practices Guide

• Testing Rails Applications Guide

Found this useful? Share it with a fellow developer who’s struggled with fragile tests! And don’t forget to subscribe for more practical testing insights.

Share

Happy coding! 🚀

💡 Tips and Notes

• Pro Tip: If you’re mocking the object under test, you’re probably testing an outgoing command message

• Remember: Incoming commands change the object’s state; outgoing commands send messages to collaborators

You know that moment when you realize someone created the same table twice, and now every subsequent migration is blocked because PostgreSQL won’t let you create something that already exists? This was mine.

In this issue, I’ll take you through how we debugged a deployment-blocking migration error and implemented a safer approach to large-scale data backfilling. No theory dumps – just real code, real problems, and real solutions.

What you’ll learn:

• How to identify and resolve duplicate migration conflicts

• Why chunked data processing prevents production disasters

• When to use background jobs for large dataset operations

• How to build idempotent rake tasks that are safe to retry

The Problem

We had a classic case of migration chaos during a critical deployment.

Here’s what we were dealing with:

# Migration file: 20250423222157_add_report_subscribers_table.rb
class AddReportSubscribersTable < ActiveRecord::Migration[7.0]
  def change
    create_table :report_subscribers, id: :uuid do |t|
      t.references :report, null: false, foreign_key: true, type: :uuid
      t.string :subscriber_type, null: false
      t.string :subscriber_id, null: false
      t.datetime :deleted_at
      t.timestamps
    end
    
    add_index :report_subscribers, [:report_id, :subscriber_type]
  end
end

Warning Signs:

• Deployment failing with PG::DuplicateTable error

• Migration attempting to create existing table structure

• All subsequent migrations blocked by the failed migration

• Production deployment pipeline completely stuck

The Journey: From Problem to Solution

Step 1: Emergency Migration Cleanup

The Issue: The report_subscribers table already existed with the correct schema, but our migration was trying to create it again.

Before:

# Failed migration blocking deployment
rake db:migrate
# => PG::DuplicateTable: ERROR: relation "report_subscribers" already exists

After:

# Removed the duplicate migration file entirely
# db/migrate/20250423222157_add_report_subscribers_table.rb -> deleted

# Verified existing table structure
rails console
ActiveRecord::Base.connection.table_exists?('report_subscribers')
# => true

Impact:

• Deployment pipeline immediately unblocked

• All subsequent migrations could run successfully

• Existing functionality preserved without data loss

Step 2: Implementing Safe Data Backfilling

While fixing the migration, we also needed to address a related challenge: backfilling missing session_group_id values across millions of MediaFile records.

The Challenge:

# Naive approach - would lock the database
MediaFile.where(fileable_type: 'UserSession', session_group_id: nil)
         .find_each do |file|
  # This could be millions of records!
  file.update!(session_group_id: file.fileable.session_group_id)
end

The Solution:

# Safe chunked processing via rake task
task :backfill_session_group_id_to_media_files => :environment do
  # Find date range for processing
  oldest = MediaFile.where(
    fileable_type: 'UserSession', 
    session_group_id: nil,
    deleted_at: nil
  ).minimum(:created_at)
  
  newest = MediaFile.where(
    fileable_type: 'UserSession', 
    session_group_id: nil,
    deleted_at: nil
  ).maximum(:created_at)
  
  # Process by month to avoid memory issues
  current = oldest.beginning_of_month
  while current <= newest
    month_end = current.end_of_month
    
    # Queue background job for each month
    DataMigration::BackfillSessionGroupIdJob.perform_async(
      current.iso8601, 
      month_end.iso8601
    )
    
    current = current.next_month
  end
end

The Aha Moment

The key realization was that both problems shared the same root cause: operations that don’t respect the scale and constraints of production systems.

Duplicate migrations happen because developers don’t check existing schema state. Large dataset operations fail because they don’t account for memory limits and database locks.

Real Numbers From This Experience

• Before: 100% deployment failure rate due to migration conflict

• After: 0 deployment failures from duplicate migrations

• Backfill processing: 2.3 million records processed safely over 6 hours

• Database impact: 0 production locks or performance degradation

The Final Result

# Clean migration state
class CheckMigrationStatus
  def self.call
    # Verify table exists with correct schema
    return false unless ActiveRecord::Base.connection.table_exists?('report_subscribers')
    
    # Confirm model associations work
    ReportDocument.new.respond_to?(:report_subscribers) &&
    ReportSubscriber.column_names.include?('session_group_id')
  end
end

# Safe background job for chunked processing  
class DataMigration::BackfillSessionGroupIdJob < ApplicationJob
  def perform(start_date, end_date)
    MediaFile.where(
      fileable_type: 'UserSession',
      session_group_id: nil,
      deleted_at: nil,
      created_at: start_date..end_date
    ).includes(:fileable).find_in_batches(batch_size: 1000) do |batch|
      batch.each do |file|
        next unless file.fileable&.session_group_id
        
        file.update_column(:session_group_id, file.fileable.session_group_id)
      end
    end
  end
end

Key Improvements:

• Migration conflicts eliminated through proper schema verification

• Large datasets processed safely without database locks

• Background job architecture allows monitoring and retry capabilities

• Idempotent operations that are safe to run multiple times

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • Check for existing tables before creating new migrations

   • Add schema verification to your migration checklist

   • Review any pending large dataset operations

2. Next Steps

   • Implement chunked processing for any large dataset operations

   • Set up background job monitoring for data migrations

   • Create migration rollback procedures for emergency situations

Your Turn!

The Safe Migration Challenge

How would you safely backfill this relationship without locking the database?

# You need to populate the missing user_type field
# for 5 million existing User records based on their email domain
class User < ApplicationRecord
  # user_type was just added and needs backfilling
  # corporate emails should be 'enterprise'
  # gmail/yahoo should be 'consumer' 
  # everything else should be 'unknown'
end

# Your challenge: Write a safe backfill strategy

💬 Discussion Prompts:

• How would you chunk this operation to avoid memory issues?

• What batch size would you choose and why?

• How would you make this operation resumable if it fails partway through?

🔧 Useful Resources:

• Rails Migration Guide

• PostgreSQL Concurrent Operations

• Sidekiq Best Practices

Found this useful? Share it with a fellow developer who’s dealt with migration headaches! And don’t forget to subscribe for more practical database insights.

Happy coding! 🚀

💡 Tips and Notes

• Pro Tip: Always verify table existence before creating migrations, especially in team environments

• Remember: When processing millions of records, think in terms of chunks and background jobs, not single transactions

Leave a comment

My colleague spent two hours debugging order calculations that should have been straightforward.

You know that moment when you realize a bug exists because your code is accessing orders[2] in one place and orders[1] in another, and nobody knows what these indices actually mean? This was his.

In this issue, I’ll take you through how Ruby Struct transforms confusing raw data into meaningful, self-documenting code. No theory dumps – just real code, real problems, and real solutions.

🚀 What you’ll learn:

• How to wrap meaningless data structures in business-friendly Struct classes

• Why soft typing prevents bugs that primitive types can’t catch

• When to choose Struct over full classes for domain modeling

• How proper data encapsulation creates ubiquitous language across teams

The Problem

We had painful data confusion throughout our Ruby codebase:

# What does this actually represent?
orders = Order.all
user_data = [user.name, user.email, user.created_at]
coordinates = [lat, lng, elevation]

# Which index is what? Good luck remembering.
def calculate_shipping(orders)
  orders.each do |order|
    # Is this the right array position?
    if order[3] > threshold
      # What is order[3]? Weight? Price? Quantity?
      apply_surcharge(order)
    end
  end
end

💡 Warning Signs:

• Raw arrays where meaning isn’t clear from context

• Magic indices scattered throughout the codebase

• String/Integer types that don’t explain domain meaning

• Debugging sessions that involve guessing what data represents

The Journey: From Problem to Solution

Step 1: Wrap Raw Data in Meaningful Structs

Before:

# Poor: No context, just raw data
orders = Order.all
user_coordinates = [user.lat, user.lng]

After:

# Better: Wrapped in meaningful structures
Orders = Struct.new(:orders, keyword_init: true) do
  def self.of(order_collection)
    new(orders: order_collection)
  end
  
  def high_priority
    orders.select(&:urgent?)
  end
end

Coordinates = Struct.new(:latitude, :longitude, keyword_init: true)

orders = Orders.of(Order.all)
location = Coordinates.new(latitude: user.lat, longitude: user.lng)

🎯 Impact:

• Code became self-documenting through meaningful names

• Index-based bugs disappeared completely

• Business logic could be added directly to data structures

Step 2: Create Soft Typing Through Named Attributes

Instead of relying only on primitive types, we gave meaning to values by naming them:

# Before: What kind of string is this?
def process_user_info(name, email, role)
  # name, email, role are all just strings
  # No way to enforce their meaning
end

# After: Struct enforces meaning through names
UserInfo = Struct.new(:name, :email, :role, keyword_init: true) do
  def admin?
    role == 'admin'
  end
  
  def valid_email?
    email.include?('@')
  end
end

def process_user_info(user_info)
  # user_info.name is clearly a name
  # user_info.email is clearly an email
  # Business logic is encapsulated
end

The Aha Moment

The real breakthrough came when we realized that object-oriented design focuses on the messages objects send to each other.

Struct wasn’t just about organizing data – it was about creating meaningful interfaces that hide implementation details while exposing business intent.

Real Numbers From This Experience

• Before: 15+ index-based bugs per month

• After: Zero index-based bugs

• Before: 30 minutes average debugging time for data-related issues

• After: 5 minutes average debugging time

• Code readability: 80% improvement in code review feedback

The Final Result

# Clean, self-documenting, business-focused code
Orders = Struct.new(:orders, keyword_init: true) do
  def self.of(order_collection)
    # Add validation, constraints, or business rules here
    new(orders: order_collection)
  end
  
  def total_value
    orders.sum(&:amount)
  end
  
  def urgent_orders
    orders.select(&:urgent?)
  end
  
  # Hide internal structure - consumers can't depend on array order
  def each(&block)
    orders.each(&block)
  end
end

# Usage becomes expressive and safe
customer_orders = Orders.of(Order.where(customer_id: current_user.id))
urgent_total = customer_orders.urgent_orders.sum(&:amount)

🎉 Key Improvements:

• Business terminology directly in the code

• Encapsulated behavior with data

• Protection against implementation detail leakage

• Foundation for ubiquitous language across the team

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • Find one raw array in your codebase and wrap it in a Struct

   • Replace magic indices with named Struct attributes

   • Add one business method to an existing data structure

2. Next Steps

   • Audit your codebase for primitive obsession patterns

   • Create Struct wrappers for your most-used data collections

   • Document the business meaning of your data structures

Your Turn!

The Struct Refactoring Challenge

How would you refactor this confusing data structure?

# Current: What do these represent?
user_stats = [
  user.login_count,
  user.last_login,
  user.subscription_type,
  user.is_premium?
]

def send_marketing_email(stats)
  if stats[0] > 10 && stats[3]
    # What logic is this actually implementing?
    PremiumMailer.send_retention(stats[1])
  end
end

💬 Discussion Prompts:

• How would you name the Struct to reflect business intent?

• What business methods would you add to encapsulate the logic?

• How could this improve team communication about user engagement?

🔧 Useful Resources:

• Ruby Struct Documentation

• Domain-Driven Design: Tackling Complexity

• Effective Ruby: 48 Specific Ways to Write Better Ruby

Found this useful? Share it with a fellow developer who’s tired of debugging magic indices! And don’t forget to subscribe for more practical Ruby insights.

Happy coding! 🚀

Share

💡 Tips and Notes

• Pro Tip: Use keyword_init: true for better readability and to avoid positional argument bugs

• Remember: Struct is perfect when you need more than a Hash but less than a full class

This guide shows how I do it—with RSpec, FactoryBot, and a healthy dose of skepticism about when I even need a database model.

💡 What I Think About Testing

Let me start with something I’ve learned the hard way:

Tests don’t prove correctness—they reveal your assumptions.

I used to think green tests meant “it works.” But now I know:
If a test fails, it often means the requirements are fuzzy—not that my code is broken.

Also, Rails connects everything by default. That’s both a blessing and a curse. If you lean into it blindly, you’ll create tight coupling. If you design thoughtfully, you can take advantage of it.

🔍 Start from the Outside In

When I write an endpoint, I don’t begin with models or controllers. I start with the consumer—what does the outside world expect?

Let’s say I’m building a /books endpoint. From the consumer's point of view, it should:

• Respond to GET /books

• Return a JSON array of books

• Include category information

So that’s where I start.

🛠 Step-by-Step Using RSpec

1. ✅ System Spec First (Capybara)

Even if I don’t care much about HTML in this case, I still like to begin with a high-level check:

# spec/system/books_spec.rb

require "rails_helper"

RSpec.describe "Books endpoint", type: :system do
  it "shows the books page" do
    visit "/books"
    expect(page).to have_selector("h1", text: "Books")
  end
end

Of course, this test fails. That’s the point.
Failure shows me what to build next.

2. ➕ Add the Route

# config/routes.rb

Rails.application.routes.draw do
  resources :books, only: [:index]
end

3. 🧠 Stub the Controller

# app/controllers/books_controller.rb

class BooksController < ApplicationController
  def index
    render html: "<h1>Books</h1>".html_safe
  end
end

Now the system test passes. Sweet. But HTML isn’t enough—we need JSON.

4. 🔎 Write the First Request Spec

I test the API response before implementing it. Here’s the baseline:

# spec/requests/books_spec.rb

require "rails_helper"

RSpec.describe "Books API", type: :request do
  describe "GET /books" do
    context "when no books exist" do
      it "returns an empty array" do
        get "/books", headers: { "ACCEPT" => "application/json" }

        expect(response).to have_http_status(:success)
        expect(JSON.parse(response.body)).to eq([])
      end
    end
  end
end

5. 🔧 Update the Controller to Handle JSON

# app/controllers/books_controller.rb

class BooksController < ApplicationController
  def index
    respond_to do |format|
      format.html { render html: "<h1>Books</h1>".html_safe }
      format.json { render json: [] }
    end
  end
end

That gets the test green. Now it’s time to test with actual data.

6. 🧪 Test for Real Book Records

Let’s write a more complete spec with some data:

# spec/requests/books_spec.rb

RSpec.describe "Books API", type: :request do
  describe "GET /books" do
    context "when books exist" do
      before do
        create(:book, title: "The Great Gatsby", category: "Fiction")
        create(:book, title: "Sapiens", category: "Non-fiction")
      end

      it "returns books with categories" do
        get "/books", headers: { "ACCEPT" => "application/json" }

        expect(response).to have_http_status(:success)
        books = JSON.parse(response.body)

        expect(books).to be_an(Array)
        expect(books.size).to eq(2)
        expect(books.map { |b| b["category"] }.sort).to eq(["Fiction", "Non-fiction"])
      end
    end
  end
end

7. 🟩 Return Actual Data from the Controller

# app/controllers/books_controller.rb

class BooksController < ApplicationController
  def index
    respond_to do |format|
      format.html { render html: "<h1>Books</h1>".html_safe }
      format.json { render json: books_with_categories }
    end
  end

  private

  def books_with_categories
    Book.all.map do |book|
      {
        id: book.id,
        title: book.title,
        category: book.category
      }
    end
  end
end

📦 Setting Up FactoryBot

Here's the factory I use instead of fixtures:

# spec/factories/books.rb

FactoryBot.define do
  factory :book do
    title { "Sample Book" }
    category { "Fiction" }
  end
end

🤔 Do I Even Need a Model?

Sometimes I just hard-code the data. Yeah, really.

Creating a Book model is tempting, but I ask myself:

• Will this data change frequently?

• Do I need persistence?

• Are there complex relationships?

• Will I query/filter this later?

If the answer is mostly no, then I skip the model. It keeps things simpler.

But if I do need it...

📐 When I Do Use a Model

Generate it:

rails generate model Book title:string category:string
rails db:migrate

Update the controller:

def books_with_categories
  Book.all.map do |book|
    {
      id: book.id,
      title: book.title,
      category: book.category
    }
  end
end

And I’m good to go.

🔄 Refactoring = Real Design

I’ve learned not to treat refactoring as “cleanup.” It’s design work.

After each passing test, I stop and ask:

• Can I simplify this?

• Is there a better abstraction?

• Am I happy with how the code reads?

If I see a better shape for the code, I go for it. But I don’t refactor just to refactor.

🧱 Common Pitfalls I Avoid

• Letting Rails bleed into my domain.
  My business logic shouldn’t rely on ActiveRecord or any Rails-specific stuff.

• Writing tests that don’t give me feedback.
  If a test doesn’t catch real issues or give me confidence, I delete it.

• Skipping refactoring.
  Just because the test is green doesn’t mean I’m done. Good design is the goal.

🧭 What I Keep in Mind

TDD isn’t about testing—it’s about design.

I use tests to:

• Think through user expectations

• Drive the smallest possible implementation

• Improve the design as I go

When I follow this workflow, I end up with tests that are meaningful, code that’s flexible, and apps that are easier to maintain.

Share

Get the same 25-point evaluation I use with coaching clients - completely free

Stop Fighting Your Rails Codebase

You know that sinking feeling when a "simple" Rails feature takes 3 weeks instead of 3 days? When new developers avoid certain parts of your codebase? When bug fixes create more bugs?

Your Rails application might be working, but it's probably broken in ways that are costing you thousands in lost productivity.

The Hidden Cost of "Working" Code

Most Rails teams focus on making code work, not making it maintainable. The result:

❌ Simple features take weeks instead of days
❌ New developers can't contribute for months
❌ "Don't touch it" code that everyone avoids
❌ Bug fixes that create new bugs
❌ Deployment anxiety and weekend emergencies

This isn't a skill problem - it's an architecture problem.

What You're Getting (Completely Free):

The Same Rails Code Quality Assessment I Use With Enterprise Clients

This 25-point diagnostic tool reveals the hidden issues that are silently killing your Rails development velocity.

Based on transforming Rails applications at:

• Checkr (30% to 70% invoicing accuracy improvement)

• Casper (57% process automation, 59% cost reduction)

Three Critical Areas Evaluated:

1. Coupling & Dependencies (40 points)

• Business logic mixed with external services

• Database queries scattered throughout controllers

• Impossible-to-test code that hits real APIs

• "Change one thing, break everything else" syndrome

2. Method & Class Complexity (35 points)

• Monolithic methods doing multiple unrelated things

• Controllers containing complex business logic

• Classes that have grown to hundreds of lines

• Comments explaining what code does (not why)

3. Development Velocity Impact (25 points)

• Simple features taking much longer than expected

• Team members avoiding "working" code

• New developers taking weeks to contribute

• Bug fixes introducing new problems

Your Assessment Results Include:

Immediate Clarity:

✅ Clear score (0-100) showing your Rails code health
✅ Specific problem areas ranked by impact
✅ Priority improvement roadmap based on your score
✅ Quick wins you can implement this week

Detailed Action Plans:

✅ Code examples showing before/after improvements
✅ Refactoring strategies for each problem type
✅ Team practices to prevent quality regression
✅ Metrics to track improvement progress

Expert Guidance:

✅ Same framework used with $10k+ coaching clients
✅ Real-world examples from production Rails apps
✅ Proven techniques that deliver measurable ROI

Perfect For Rails Teams That:

🎯 Struggle with slow feature delivery despite having skilled developers
🎯 Have "don't touch it" code that everyone avoids modifying
🎯 Spend more time debugging than building new features
🎯 Want new developers to contribute quickly and confidently
🎯 Need to justify refactoring to business stakeholders
🎯 Are frustrated with deployment anxiety and weekend emergencies

How It Works:

1. Download Instantly (Free)

Get the 25-point assessment PDF immediately - no waiting, no sales calls

2. Complete Assessment (15-20 minutes)

Rate your Rails application across proven quality indicators

3. Calculate Your Score

Get immediate clarity on your code health and transformation priorities

4. Follow Action Plan

Implement specific improvements based on your score range

5. Track Progress

Measure velocity improvements and team confidence gains

Get Your Free Assessment Now

DOWNLOAD FREE RAILS CODE QUALITY ASSESSMENT

Instant PDF download - At no cost

What you'll receive:

• Complete 25-point assessment scorecard

• Detailed scoring guide and interpretation

• Action plans for each score range

• Code examples and refactoring strategies

• Progress tracking framework

Frequently Asked Questions:

Q: Why is this free?
A: I want every Rails team to build maintainable applications. Quality code benefits everyone - developers, businesses, and users.

Q: How long does it take?
A: 5-10 minutes to complete, immediate results and action plan.

Q: Is this just theory?
A: No - every question comes from real patterns I've seen across 50+ Rails applications. The solutions are proven and practical.

Q: What if I score high (bad)?
A: Higher scores mean bigger opportunities for improvement. The assessment includes specific action plans for every score range.

Q: Can I share this with my team?
A: Absolutely! In fact, having multiple team members take it often reveals interesting perspectives on the same codebase.

About Rafael George

Staff Software Engineer with 15+ years transforming Rails applications at high-growth companies. Specialized in event-driven architecture and collaborative development practices that align technology with business needs.

Proven track record:

• Reduced onboarding manual work by 17% at Gusto

• Improved invoicing accuracy from 30% to 70% at Checkr

• Automated 57% of packaging processes at Casper

• Transformed Rails architectures at 20+ companies

Ready to Discover What's Slowing Your Rails Team Down?

GET YOUR FREE ASSESSMENT NOW

Download instantly - Start improving your Rails code quality today

P.S. - Need Expert Help?

If your assessment reveals significant code quality challenges (score 60+), I offer Rails Code Quality Transformation Sessions where we review your specific codebase and create a targeted improvement plan.

Learn about transformation sessions →

But start with the free assessment first - it gives us both a clear picture of your situation and improvement priorities.

Share

In this issue, I'll take you through my journey from fat models to clean, maintainable architecture. No theory dumps – just real code, real problems, and real solutions.

🚀 What you'll learn:

• Why "thin controller, fat model" advice destroys codebases

• How to extract service objects that actually make sense

• The value object pattern for cleaner data handling

• Practical steps to refactor without breaking everything

The Problem

Three months into our Rails project, our main User model had become a monster. What started as innocent database relationships had grown into a beast handling everything from authentication to payment processing to email campaigns.

Here's what we were dealing with:

class User < ActiveRecord::Base
  # 15 different associations
  has_many :orders, :reviews, :subscriptions, :notifications
  belongs_to :company, :billing_address, :shipping_address
  
  # Endless validations
  validates :email, presence: true, uniqueness: true
  validates :password, length: { minimum: 8 }
  validates :phone, format: { with: /\A[\+]?[1-9][\d .\-\(\)]{6,}\z/ }
  
  # Business logic explosion
  def upgrade_to_premium
    transaction do
      update!(subscription_type: 'premium')
      charge_credit_card
      send_welcome_email
      create_analytics_event
      sync_with_crm
      generate_invoice
      notify_sales_team
    end
  end
  
  def calculate_discount_rate
    # 50 lines of complex business logic here
  end
  
  # ... 200+ more methods
end

💡 Warning Signs:

• Tests took 45 seconds to run for a single model

• Adding new features meant touching 5+ unrelated methods

• Database fixtures required 12 related objects just to test business logic

• New developers needed 3 days just to understand one model

The Journey: From Problem to Solution

Step 1: Extract Service Objects for Complex Operations

Before:

class User < ActiveRecord::Base
  def upgrade_to_premium
    transaction do
      update!(subscription_type: 'premium')
      charge_credit_card
      send_welcome_email
      create_analytics_event
      sync_with_crm
      generate_invoice
      notify_sales_team
    end
  end
end

After:

# Clean model with only data concerns
class User < ActiveRecord::Base
  has_many :orders
  belongs_to :company
  
  validates :email, presence: true, uniqueness: true
  validates :password, length: { minimum: 8 }
end

# Dedicated service for upgrade logic
class UserUpgradeService
  def initialize(user)
    @user = user
  end
  
  def execute
    return false unless eligible_for_upgrade?
    
    ActiveRecord::Base.transaction do
      upgrade_subscription
      process_payment
      send_notifications
      track_analytics
    end
    
    true
  end
  
  private
  
  def eligible_for_upgrade?
    @user.subscription_type != 'premium' && @user.payment_method.present?
  end
  
  def upgrade_subscription
    @user.update!(subscription_type: 'premium', upgraded_at: Time.current)
  end
  
  def process_payment
    PaymentProcessor.charge(@user.payment_method, premium_price)
  end
  
  def send_notifications
    UserMailer.premium_welcome(@user).deliver_later
    NotificationService.new(@user).send_upgrade_confirmation
  end
  
  def track_analytics
    Analytics.track(@user.id, 'subscription_upgraded', { plan: 'premium' })
  end
end

🎯 Impact:

• Test suite ran 60% faster (18 seconds vs 45 seconds)

• Service objects could be tested without database setup

• Business logic became reusable across different contexts

Step 2: Introduce Value Objects for Complex Data

Before:

class User < ActiveRecord::Base
  def formatted_phone
    # 20 lines of phone formatting logic
  end
  
  def valid_phone?
    # Complex validation logic
  end
end

After:

class PhoneNumber
  attr_reader :value
  
  def initialize(raw_phone)
    @value = normalize(raw_phone)
    validate!
  end
  
  def formatted
    case country_code
    when '1' then us_format
    when '44' then uk_format
    else international_format
    end
  end
  
  def valid?
    @value.match?(/^\+\d{10,15}$/)
  end
  
  private
  
  def normalize(raw_phone)
    raw_phone.to_s.gsub(/[^\d+]/, '')
  end
  
  def validate!
    raise ArgumentError, "Invalid phone number" unless valid?
  end
end

# In the User model
class User < ActiveRecord::Base
  def phone_number
    @phone_number ||= PhoneNumber.new(phone) if phone.present?
  end
end

The Aha Moment

The breakthrough came when I realized we weren't building a database wrapper – we were building a business application that happened to use a database. The database structure shouldn't dictate our code organization.

Real Numbers From This Experience

• Before: 1,200-line User model

• After: 180-line User model + 8 focused service objects + 4 value objects

• Test suite: 45s → 18s runtime

• Bug fix time: 2-3 hours → 30 minutes average

• New feature development: 40% faster

The Final Result

# Lean User model focused on data persistence
class User < ActiveRecord::Base
  has_many :orders
  has_many :subscriptions
  belongs_to :company
  
  validates :email, presence: true, uniqueness: true
  validates :password, length: { minimum: 8 }
  
  def phone_number
    @phone_number ||= PhoneNumber.new(phone) if phone.present?
  end
  
  def full_name
    "#{first_name} #{last_name}".strip
  end
end

# Controller stays focused on HTTP concerns
class UsersController < ApplicationController
  def upgrade
    @user = current_user
    service = UserUpgradeService.new(@user)
    
    if service.execute
      redirect_to dashboard_path, notice: "Welcome to Premium!"
    else
      flash.now[:alert] = "Upgrade failed. Please try again."
      render :show
    end
  end
end

🎉 Key Improvements:

• Models handle only data persistence and simple queries

• Service objects contain isolated business logic

• Value objects encapsulate complex data types

• Controllers focus on HTTP request/response flow

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • Identify your fattest model (hint: it's probably User)

   • Count the public methods – if it's over 20, you have work to do

   • Look for methods with more than 5 lines that aren't simple queries

2. Next Steps

   • Extract one complex method into a service object this week

   • Create a value object for any data with formatting or validation logic

   • Write tests for your new objects without touching the database

Your Turn!

The Fat Model Challenge

Here's a typical fat model. How would you refactor it?

class Order < ActiveRecord::Base
  belongs_to :user
  has_many :line_items
  
  def process_payment
    return false unless valid_for_payment?
    
    transaction do
      charge_result = CreditCardProcessor.charge(
        user.credit_card, 
        total_amount
      )
      
      if charge_result.success?
        update!(status: 'paid', paid_at: Time.current)
        generate_receipt
        send_confirmation_email
        update_inventory
        create_shipment
        track_conversion
        true
      else
        errors.add(:payment, charge_result.error)
        false
      end
    end
  end
  
  def generate_receipt
    # 30 lines of PDF generation
  end
  
  def send_confirmation_email
    # Email logic
  end
  
  def update_inventory
    # Inventory management
  end
end

💬 Discussion Prompts:

• What service objects would you extract from this Order model?

• Which parts belong in the model vs external services?

• How would you test the payment processing logic?

🔧 Useful Resources:

• Sandi Metz's Rules for Developers

• Clean Architecture by Uncle Bob

• Service Objects in Rails

Found this useful? Share it with a fellow Rails developer! And don't forget to reply with your own fat model horror stories – I read every response.

Share

Happy coding!

Tips and Notes:

• Note: All code examples are simplified for clarity – real implementations should include proper error handling

• Pro Tip: Start with service objects before jumping to repositories – you can always add more abstraction later

• Remember: The goal isn't perfect architecture, it's maintainable code that your team can work with confidently

Leave a comment

In this issue, I’ll take you through how adapters transformed our messy, tightly-coupled codebase into something maintainable. No theory dumps – just real code, real problems, and real solutions.

🚀 What you’ll learn:

• How to isolate external dependencies from your core business logic

• The adapter pattern that saved us from integration hell

• Why your domain shouldn’t know about databases or APIs

• Practical techniques for building bulletproof boundaries

The Problem

Our payment processing system had grown organically over two years. What started as a simple feature had become a tangled mess where business rules, database queries, and API calls were all best friends living in the same class.

Here’s what we were dealing with:

class PaymentProcessor
  def process_payment(user_id, amount, card_details)
    # Database query mixed with business logic
    user = User.find(user_id)
    return false if user.account_balance < amount
    
    # Direct API call embedded in the flow
    response = HTTParty.post("https://payment-gateway.com/charge", {
      card_number: card_details[:number],
      amount: amount,
      user_email: user.email
    })
    
    # More database operations
    if response.code == 200
      Transaction.create!(
        user_id: user_id,
        amount: amount,
        status: 'completed',
        gateway_response: response.body
      )
      user.update!(account_balance: user.account_balance - amount)
      true
    else
      false
    end
  end
end

💡 Warning Signs:

• Business logic scattered across database concerns

• Direct HTTP calls embedded in core workflows

• Impossible to test without hitting real external services

• Changes to payment gateway required touching business logic

Subscribe now

The Journey: From Problem to Solution

Step 1: Extract the Business Logic

The first breakthrough was realizing our domain logic was drowning in infrastructure concerns. We needed to separate what the business cared about from how we stored or retrieved data.

Before:

def process_payment(user_id, amount, card_details)
  user = User.find(user_id) # Database concern
  return false if user.account_balance < amount # Business rule buried
  # ... rest mixed together
end

After:

module Payments
  class ProcessPayment
    def self.call(request)
      new.call(request)
    end
    
    Request = Struct.new(:user_id, :amount, :card_details, keyword_init: true)
    Response = Struct.new(:success, :transaction_id, :errors, keyword_init: true)
    
    def call(request)
      # Pure business logic - no database or API knowledge
      return insufficient_funds_response unless user_has_funds?(request)
      
      charge_result = charge_card(request)
      return failed_charge_response(charge_result) unless charge_result.success
      
      transaction = record_transaction(request, charge_result)
      deduct_balance(request)
      
      Response.new(success: true, transaction_id: transaction.id)
    end
    
    private
    # Business logic methods here...
  end
end

🎯 Impact:

• Business rules became crystal clear and testable

• Zero external dependencies in core logic

• 10x faster test suite (no more database hits)

Step 2: Build the Translation Layer

Now we had clean business logic, but it needed to talk to the outside world. This is where adapters became our heroes – they translate between our pristine domain and the messy real world.

The Adapter Pattern:

module Payments
  module Adapters
    class PaymentGatewayAdapter
      def initialize(gateway_service: PaymentGateway::Service.new)
        @gateway_service = gateway_service
      end
      
      Request = Struct.new(:amount, :card_details, :user_email, keyword_init: true)
      Response = Struct.new(:success, :transaction_id, :error_message, keyword_init: true)
      
      def charge_card(request)
        result = gateway_service.charge(
          amount: request.amount,
          card_number: request.card_details[:number],
          email: request.user_email
        )
        
        # Transform external response to domain language
        Response.new(
          success: result.status == 'approved',
          transaction_id: result.id,
          error_message: result.error
        )
      rescue StandardError => e
        Response.new(success: false, error_message: "Gateway unavailable")
      end
      
      private
      attr_reader :gateway_service
    end
  end
end

The Aha Moment

The breakthrough came when I realized adapters aren’t just about dependency injection – they’re translators. They speak “domain language” on one side and “external system language” on the other. Our business logic could finally focus on business rules while adapters handled the messy details of talking to databases, APIs, and external services.

Real Numbers From This Experience

• Before: 45-second test suite (hitting database and external APIs)

• After: 3-second test suite (pure unit tests)

• Bug reports decreased by 60% (cleaner separation of concerns)

• Feature delivery time improved by 40% (easier to reason about and modify)

The Final Result

module Payments
  class ProcessPayment
    def initialize(
      user_repository: Adapters::UserRepository.new,
      payment_gateway: Adapters::PaymentGatewayAdapter.new,
      transaction_repository: Adapters::TransactionRepository.new
    )
      @user_repository = user_repository
      @payment_gateway = payment_gateway
      @transaction_repository = transaction_repository
    end
    
    def call(request)
      user = user_repository.find(request.user_id)
      return insufficient_funds_response unless user.balance >= request.amount
      
      charge_request = payment_gateway_request(request, user)
      charge_result = payment_gateway.charge_card(charge_request)
      return failed_charge_response unless charge_result.success
      
      transaction = transaction_repository.create(
        user_id: user.id,
        amount: request.amount,
        gateway_transaction_id: charge_result.transaction_id
      )
      
      user_repository.deduct_balance(user.id, request.amount)
      
      Response.new(success: true, transaction_id: transaction.id)
    end
    
    private
    attr_reader :user_repository, :payment_gateway, :transaction_repository
  end
end

🎉 Key Improvements:

• Business logic completely isolated from external concerns

• Every external interaction goes through a dedicated adapter

• Testable without any external dependencies

• Easy to swap implementations (different payment gateways, databases, etc.)

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • Identify one class that talks directly to external services

   • Extract the external call into a separate method

   • Add a simple wrapper around that external dependency

2. Next Steps

   • Create your first adapter for the most problematic external integration

   • Define clear request/response objects for your adapter interface

   • Write tests for your business logic without any external dependencies

Your Turn!

The Adapter Challenge

Look at this code and identify where adapters would help:

class OrderFulfillment
  def fulfill_order(order_id)
    order = Order.find(order_id)
    return false if order.status != 'pending'
    
    # Email service call
    Mailer.deliver_now(OrderConfirmation.new(order.user.email, order))
    
    # Inventory update
    HTTParty.put("https://inventory.com/api/reserve", {
      items: order.line_items.map(&:product_id),
      quantities: order.line_items.map(&:quantity)
    })
    
    # Payment processing
    Stripe.charge(
      amount: order.total,
      customer: order.user.stripe_customer_id
    )
    
    order.update!(status: 'fulfilled')
  end
end

💬 Discussion Prompts:

• Which external dependencies would you extract first?

• How would you structure the adapter interfaces?

• What would the business logic look like after refactoring?

What’s Next?

Next week: “Repository Pattern: When Your Database Becomes a Detail” - We’ll dive deep into how to make your data persistence strategy completely swappable.

🔧 Useful Resources:

• Clean Architecture by Robert Martin

• Hexagonal Architecture (Ports and Adapters) by Alistair Cockburn

• Domain-Driven Design by Eric Evans

Found this useful? Share it with a fellow developer! And don’t forget to try refactoring one class in your current project using the adapter pattern.

Happy coding!

• Pro Tip: Start with the external dependency that causes the most testing pain – usually databases or HTTP calls

• Remember: Adapters should be thin translation layers, not business logic containers

Share

Ever stared at a Rails controller that's grown into a 200-line monster, handling everything from authentication to email sending to complex business logic? That was me last month, debugging a user signup flow that had become an unmaintainable nightmare.

You know that moment when you realize your "quick fix" has turned into spaghetti code that nobody wants to touch? This was mine.

In this issue, I'll take you through how Use Case Objects completely transformed my approach to organizing business logic in Ruby applications. No theory dumps – just real code, real problems, and real solutions.

🚀 What you'll learn:

• How to isolate business logic from Rails controllers using Use Case Objects

• The four essential rules for designing maintainable use cases

• How to structure inputs and outputs with value objects

• How Use Case Objects fit into Hexagonal Architecture

The Problem

Picture this: I'm working on a user onboarding system where the signup process involves user validation, email verification, welcome email sending, analytics tracking, and trial account setup. All of this logic was crammed into a single controller action.

Here's what we were dealing with:

class UsersController < ApplicationController
  def create
    @user = User.new(user_params)
    
    if @user.valid?
      if @user.save
        UserMailer.welcome_email(@user).deliver_now
        Analytics.track('user_signup', user_id: @user.id)
        
        if params[:trial]
          trial = Trial.create(user: @user, expires_at: 30.days.from_now)
          TrialMailer.trial_started(@user, trial).deliver_now
        end
        
        redirect_to dashboard_path, notice: 'Welcome!'
      else
        render :new
      end
    else
      render :new
    end
  end
  
  private
  
  def user_params
    params.require(:user).permit(:username, :email, :password)
  end
end

💡 Warning Signs:

• Multiple responsibilities mixed together (validation, persistence, email, analytics)

• Difficult to test individual business rules

• Hard to reuse signup logic from other contexts (API, admin interface)

• Complex conditional logic that's prone to bugs

The Journey: From Problem to Solution

Step 1: Extract Business Logic into Use Case Objects

Before:

class UsersController < ApplicationController
  def create
    @user = User.new(user_params)
    
    if @user.valid?
      if @user.save
        UserMailer.welcome_email(@user).deliver_now
        Analytics.track('user_signup', user_id: @user.id)
        # ... more logic
      end
    end
  end
end

After:

module Onboarding
  class SignUp
    # Input as value object
    Credentials = Struct.new(:username, :email, :password, :trial_requested, keyword_init: true)
    
    def self.of(attrs)
      Credentials.new(
        username: attrs.fetch(:username),
        email: attrs.fetch(:email),
        password: attrs.fetch(:password),
        trial_requested: attrs.fetch(:trial_requested, false)
      )
    end

    # Output as value object
    SignedUp = Struct.new(:user, :trial, :success, keyword_init: true)

    def self.call(params:)
      credentials = of(params)
      
      user = User.new(
        username: credentials.username,
        email: credentials.email,
        password: credentials.password
      )
      
      return SignedUp.new(user: user, success: false) unless user.valid?
      
      user.save!
      
      # Handle business logic
      UserMailer.welcome_email(user).deliver_now
      Analytics.track('user_signup', user_id: user.id)
      
      trial = nil
      if credentials.trial_requested
        trial = Trial.create(user: user, expires_at: 30.days.from_now)
        TrialMailer.trial_started(user, trial).deliver_now
      end
      
      SignedUp.new(user: user, trial: trial, success: true)
    end
  end
end

class UsersController < ApplicationController
  def create
    result = Onboarding::SignUp.call(params: signup_params)
    
    if result.success
      redirect_to dashboard_path, notice: 'Welcome!'
    else
      @user = result.user
      render :new
    end
  end
  
  private
  
  def signup_params
    params.require(:user).permit(:username, :email, :password).merge(
      trial_requested: params[:trial].present?
    )
  end
end

🎯 Impact:

• Business logic is now isolated and testable

• Controller reduced from 25 lines to 12 lines

• Signup logic can be reused across different interfaces

Step 2: Apply the Four Essential Rules

Following the rules for Use Case Objects, I refined the implementation:

1. Naming: Used SignUp (verb) to represent the action

2. Public Interface: Exposed only the .call method

3. Input/Output Structure: Created value objects for both inputs and outputs

4. Business Metrics: Focused on user experience metrics

The Aha Moment

The breakthrough came when I realized that Use Case Objects act as the application boundary in Hexagonal Architecture. They sit between external actors (controllers, background jobs, APIs) and the system's internal logic (models, services, repositories).

This means my business rules are no longer scattered across controllers, models, and service objects – they're centralized in use cases that clearly define what the application does.

Real Numbers From This Experience

• Before: 45 lines of controller code handling signup

• After: 12 lines in controller + 35 lines in well-structured use case

• Test coverage increased from 60% to 95% for signup flow

The Final Result

module Onboarding
  class SignUp
    # Input as value object
    Credentials = Struct.new(:username, :email, :password, :trial_requested, keyword_init: true)
    
    def self.of(attrs)
      Credentials.new(
        username: attrs.fetch(:username),
        email: attrs.fetch(:email),
        password: attrs.fetch(:password),
        trial_requested: attrs.fetch(:trial_requested, false)
      )
    end

    # Output as value object
    SignedUp = Struct.new(:user, :trial, :success, :errors, keyword_init: true)

    def self.call(params:)
      credentials = of(params)
      
      user = User.new(
        username: credentials.username,
        email: credentials.email,
        password: credentials.password
      )
      
      unless user.valid?
        return SignedUp.new(user: user, success: false, errors: user.errors)
      end
      
      user.save!
      
      # Execute business rules
      UserMailer.welcome_email(user).deliver_now
      Analytics.track('user_signup', user_id: user.id)
      
      trial = create_trial_if_requested(user, credentials.trial_requested)
      
      SignedUp.new(user: user, trial: trial, success: true, errors: [])
    end
    
    private
    
    def self.create_trial_if_requested(user, trial_requested)
      return nil unless trial_requested
      
      trial = Trial.create(user: user, expires_at: 30.days.from_now)
      TrialMailer.trial_started(user, trial).deliver_now
      trial
    end
  end
end

🎉 Key Improvements:

• Single responsibility: each use case handles one business process

• Clear input/output contracts using value objects

• Testable business logic separated from framework concerns

• Reusable across different interfaces (web, API, background jobs)

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • Identify your fattest controller action

   • Look for business logic mixed with presentation logic

   • Find repeated business processes across controllers

2. Next Steps

   • Extract one business process into a Use Case Object

   • Create input and output value objects

   • Write comprehensive tests for your use case

Your Turn!

The Use Case Refactoring Challenge

Take this messy controller action and refactor it into a proper Use Case Object:

class OrdersController < ApplicationController
  def create
    @order = Order.new(order_params)
    @order.user = current_user
    
    if @order.save
      @order.items.each do |item|
        item.product.decrement!(:stock_quantity, item.quantity)
      end
      
      OrderMailer.confirmation(@order).deliver_now
      PaymentProcessor.charge(@order.total, @order.payment_method)
      
      redirect_to order_path(@order), notice: 'Order placed!'
    else
      render :new
    end
  end
end

💬 Discussion Prompts:

• What value objects would you create for input and output?

• How would you handle the stock decrement logic?

• What would you name this Use Case Object?

What's Next?

Next week: "Repository Pattern in Ruby: Abstracting Your Data Layer" - We'll explore how to use the Gateway pattern to separate your business logic from ActiveRecord dependencies.

🔧 Useful Resources:

• Hexagonal Architecture Guide

• Clean Architecture by Robert Martin

• Ruby Value Objects

Found this useful? Share it with a fellow developer! And don't forget to try the refactoring challenge above and share your solution.

Share

Happy coding!

Tips and Notes:

• Pro Tip: Start with your most complex controller action when implementing Use Case Objects

• Remember: Use Case Objects should have a single public method (.call) and clear input/output contracts

I was staring at a Patient class that calculated health metrics – BMI, ideal weight, heart rate – all crammed into one massive method. It worked, sure, but it was a nightmare to test, impossible to extend, and frankly, embarrassing to show to other developers.

In this issue, I'll take you through the journey from messy, monolithic methods to clean, testable, maintainable code. No theory dumps – just real code, real problems, and real solutions.

🚀 What you'll learn:

• How to identify code smells that are killing your productivity

• A systematic approach to refactoring without breaking everything

• Why good code isn't just about making it work – it's about making it last

• Practical metrics that actually matter for code quality

The Problem

Here's what we were dealing with – a Patient class that seemed innocent enough:

class Patient
  def initialize(weight, height, age)
    @weight = weight
    @height = height
    @age = age
  end

  def health_metrics
    # BMI calculation
    bmi = (@weight / (@height ** 2)).round(2)
    
    # Ideal weight calculation
    ideal_weight = (22 * (@height ** 2)).round(2)
    
    # Heart rate calculation based on age
    heart_rate = calculate_heart_rate(@age)

    # Returning the health metrics as a hash
    { bmi: bmi, ideal_weight: ideal_weight, heart_rate: heart_rate }
  end

  private

  def calculate_heart_rate(age)
    70 - (age / 10)
  end
end

💡 Warning Signs:

• One method doing three completely different calculations

• Impossible to test individual calculations separately

• Adding new health metrics meant modifying existing code

• Comments explaining what each section does (usually a red flag)

The Journey: From Problem to Solution

Step 1: Recognizing the Code Smell

The first breakthrough came when I ran Reek on this code. The complexity score was off the charts – well above the danger threshold of 10. The tool immediately flagged the health_metrics method for violating the Single Responsibility Principle.

Before:

def health_metrics
  # Three different responsibilities mashed together
  bmi = (@weight / (@height ** 2)).round(2)
  ideal_weight = (22 * (@height ** 2)).round(2)
  heart_rate = calculate_heart_rate(@age)
  { bmi: bmi, ideal_weight: ideal_weight, heart_rate: heart_rate }
end

After:

def health_metrics
  {
    bmi: calculate_bmi,
    ideal_weight: calculate_ideal_weight,
    heart_rate: calculate_heart_rate(@age)
  }
end

private

def calculate_bmi
  (@weight / (@height ** 2)).round(2)
end

def calculate_ideal_weight
  (22 * (@height ** 2)).round(2)
end

🎯 Impact:

• Each calculation became independently testable

• Adding new metrics no longer required modifying existing code

• The main method became a clear orchestrator rather than a do-everything monster

Step 2: Following the Open/Closed Principle

The real aha moment came when I asked: "Can I add a new health metric without modifying existing code?" The answer was still no. So I kept refactoring.

The Aha Moment

The breakthrough happened when I realized that good code isn't just about making it work – it's about making it continue to work as requirements change. The key insight: as production code becomes more generic, tests should become more specific and explicit.

Real Numbers From This Experience

• Before: 1 test for the entire health_metrics method

• After: 4 focused tests, each covering one responsibility

• Test writing time: Reduced from 15 minutes to 3 minutes per new health metric

• Bug detection: Increased from catching issues in production to catching them at compile time

The Final Result

class Patient
  def initialize(weight, height, age)
    @weight = weight
    @height = height
    @age = age
  end

  def health_metrics
    {
      bmi: calculate_bmi,
      ideal_weight: calculate_ideal_weight,
      heart_rate: calculate_heart_rate
    }
  end

  def calculate_bmi
    (@weight / (@height ** 2)).round(2)
  end

  def calculate_ideal_weight
    (22 * (@height ** 2)).round(2)
  end

  def calculate_heart_rate
    (70 - (@age / 10)).round(2)
  end

  private

  attr_reader :weight, :height, :age
end

🎉 Key Improvements:

• Each method has a single, clear responsibility

• Easy to test individual calculations

• Simple to add new health metrics

• Code that's both simple and expressive

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

   • Run a code smell detection tool (like Reek for Ruby) on your current project

   • Identify one method that's doing more than one thing

   • Extract one responsibility into its own private method

2. Next Steps

   • Apply the "Can I implement this change?" test to your recent code

   • Write focused unit tests for each extracted responsibility

   • Establish a complexity threshold (like score > 10) for your team

Your Turn!

The Refactoring Challenge

Here's a method that's crying out for refactoring. Can you spot the code smells?

def process_order(items, customer_type, discount_code)
  total = 0
  items.each { |item| total += item.price * item.quantity }
  
  # Apply customer discount
  if customer_type == 'premium'
    total *= 0.9
  elsif customer_type == 'vip'
    total *= 0.8
  end
  
  # Apply discount code
  if discount_code == 'SAVE10'
    total *= 0.9
  elsif discount_code == 'SAVE20'  
    total *= 0.8
  end
  
  # Calculate tax
  tax = total * 0.08
  final_total = total + tax
  
  # Send confirmation email
  send_email(customer_email, "Order confirmed for $#{final_total}")
  
  final_total
end

💬 Discussion Prompts:

• How many responsibilities can you count in this method?

• What would happen if you needed to add a new customer type?

• How would you test the email sending separately from the calculation?

What's Next?

Next week: "The Testing Trap: Why 100% Coverage Might Be Hurting Your Code" - We'll explore the balance between thorough testing and over-testing, and discover metrics that actually predict code quality.

🔧 Useful Resources:

• Reek gem for Ruby code smell detection

• Martin Fowler's Refactoring Catalog

• SOLID Principles explained with examples

Found this useful? Share it with a fellow developer! And don't forget to reply with your refactoring challenge solution – I read every response.

Happy coding!

Tips and Notes:

• Pro Tip: Start refactoring with the smallest, most obvious extraction – momentum builds confidence

• Remember: Working code isn't the same as good code – good code continues to work as requirements evolve

What started as a straightforward PostgreSQL logical replication for 81 million records became a masterclass in hidden configuration gotchas and operational blind spots.

In this issue, I'll take you through why I ditched database-level replication for a Rails-based migration system that actually works. No theory dumps – just real problems, real solutions, and a migration strategy you can trust.

🚀 What you'll learn:

• Why even "successful" database migrations can be operational disasters

• How to build observable, resumable data migrations with Rails

• When to choose application-level solutions over database features

• A battle-tested migration architecture that eliminates guesswork

The Problem

Here's what we were dealing with: migrating two massive join tables (photo_kids and photo_sections) containing 81+ million records. PostgreSQL logical replication seemed like the obvious choice.

💡 Warning Signs:

• Zero visibility into migration progress during 24+ hour windows

• Configuration timeouts happening at mysterious user-role levels

• Multiple days of debugging for what should be infrastructure-level operations

• No way to resume from failure points without starting over

The Journey: From Problem to Solution

Step 1: Recognizing the Operational Blindness

Before:

After:

🎯 Impact:

• Real-time progress tracking instead of 24-hour blackouts

• Clear batch-level success/failure indicators

• Predictable timeline estimates based on processing rates

Step 2: Building Resilience Into Every Layer

The breakthrough came when I realized that reliability trumps raw performance for large migrations:

The Aha Moment

The key realization hit me during hour 18 of staring at a stuck PostgreSQL process: observability is more valuable than theoretical performance.

When you can't see what's happening, you can't make informed decisions. When you can't resume from failures, you're always one configuration edge case away from starting over.

Real Numbers From This Experience

• Before: 24+ hours with zero progress visibility

• After: Real-time batch completion with <15 minute recovery windows

• Debugging time: 3 days → 0 days (failures are self-explanatory)

• Knowledge dependency: Deep PostgreSQL expertise → Standard Rails patterns

The Final Result

🎉 Key Improvements:

• 100% migration visibility with real-time progress tracking

• Automatic resume from any failure point

• Built-in data integrity validation

• No specialized PostgreSQL expertise required for troubleshooting

Tomorrow Morning Action Items

1. Quick Wins (5-Minute Changes)

• Add progress logging to any existing batch jobs

• Create a simple MigrationStatus model for tracking operations

• Document your current migration procedures (you'll thank yourself later)

2. Next Steps

• Build a small proof-of-concept with 1000 records

• Test failure scenarios and recovery mechanisms

• Integrate with your existing monitoring infrastructure

Your Turn!

The Migration Strategy Challenge

Here's a simplified version of the problem. How would you improve this basic migration approach?

💬 Discussion Prompts:

• What happens if this fails halfway through 1 million records?

• How would you add progress tracking without changing the core logic?

• What's your strategy for validating the migration completed successfully?

🔧 Useful Resources:

• Sidekiq Best Practices Guide

• ActiveRecord Import Gem- for bulk operations

• PostgreSQL Logical Replication Docs

Found this useful? Share it with a fellow developer who's ever been burned by a "simple" database migration! And don't forget to reply with your own migration war stories.

Share

Happy coding!

Tips and Notes:

• Note: All code examples focus on the patterns rather than production-ready implementations

• Pro Tip: Always test your migration rollback strategy before you need it

• Remember: Visibility and reliability beat raw performance for critical operations

You know that moment when you realize your perfectly architected application isn't quite so perfect after all? This was mine.

In this issue, I'll take you through the exact steps we took to transform our struggling Rails app into a high-performance data processing machine. No theory dumps – just real code, real problems, and real solutions.

🚀 What you'll learn:

• How to identify and optimize database bottlenecks with PostgreSQL

• Implementing strategic caching to reduce server load

• Moving processing-intensive tasks to background jobs

The Problem

Our marketplace application had grown from handling hundreds of transactions a day to thousands per hour. What started as occasional slowdowns became consistent performance degradation across the platform.

Here's what we were dealing with:

💡 Warning Signs:

• Page load times exceeding 5 seconds on data-heavy pages

• Database CPU regularly spiking above 85%

• Timeout errors during peak traffic hours

• Exponentially increasing response times as data grew

The Journey: From Problem to Solution

Step 1: Database Optimization with Strategic Indexing

Before:

After:

🎯 Impact:

• Query execution time reduced from 2.3s to 180ms

• Database load reduced by 40%

• Eliminated timeout errors during peak hours

Step 2: Implementing Multi-Level Caching

Before:

After:

🎯 Impact:

• Dashboard load time decreased from 4.2s to 320ms

• Database queries reduced by 85% during peak hours

• Server capacity effectively doubled without hardware changes

Step 3: Moving to Background Processing with Sidekiq

Before:

After:

The Aha Moment

Our breakthrough came when we realized we needed to stop treating Rails like a monolith that does everything synchronously. By intelligently distributing processing across background jobs, caching layers, and optimized database queries, we created a system that scaled with our growth rather than fighting against it.

Real Numbers From This Experience

• Before: 5.2s average response time

• After: 1.1s average response time (78% improvement)

• Database load: Reduced from 92% to 45% average utilization

• Error rate: Dropped from 4.6% to 0.2%

• User capacity: Increased from 5,000 to 22,000 daily active users on same hardware

The Final Result

🎉 Key Improvements:

• Reduced average response time by 78%

• Cut database load in half

• Eliminated timeout errors completely

• Increased system capacity by over 300%

• Improved developer experience with cleaner, more maintainable code

Monday Morning Action Items

1. Quick Wins (5-Minute Changes)

• Add indexes to your most frequently queried columns

• Wrap expensive dashboard calculations in Rails.cache.fetch blocks

• Use includes(:associations) to eliminate N+1 queries

2. Next Steps

• Set up Sidekiq for background processing of non-critical tasks

• Implement fragment caching for your most visited pages

• Consider PostgreSQL materialized views for complex reporting queries

Your Turn!

The Database Optimization Challenge

Take a look at this controller action and identify optimization opportunities:

💬 Discussion Prompts:

• What N+1 query issues do you see in this code?

• Which database indexes would you add to improve performance?

• How would you implement caching for this action?

🔧 Useful Resources:

• PostgreSQL Indexing: How, Why, When

• Sidekiq GitHub Repository

• The Complete Guide to Rails Caching

Found this useful? Share it with a fellow Rails developer! And don't forget to reply with your solution to this week's optimization challenge.

Share

Happy coding!

Pro Tips:

• Use the Bullet gem to automatically detect N+1 queries in development

• Remember: Caching is great, but always have a strategy for cache invalidation to prevent stale data