nats_wave 1.1.13 → 1.1.15

data/README.md

@@ -1,7 +1,6 @@
 # 🌊 NatsWave
 
-A comprehensive NATS-based event messaging system for Rails applications that enables seamless communication between
-different teams, products, and services in asset management and valuation workflows.
+A comprehensive NATS-based event messaging system for Rails applications that enables seamless communication between different teams, products, and services in asset management and valuation workflows.
 
 [![Gem Version](https://badge.fury.io/rb/nats_wave.svg)](https://badge.fury.io/rb/nats_wave)
 [![Build Status](https://github.com/PurpleWave/nats_wave/workflows/CI/badge.svg)](https://github.com/PurpleWave/nats_wave/actions)
@@ -31,18 +30,17 @@ different teams, products, and services in asset management and valuation workfl
 
 ## ✨ Features
 
-- **🚀 Model-Based Configuration** - Configure subscriptions and mappings directly in your models
-- **🔄 Automatic Event Publishing** - ActiveRecord integration publishes model changes automatically
-- **🗺️ Intelligent Data Mapping** - Transform data between different schemas and field names with automatic field
-  mapping
-- **🔀 Cross-Service Synchronization** - Sync data between services with different model names and schemas
-- **🎯 Smart Message Routing** - Route messages based on service origin, model type, and custom conditions
+- **🚀 Streamlined Model Configuration** - Simple, declarative model-based subscriptions and publishing
+- **📤 Smart Publishing** - Automatic event publishing with custom field mappings and transformations
+- **📥 Intelligent Subscriptions** - Auto-sync with custom handlers for complex processing
+- **🗺️ Advanced Data Mapping** - Transform data between different schemas with field mappings and transformations
+- **🔀 Cross-Service Synchronization** - Seamlessly sync data between services with different models and schemas
+- **🎯 Custom Message Handlers** - Optional custom processing after automatic sync operations
 - **📊 Datadog Integration** - Built-in metrics and monitoring support
 - **🛡️ Robust Error Handling** - Dead letter queues, retries, and graceful failure handling
 - **🔧 Middleware System** - Authentication, validation, and logging middleware
 - **⚡ High Performance** - Connection pooling, async publishing, and batch operations
-- **🏥 Health Monitoring** - Built-in health checks and status endpoints
-- **📈 Auto-Discovery** - Automatic registration of model subscriptions via ModelRegistry
+- **🔄 Auto-Reconnection** - Automatic reconnection with exponential backoff and health monitoring
 - **🧪 Test-Friendly** - Comprehensive test helpers and mocking support
 
 ## 📦 Installation
@@ -51,6 +49,7 @@ Add this line to your Rails application's Gemfile:
 
 ```ruby
 gem 'nats_wave'
+gem 'nats', '~> 0.11' # NATS Ruby client
 
 # Optional: For enhanced monitoring
 gem 'dogstatsd-ruby' # For Datadog metrics
@@ -66,7 +65,6 @@ Generate the configuration files:
 
 ```bash
 rails generate nats_wave:install
-rails db:migrate
 ```
 
 ## 🚀 Quick Start
@@ -76,17 +74,16 @@ rails db:migrate
 ```ruby
 # config/initializers/nats_wave.rb
 NatsWave.configure do |config|
-    config.nats_url = ENV.fetch('NATS_URL', 'nats://localhost:4222')
-    config.service_name = 'valuation_service'
-    config.default_subject_prefix = "#{config.service_name}.events"
-    
-    # Publishing
-    config.publishing_enabled = !Rails.env.test?
-    config.async_publishing = Rails.env.production?
-    
-    # Subscription  
-    config.subscription_enabled = !Rails.env.test?
-    config.queue_group = "#{config.service_name}_consumers"
+  config.nats_url = ENV.fetch('NATS_URL', 'nats://localhost:4222')
+  config.service_name = ENV.fetch('NATS_SERVICE_NAME', 'valuation_service')
+  
+  # Publishing
+  config.publishing_enabled = !Rails.env.test?
+  config.async_publishing = Rails.env.production?
+  
+  # Subscription  
+  config.subscription_enabled = !Rails.env.test?
+  config.queue_group = "#{config.service_name}_consumers"
 end
 ```
 
@@ -95,78 +92,86 @@ end
 ```ruby
 # app/models/asset.rb
 class Asset < ApplicationRecord
-    include NatsWave::NatsPublishable
-    include NatsWave::Concerns::Mappable
-    
-    # Automatically publish asset events
-    nats_publishable(
-            actions: [:create, :update, :destroy],
-            skip_attributes: [:notes, :edge_data],
-            include_associations: [:package, :estimates],
-            subject_prefix: 'assets'
-    )
-    
-    # Map from external inventory system  
-    nats_wave_maps_from 'InventoryItem',
-                        field_mappings: {
-                                'item_id' => 'unique_id',
-                                'description' => 'description',
-                                'manufacturer' => 'make',
-                                'model_name' => 'model',
-                                'year_manufactured' => 'year',
-                                'serial_number' => 'serial',
-                                'vin_number' => 'vin'
-                        },
-                        transformations: {
-                                'make' => ->(make) { make&.upcase&.strip },
-                                'year' => ->(year) { year.to_i if year.present? },
-                                'estimated_hammer' => ->(value) { value.to_f.round(2) }
-                        },
-                        unique_fields: [:unique_id, :vin, :serial],
-                        sync_strategy: :upsert,
-                        subjects: ['inventory_service.items.*']
-    
-    # Subscribe to external asset events with custom handling
-    nats_wave_subscribes_to "auction_service.assets.*" do |message|
-        AuctionAssetProcessor.process(message)
+  include NatsWave::Concerns::Mappable
+  
+  # Subscribe to external inventory system - auto-sync + custom handler
+  nats_wave_subscribes_to "inventory_service.items.*",
+    field_mappings: {
+      'item_id' => 'unique_id',
+      'description' => 'description',
+      'manufacturer' => 'make',
+      'model_name' => 'model',
+      'year_manufactured' => 'year',
+      'serial_number' => 'serial'
+    },
+    transformations: {
+      'make' => ->(make) { make&.upcase&.strip },
+      'year' => ->(year) { year.to_i if year.present? }
+    },
+    unique_fields: [:unique_id],
+    skip_fields: ['internal_notes'] do |model_name, action, processed_data, message|
+      # Custom handler runs AFTER auto-sync
+      Rails.logger.info "📨 Processed #{action} for #{model_name}: #{processed_data[:unique_id]}"
+      
+      # Custom logic here
+      if action == 'create' && processed_data[:estimated_value].blank?
+        ValuationRequestJob.perform_later(processed_data[:unique_id])
+      end
+    end
+  
+  # Publish asset changes to other services
+  nats_wave_publishes_to "#{ENV['NATS_SERVICE_NAME']}.assets.{action}",
+    field_mappings: {
+      'unique_id' => 'asset_id',
+      'make' => 'manufacturer',
+      'model' => 'model_name'
+    },
+    transformations: {
+      'created_at' => lambda(&:iso8601),
+      'updated_at' => lambda(&:iso8601),
+      'estimated_hammer' => ->(cents) { cents.to_f / 100 }
+    },
+    skip_fields: %w[notes edge_data source_data],
+    actions: %i[create update] do |model_name, action, published_data, record|
+      # Custom handler runs AFTER publishing
+      Rails.logger.info "📤 Published #{action} for #{model_name}: #{record.id}"
+      
+      # Send notifications, update caches, etc.
+      if action == 'update' && record.valuation_complete?
+        NotificationService.notify_valuation_complete(record)
+      end
     end
 end
 ```
 
 ### 3. Start the Subscriber
 
-The subscriber automatically starts with Rails and processes registered model subscriptions:
+The subscriber automatically starts with Rails:
 
 ```bash
-# Development - auto-starts with Rails
+# Development - auto-starts with Rails server
 rails server
 
 # You'll see logs like:
-# I, [2025-07-21T12:10:35.910694 #29]  INFO -- : Starting NATS subscriber for valuation_service
-# I, [2025-07-21T12:10:35.911316 #29]  INFO -- : ✅ Successfully subscribed to inventory_service.items.* (total: 1)
-# I, [2025-07-21T12:10:35.912749 #29]  INFO -- : Started 3 subscriptions from Model Registry
+# I, [2025-01-21T12:10:35.910694 #29]  INFO -- : Starting NATS subscriber for valuation_service
+# I, [2025-01-21T12:10:35.911316 #29]  INFO -- : ✅ Successfully subscribed to inventory_service.items.*
+# I, [2025-01-21T12:10:35.912749 #29]  INFO -- : Started 3 subscriptions from Model Registry
 
-# Production - run dedicated subscriber process
-rails nats_wave:start
+# Production - run dedicated subscriber process if needed
+bundle exec rake nats_wave:start
 ```
 
 ### 4. Test the Integration
 
 ```bash
 # Test connectivity
-rails nats_wave:health
-
-# Show model subscriptions  
-rails nats_wave:model_subscriptions
+rails runner "puts NatsWave.health_check"
 
 # Publish a test message
 rails console
-> NatsWave.publish(
-    subject: 'assets.create',
-    model: 'Asset', 
-    action: 'create',
-    data: { id: 123, make: 'Caterpillar', model: '320D' }
-  )
+> asset = Asset.first
+> asset.update!(make: 'Updated Manufacturer')
+# This automatically publishes via nats_wave_publishes_to
 ```
 
 ## ⚙️ Configuration
@@ -176,13 +181,10 @@ rails console
 ```bash
 # Required
 NATS_URL=nats://your-nats-server:4222
-
-# Optional - defaults to Rails application name
 NATS_SERVICE_NAME=valuation_service
 
 # Optional Authentication & Security
 NATS_AUTH_SECRET=your-secret-key
-SCHEMA_REGISTRY_URL=http://schema-registry:8081
 
 # Optional Monitoring
 DD_AGENT_HOST=localhost  # For Datadog metrics
@@ -191,484 +193,251 @@ DD_AGENT_PORT=8125
 
 ### Complete Configuration Setup
 
-Create or update `config/initializers/nats_wave.rb`:
-
 ```ruby
-# frozen_string_literal: true
-
+# config/initializers/nats_wave.rb
 begin
-    Rails.logger.info "Initializing NATS Wave with URL: #{ENV['NATS_URL']}"
+  Rails.logger.info "Initializing NATS Wave..."
+  
+  NatsWave.configure do |config|
+    # === CORE CONNECTION SETTINGS ===
+    config.nats_url = ENV.fetch('NATS_URL', 'nats://localhost:4222')
+    config.service_name = ENV.fetch('NATS_SERVICE_NAME', 
+                                  Rails.application.class.name.deconstantize.underscore)
+    config.connection_pool_size = 10
+    config.reconnect_attempts = 3
     
-    NatsWave.configure do |config|
-        # === CORE CONNECTION SETTINGS ===
-        config.nats_url = ENV.fetch('NATS_URL', 'nats://localhost:4222')
-        config.service_name = ENV.fetch('NATS_SERVICE_NAME',
-                                        Rails.application.class.name.deconstantize.underscore)
-        config.connection_pool_size = 10
-        config.reconnect_attempts = 3
-        
-        Rails.logger.info "NATS URL: #{config.nats_url}"
-        Rails.logger.info "Service Name: #{config.service_name}"
-        
-        # === PUBLISHING CONFIGURATION ===
-        config.publishing_enabled = !Rails.env.test? # Disable in test environment
-        config.async_publishing = Rails.env.production? # Async only in production
-        config.default_subject_prefix = config.service_name # Use service name as prefix
-        
-        # === SUBSCRIPTION CONFIGURATION ===
-        config.subscription_enabled = !Rails.env.test? # Disable in test environment
-        config.queue_group = "#{config.service_name}_consumers" # Queue group for load balancing
-        
-        # === ERROR HANDLING ===
-        config.max_retries = 3 # Max retry attempts
-        config.retry_delay = 5 # Base retry delay in seconds
-        config.dead_letter_queue = "failed_messages" # Failed message storage
-        
-        # === AUTHENTICATION (Optional) ===
-        if ENV['NATS_AUTH_SECRET'].present?
-            config.middleware_authentication_enabled = true
-            config.auth_secret_key = ENV['NATS_AUTH_SECRET']
-        end
-        
-        # === VALIDATION (Optional) ===
-        if ENV['SCHEMA_REGISTRY_URL'].present?
-            config.middleware_validation_enabled = true
-            config.schema_registry_url = ENV['SCHEMA_REGISTRY_URL']
-        end
-        
-        # === LOGGING ===
-        config.middleware_logging_enabled = true
-        config.log_level = Rails.env.production? ? 'info' : 'debug'
+    # === PUBLISHING CONFIGURATION ===
+    config.publishing_enabled = !Rails.env.test?
+    config.async_publishing = Rails.env.production?
+    
+    # === SUBSCRIPTION CONFIGURATION ===
+    config.subscription_enabled = !Rails.env.test?
+    config.queue_group = "#{config.service_name}_consumers"
+    
+    # === ERROR HANDLING ===
+    config.max_retries = 3
+    config.retry_delay = 5
+    config.dead_letter_queue = "failed_messages"
+    
+    # === AUTHENTICATION (Optional) ===
+    if ENV['NATS_AUTH_SECRET'].present?
+      config.middleware_authentication_enabled = true
+      config.auth_secret_key = ENV['NATS_AUTH_SECRET']
     end
     
-    Rails.logger.info "NATS Wave configuration completed successfully"
+    # === LOGGING ===
+    config.middleware_logging_enabled = true
+    config.log_level = Rails.env.production? ? 'info' : 'debug'
+  end
+  
+  Rails.logger.info "✅ NATS Wave configuration completed successfully"
 rescue => e
-    Rails.logger.error "Failed to configure NATS Wave: #{e.message}"
-    Rails.logger.error e.backtrace.join("\n")
-    
-    # Optional: Re-raise in development to catch configuration issues early
-    raise e if Rails.env.development?
+  Rails.logger.error "❌ Failed to configure NATS Wave: #{e.message}"
+  raise e if Rails.env.development?
 end
 
 # === AUTOMATIC SUBSCRIBER STARTUP ===
 Rails.application.config.after_initialize do
-    Thread.new do
-        sleep 2 # Give Rails time to boot and load all models
-        begin
-            # Start subscriber - this will automatically process all registered model subscriptions
-            NatsWave.start_subscriber
-            Rails.logger.info "✅ NatsWave subscriber started successfully"
-            
-            # Optional: Log subscription statistics
-            stats = NatsWave::ModelRegistry.subscription_stats
-            Rails.logger.info "📊 Active subscriptions: #{stats[:total_subscriptions]} across #{stats[:models_with_subscriptions]} models"
-        
-        rescue StandardError => e
-            Rails.logger.error "Failed to start NatsWave subscriber: #{e.message}"
-            Rails.logger.error e.backtrace.join("\n")
-            
-            # Optional: Alert monitoring systems
-            if defined?(Sentry)
-                Sentry.capture_exception(e, tags: { component: 'nats_wave_startup' })
-            end
-        end
-    end
-end
-
-# === DATADOG METRICS INTEGRATION (Optional) ===
-if defined?(Datadog::Statsd) && !Rails.env.test?
-    # Get application version safely
-    app_version = begin
-                      Rails.application.config.version
-                  rescue
-                      'unknown'
-                  end
+  Thread.new do
+    sleep 2 # Give Rails time to boot and load all models
+    begin
+      NatsWave.start_subscriber
+      Rails.logger.info "✅ NatsWave subscriber started successfully"
+      
+      # Log subscription statistics
+      stats = NatsWave::ModelRegistry.subscription_stats
+      Rails.logger.info "📊 Active subscriptions: #{stats[:total_subscriptions]} across #{stats[:models_with_subscriptions]} models"
     
-    NatsWave::Metrics.configure_datadog(
-            namespace: "#{Rails.application.class.name.deconstantize.underscore}.nats_wave",
-            tags: {
-                    service: NatsWave.configuration.service_name,
-                    environment: Rails.env,
-                    version: app_version
-            }
-    )
-    Rails.logger.info "📈 Datadog metrics integration enabled"
+    rescue StandardError => e
+      Rails.logger.error "❌ Failed to start NatsWave subscriber: #{e.message}"
+      
+      # Optional: Alert monitoring systems
+      Sentry.capture_exception(e) if defined?(Sentry)
+    end
+  end
 end
 
-# === GRACEFUL SHUTDOWN (Optional) ===
+# === GRACEFUL SHUTDOWN ===
 at_exit do
-    begin
-        if defined?(NatsWave) && NatsWave.client
-            Rails.logger.info "🛑 Shutting down NatsWave connections..."
-            NatsWave.client.disconnect!
-            Rails.logger.info "✅ NatsWave shutdown complete"
-        end
-    rescue => e
-        Rails.logger.error "Error during NatsWave shutdown: #{e.message}"
+  begin
+    if defined?(NatsWave) && NatsWave.client
+      Rails.logger.info "🛑 Shutting down NatsWave connections..."
+      NatsWave.client.disconnect!
+      Rails.logger.info "✅ NatsWave shutdown complete"
     end
+  rescue => e
+    Rails.logger.error "Error during NatsWave shutdown: #{e.message}"
+  end
 end
 ```
 
-### Environment-Specific Configuration
+## 🏗️ Model-Based Architecture
 
-#### Development Environment
+NatsWave uses a streamlined model-centric approach where each model defines its own subscriptions and publishing through the **ModelRegistry** system.
 
-```ruby
-# config/environments/development.rb
-config.after_initialize do
-    if defined?(NatsWave)
-        # Enable debug logging in development
-        NatsWave.logger.level = Logger::DEBUG
-        
-        # Optional: Show all registered subscriptions on startup
-        if NatsWave::ModelRegistry.subscriptions.any?
-            Rails.logger.info "🔍 Registered NATS subscriptions:"
-            NatsWave::ModelRegistry.subscriptions.each do |subscription|
-                Rails.logger.info "  📡 #{subscription[:model]} -> #{subscription[:subjects].join(', ')}"
-            end
-        end
-    end
-end
-```
+### Core Concepts
 
-#### Production Environment
+- **Auto-Sync**: Automatic field mapping and database synchronization
+- **Custom Handlers**: Optional custom processing after auto-sync or publishing
+- **Field Mappings**: Transform field names between external and local models
+- **Transformations**: Apply data transformations during sync/publish
+- **Unique Fields**: Define how to find existing records for updates
 
-```ruby
-# config/environments/production.rb
-config.after_initialize do
-    if defined?(NatsWave)
-        # Enable authentication in production
-        NatsWave.configuration.middleware_authentication_enabled = true
-        
-        # Set production logging level
-        NatsWave.logger.level = Logger::INFO
-        
-        # Enable health check endpoint
-        Rails.application.routes.draw do
-            get '/health/nats_wave', to: 'health#nats_wave'
-        end
-    end
-end
-```
+## 📤 Publishing Events
 
-#### Test Environment
+### Automatic Publishing with Custom Processing
 
 ```ruby
-# config/environments/test.rb or spec/spec_helper.rb
-RSpec.configure do |config|
-    config.before(:suite) do
-        # Clear ModelRegistry before tests
-        NatsWave::ModelRegistry.clear! if defined?(NatsWave::ModelRegistry)
-    end
-    
-    config.before(:each) do
-        # Mock NATS operations in tests
-        if defined?(NatsWave)
-            allow(NatsWave.client).to receive(:publish).and_return(true)
-            allow(NatsWave.client).to receive(:subscribe).and_return(true)
-        end
+class Package < ApplicationRecord
+  include NatsWave::Concerns::Mappable
+  
+  # Publish package events with field mapping and custom processing
+  nats_wave_publishes_to "#{ENV['NATS_SERVICE_NAME']}.packages.{action}",
+    field_mappings: {
+      'id' => 'package_id',
+      'key' => 'package_key',
+      'owner_name' => 'client_name',
+      'workflow_status' => 'status'
+    },
+    transformations: {
+      'created_at' => lambda(&:iso8601),
+      'updated_at' => lambda(&:iso8601),
+      'workflow_status' => ->(status) { status&.upcase }
+    },
+    skip_fields: %w[notes source_data edge_data],
+    actions: %i[create update] do |model_name, action, published_data, record|
+      # Custom processing AFTER publishing
+      Rails.logger.info "📤 Published #{action} for #{model_name}: #{record.key}"
+      
+      # Notify related services
+      if action == 'update' && record.workflow_status_changed?
+        WorkflowNotificationService.notify_status_change(record)
+      end
+      
+      # Update search indexes
+      SearchIndexUpdateJob.perform_later(record.id, 'Package') if action == 'update'
     end
 end
 ```
 
-### Configuration Options Reference
-
-| Option                              | Default                 | Description                     |
-|-------------------------------------|-------------------------|---------------------------------|
-| `nats_url`                          | `nats://localhost:4222` | NATS server connection URL      |
-| `service_name`                      | Rails app name          | Unique service identifier       |
-| `connection_pool_size`              | `10`                    | Max concurrent NATS connections |
-| `reconnect_attempts`                | `3`                     | Auto-reconnect attempts         |
-| `publishing_enabled`                | `!Rails.env.test?`      | Enable/disable publishing       |
-| `async_publishing`                  | `Rails.env.production?` | Publish asynchronously          |
-| `subscription_enabled`              | `!Rails.env.test?`      | Enable/disable subscriptions    |
-| `queue_group`                       | `{service}_consumers`   | NATS queue group name           |
-| `max_retries`                       | `3`                     | Failed message retry attempts   |
-| `retry_delay`                       | `5`                     | Base retry delay (seconds)      |
-| `middleware_authentication_enabled` | `false`                 | Enable auth middleware          |
-| `middleware_validation_enabled`     | `false`                 | Enable validation middleware    |
-| `middleware_logging_enabled`        | `true`                  | Enable logging middleware       |
-
-### Health Check Endpoint
-
-Add a health check endpoint to monitor NatsWave status:
+### Dynamic Subject Generation
 
 ```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-    # ... your other routes
-    get '/health/nats_wave', to: 'health#nats_wave'
-end
-
-# app/controllers/health_controller.rb
-class HealthController < ApplicationController
-    def nats_wave
-        health_data = NatsWave.health_check
-        
-        if health_data[:nats_connected]
-            render json: health_data, status: :ok
-        else
-            render json: health_data.merge(error: 'NATS not connected'), status: :service_unavailable
-        end
-    rescue => e
-        render json: {
-                error: e.message,
-                nats_connected: false,
-                timestamp: Time.current.iso8601
-        }, status: :service_unavailable
-    end
-end
-```
-
-### Docker Environment Configuration
-
-```yaml
-# docker-compose.yml
-version: '3.8'
-services:
-  nats:
-    image: nats:latest
-    ports:
-      - "4222:4222"
-      - "8222:8222" # Management interface
-    command: "--http_port 8222 --js"
-
-  app:
-    build: .
-    depends_on:
-      - nats
-      - postgres
-      - redis
-    environment:
-      - NATS_URL=nats://nats:4222
-      - NATS_SERVICE_NAME=valuation_service
-      - NATS_AUTH_SECRET=your-secret-key
-      - DD_AGENT_HOST=datadog-agent
-    ports:
-      - "3000:3000"
-    healthcheck:
-      test: [ "CMD", "curl", "-f", "http://localhost:3000/health/nats_wave" ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-```
-
-### Kubernetes ConfigMap
-
-```yaml
-# k8s/nats-wave-config.yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: nats-wave-config
-data:
-  NATS_URL: "nats://nats-cluster:4222"
-  NATS_SERVICE_NAME: "valuation-service"
----
-apiVersion: v1
-kind: Secret
-metadata:
-  name: nats-wave-secrets
-type: Opaque
-data:
-  NATS_AUTH_SECRET: <base64-encoded-secret>
+# Use {action} placeholder for dynamic subjects
+nats_wave_publishes_to "#{ENV['NATS_SERVICE_NAME']}.assets.{action}"
+# Creates: valuation_service.assets.create, valuation_service.assets.update, etc.
+
+# Multiple subject patterns
+nats_wave_publishes_to [
+  "#{ENV['NATS_SERVICE_NAME']}.assets.{action}",
+  "global.assets.{action}",
+  "audit.asset_changes"
+]
 ```
 
-## 🏗️ Model-Based Architecture
-
-NatsWave uses a model-centric approach where each model defines its own subscriptions and mappings through the *
-*ModelRegistry** system.
-
-### Publishing Events
+### Conditional Publishing
 
 ```ruby
-
-class Package < ApplicationRecord
-    include NatsWave::NatsPublishable
-    
-    nats_publishable(
-            actions: [:create, :update], # Which actions to publish
-            skip_attributes: [:notes, :valuation_notes], # Attributes to exclude
-            include_associations: [:organization, :assets, :contact_user], # Include related data
-            if: -> { workflow_status == 'active' }, # Conditional publishing
-            unless: -> { is_shared? }, # Skip conditions
-            subject_prefix: 'packages' # Custom subject prefix
-    )
-    
-    private
-    
-    # Add custom metadata to published events
-    def nats_wave_metadata
-        {
-                organization_name: organization&.name,
-                asset_count: assets.count,
-                total_estimated_value: assets.sum(&:estimated_hammer),
-                valuation_complete: valuation_complete?
-        }
+nats_wave_publishes_to "inventory.assets.{action}",
+  actions: %i[create update],
+  # Add conditions in the custom handler
+  skip_fields: %w[internal_notes] do |model_name, action, published_data, record|
+    # Only process if certain conditions are met
+    if record.asset_status == 'active' && !record.is_internal?
+      Rails.logger.info "📤 Published #{action} for active asset: #{record.id}"
+      
+      # Custom processing here
+      ExternalInventoryService.sync_asset(record)
+    else
+      Rails.logger.debug "⏭️ Skipped publishing for #{record.id} (inactive or internal)"
     end
-end
+  end
 ```
 
-### Subscribing to External Events
+## 📥 Subscribing to Events
 
-```ruby
+### Auto-Sync with Custom Processing
 
+```ruby
 class Asset < ApplicationRecord
-    include NatsWave::Concerns::Mappable
-    
-    # Map from inventory management system
-    nats_wave_maps_from 'InventoryAsset',
-                        field_mappings: {
-                                'inventory_id' => 'unique_id',
-                                'asset_description' => 'description',
-                                'manufacturer' => 'make',
-                                'model_number' => 'model',
-                                'year_built' => 'year',
-                                'serial_num' => 'serial',
-                                'vin_code' => 'vin',
-                                'location_code' => 'location'
-                        },
-                        transformations: {
-                                'make' => ->(make) { make&.upcase&.strip },
-                                'model' => ->(model) { model&.titleize&.strip },
-                                'year' => ->(year) { year.to_i if year.present? },
-                                'estimated_hammer' => ->(value) { value.to_f.round(2) }
-                        },
-                        unique_fields: [:unique_id, :vin, :serial],
-                        sync_strategy: :upsert,
-                        conditions: {
-                                'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }, # Do not process event messages on your server
-                                'status' => 'available',
-                                'condition' => ['good', 'fair', 'excellent']
-                        },
-                        subjects: ['inventory_service.assets.*', 'warehouse_service.assets.*']
-    
-    # Map from auction system (different external model name)
-    nats_wave_maps_from 'AuctionItem',
-                        field_mappings: {
-                                'lot_number' => 'lot_number',
-                                'hammer_price' => 'pw_contract_price',
-                                'sale_date' => 'pw_contract_date'
-                        },
-                        conditions: {
-                                'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }, # Do not process event messages on your server
-                                'auction_status' => 'sold'
-                        },
-                        subjects: ['auction_service.items.*']
-    
-    # Custom subscription with handler
-    nats_wave_subscribes_to "market_service.prices.*" do |message|
-        MarketPriceService.update_asset_estimates(message)
+  include NatsWave::Concerns::Mappable
+  
+  # Subscribe to inventory system - auto-sync + custom processing
+  nats_wave_subscribes_to "inventory_service.items.*", "warehouse_service.assets.*",
+    field_mappings: {
+      'item_id' => 'unique_id',
+      'description' => 'description', 
+      'manufacturer' => 'make',
+      'model_name' => 'model',
+      'year_manufactured' => 'year',
+      'serial_number' => 'serial',
+      'vin_number' => 'vin',
+      'estimated_value' => 'estimated_hammer'
+    },
+    transformations: {
+      'make' => ->(make) { make&.upcase&.strip },
+      'model' => ->(model) { model&.titleize&.strip },
+      'year' => ->(year) { year.to_i if year.present? },
+      'estimated_hammer' => ->(value) { (value.to_f * 100).round }, # Convert to cents
+      'asset_status' => ->(status) { status&.downcase || 'active' }
+    },
+    unique_fields: [:unique_id, :vin, :serial],
+    skip_fields: ['internal_inventory_code', 'warehouse_location'] do |model_name, action, processed_data, message|
+      # Custom handler runs AFTER auto-sync
+      Rails.logger.info "📨 Auto-synced #{action} for #{model_name}: #{processed_data[:unique_id]}"
+      
+      case action
+      when 'create'
+        # Request valuation for new assets
+        if processed_data[:estimated_hammer].blank?
+          ValuationRequestJob.perform_later(processed_data[:unique_id])
+        end
+        
+        # Download images
+        if message.dig('data', 'image_urls').present?
+          ImageDownloadJob.perform_later(processed_data[:unique_id], message['data']['image_urls'])
+        end
+        
+      when 'update'
+        # Check for significant changes
+        if processed_data[:estimated_hammer] != message.dig('previous_data', 'estimated_value')
+          AssetValueChangeNotificationJob.perform_later(processed_data[:unique_id])
+        end
+        
+      when 'delete', 'destroy'
+        # Clean up related data
+        CleanupAssetDataJob.perform_later(processed_data[:unique_id])
+      end
+      
+      # Update search index
+      SearchIndexUpdateJob.perform_later(processed_data[:unique_id], 'Asset')
     end
 end
 ```
 
-## 📤 Publishing Events
-
-### Automatic Publishing
-
-Events are automatically published when you include `NatsPublishable`:
-
-```ruby
-# This automatically publishes to "valuation_service.events.assets.create"
-asset = Asset.create!(
-        make: "Caterpillar",
-        model: "320D",
-        year: 2018,
-        serial: "ABC123456",
-        description: "Excavator - Track Type"
-)
-
-# This publishes to "valuation_service.events.assets.update"
-asset.update!(estimated_hammer: 125000)
-
-# This publishes to "valuation_service.events.assets.destroy" 
-asset.destroy!
-```
-
-### Manual Publishing
+### Pure Custom Handlers (No Auto-Sync)
 
 ```ruby
-# Publish custom valuation events
-NatsWave.publish(
-        subject: 'valuation.completed',
-        model: 'ValuationSession',
-        action: 'complete',
-        data: {
-                package_id: package.id,
-                asset_count: package.assets.count,
-                total_value: package.total_estimated_value,
-                appraiser_id: current_user.id
-        },
-        metadata: {
-                organization_id: package.organization.id,
-                completion_time: Time.current,
-                valuation_method: 'comparative_analysis'
-        }
-)
-
-# Batch publishing for performance
-events = assets.map do |asset|
-    {
-            subject: 'asset.valued',
-            model: 'Asset',
-            action: 'update',
-            data: asset.attributes.except('notes', 'edge_data')
-    }
+class User < ApplicationRecord
+  include NatsWave::Concerns::Mappable
+  
+  # Custom handler only - no auto-sync
+  nats_wave_subscribes_to "auth_service.user_sessions.*" do |model_name, action, processed_data, message|
+    # Pure custom processing - no database sync
+    case action
+    when 'login'
+      UserActivityTracker.track_login(message['data']['user_id'], message['data']['ip_address'])
+      Rails.cache.write("user_session:#{message['data']['user_id']}", message['data']['session_token'], expires_in: 1.hour)
+      
+    when 'logout'
+      UserActivityTracker.track_logout(message['data']['user_id'])
+      Rails.cache.delete("user_session:#{message['data']['user_id']}")
+      
+    when 'password_reset'
+      UserMailer.password_reset_notification(message['data']['user_id']).deliver_later
+    end
+  end
 end
-
-NatsWave.client.publish_batch(events)
-```
-
-## 📥 Subscribing to Events
-
-### Automatic Model Syncing with Field Mapping
-
-When you configure `nats_wave_maps_from`, NatsWave automatically:
-
-1. **Registers the subscription** in the ModelRegistry
-2. **Subscribes to specified subjects** when the application starts
-3. **Transforms incoming data** using field mappings and transformations
-4. **Applies conditions** to filter which messages to process
-5. **Syncs data** to your local models using the specified strategy
-
-```ruby
-# Example: Incoming message from inventory system
-{
-        "subject": "inventory_service.assets.update",
-        "model": "InventoryAsset",
-        "action": "update",
-        "data": {
-                "inventory_id": "INV-2024-001",
-                "asset_description": "2020 Ford F-150 Pickup Truck",
-                "manufacturer": "ford",
-                "model_number": "F-150",
-                "year_built": "2020",
-                "serial_num": "1FTFW1ET5LFA12345",
-                "vin_code": "1FTFW1ET5LFA12345",
-                "estimated_value": 35000.00,
-                "status": "available"
-        },
-        "source": {
-                "service": "inventory_service",
-                "instance_id": "inv-worker-1"
-        }
-}
-
-# NatsWave automatically transforms this to:
-{
-        "unique_id": "INV-2024-001",
-        "description": "2020 Ford F-150 Pickup Truck",
-        "make": "FORD", # Uppercased via transformation
-        "model": "F-150",
-        "year": 2020, # Converted to integer
-        "serial": "1FTFW1ET5LFA12345",
-        "vin": "1FTFW1ET5LFA12345",
-        "estimated_hammer": 35000.00
-}
-
-# And creates/updates the local Asset record using unique_fields [:unique_id, :vin, :serial]
 ```
 
 ## 🗺️ Data Mapping & Transformation
@@ -676,246 +445,255 @@ When you configure `nats_wave_maps_from`, NatsWave automatically:
 ### Complete Field Mapping Options
 
 ```ruby
-nats_wave_maps_from 'ExternalModel',
-                    # === FIELD MAPPINGS ===  
-                    field_mappings: {
-                            'external_field' => 'local_field',
-                            'their_id' => 'external_id',
-                            'their_name' => 'title',
-                            'created_timestamp' => 'created_at'
-                    },
-                    
-                    # === DATA TRANSFORMATIONS ===
-                    transformations: {
-                            'created_at' => :parse_timestamp, # Method call
-                            'make' => ->(value) { value&.upcase&.strip }, # Lambda  
-                            'year' => ->(year) { year.to_i if year.present? },
-                            'price' => :convert_to_cents, # Custom method
-                            'status' => ->(val, record) { "#{record['prefix']}_#{val}" } # With record access
-                    },
-                    
-                    # === CONDITIONAL SYNC ===
-                    conditions: {
-                            'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }, # Do not process event messages on your server
-                            'status' => 'active', # Exact match
-                            'service_type' => ['premium', 'basic'], # Array inclusion  
-                            'value' => ->(val) { val.to_f > 1000 }, # Custom logic
-                            'category' => /^(vehicle|equipment)$/ # Regex match
-                    },
-                    
-                    # === SYNC STRATEGY ===
-                    sync_strategy: :upsert, # Options: :upsert, :create_only, :update_only
-                    
-                    # === UNIQUE IDENTIFICATION === 
-                    unique_fields: [:external_id, :vin, :serial], # Fields to find existing records
-                    
-                    # === SKIP FIELDS ===
-                    skip_fields: [:internal_notes, :secret_key], # Fields to ignore
-                    
-                    # === SUBSCRIPTION CONFIGURATION ===
-                    subjects: [
-                            'inventory_service.items.*',
-                            'warehouse_service.assets.*',
-                            'external_api.inventory.*'
-                    ]
+nats_wave_subscribes_to "external_service.models.*",
+  # === FIELD MAPPINGS ===  
+  field_mappings: {
+    'external_field' => 'local_field',
+    'their_id' => 'external_id',
+    'their_name' => 'title',
+    'created_timestamp' => 'created_at',
+    'nested.field.value' => 'flattened_value' # Flatten nested fields
+  },
+  
+  # === DATA TRANSFORMATIONS ===
+  transformations: {
+    'created_at' => :parse_timestamp, # Method call
+    'make' => ->(value) { value&.upcase&.strip }, # Lambda  
+    'year' => ->(year) { year.to_i if year.present? },
+    'price' => :convert_to_cents, # Custom method
+    'status' => ->(val, record) { "#{record['prefix']}_#{val}" }, # With record access
+    'tags' => ->(tags) { tags.is_a?(Array) ? tags.join(',') : tags } # Array handling
+  },
+  
+  # === UNIQUE IDENTIFICATION === 
+  unique_fields: [:external_id, :vin, :serial], # Fields to find existing records
+  
+  # === SKIP FIELDS ===
+  skip_fields: [:internal_notes, :secret_key] # Fields to ignore completely
 ```
 
 ### Advanced Transformations
 
 ```ruby
-
 class Asset < ApplicationRecord
-    include NatsWave::Concerns::Mappable
-    
-    nats_wave_maps_from 'ExternalAsset',
-                        transformations: {
-                                # Simple lambda transformations
-                                'estimated_hammer' => ->(value) { value.to_f.round(2) },
-                                'make' => ->(make) { make&.upcase&.strip },
-                                
-                                # Method transformations
-                                'vin' => :normalize_vin,
-                                'serial' => :normalize_serial,
-                                
-                                # Complex transformations with full record access
-                                'description' => ->(value, record) {
-                                    "#{record['year']} #{record['make']} #{record['model']} #{value}".strip
-                                },
-                                
-                                # Conditional transformations
-                                'condition' => ->(condition) {
-                                    case condition&.downcase
-                                        when 'excellent', 'like new' then 'excellent'
-                                        when 'good', 'fair' then 'good'
-                                        when 'poor', 'needs repair' then 'poor'
-                                        else 'unknown'
-                                    end
-                                }
-                        }
-    
-    private
-    
-    def self.normalize_vin(vin)
-        vin&.upcase&.gsub(/[^A-Z0-9]/, '')&.strip
-    end
-    
-    def self.normalize_serial(serial)
-        serial&.upcase&.strip&.gsub(/\s+/, '')
-    end
-    
-    def self.parse_timestamp(timestamp)
-        return nil if timestamp.blank?
-        Time.parse(timestamp.to_s)
-    rescue ArgumentError
+  include NatsWave::Concerns::Mappable
+  
+  nats_wave_subscribes_to "external_assets.*",
+    transformations: {
+      # Simple lambda transformations
+      'estimated_hammer' => ->(value) { value.to_f.round(2) },
+      'make' => ->(make) { make&.upcase&.strip },
+      
+      # Method transformations
+      'vin' => :normalize_vin,
+      'serial' => :normalize_serial,
+      
+      # Complex transformations with full record access
+      'description' => ->(value, record) {
+        parts = [record['year'], record['make'], record['model'], value].compact
+        parts.join(' ').strip
+      },
+      
+      # Conditional transformations
+      'condition' => ->(condition) {
+        case condition&.downcase
+        when 'excellent', 'like new' then 'excellent'
+        when 'good', 'fair' then 'good'  
+        when 'poor', 'needs repair' then 'poor'
+        else 'unknown'
+        end
+      },
+      
+      # Date/time parsing
+      'manufactured_date' => ->(date_str) {
+        return nil if date_str.blank?
+        Date.parse(date_str.to_s)
+      rescue ArgumentError
         nil
+      }
+    } do |model_name, action, processed_data, message|
+      Rails.logger.info "🔄 Transformed and synced #{model_name}: #{processed_data[:unique_id]}"
     end
-    
-    def self.convert_to_cents(dollars)
-        (dollars.to_f * 100).round
-    end
+  
+  private
+  
+  def self.normalize_vin(vin)
+    vin&.upcase&.gsub(/[^A-Z0-9]/, '')&.strip
+  end
+  
+  def self.normalize_serial(serial)
+    serial&.upcase&.strip&.gsub(/\s+/, '')
+  end
+  
+  def self.parse_timestamp(timestamp)
+    return nil if timestamp.blank?
+    Time.parse(timestamp.to_s)
+  rescue ArgumentError
+    nil
+  end
+  
+  def self.convert_to_cents(dollars)
+    (dollars.to_f * 100).round
+  end
 end
 ```
 
 ## 🔀 Cross-Service Integration
 
-### Handling Different Services with Same Model Names
+### Multiple Services with Same Model Names
 
 ```ruby
-
 class Package < ApplicationRecord
-    include NatsWave::Concerns::Mappable
-    
-    # Map from inventory service's Package model
-    nats_wave_maps_from 'Package',
-                        field_mappings: { 'sku' => 'product_code', 'inventory_status' => 'status' },
-                        subjects: ['inventory_service.packages.*'],
-                        conditions: {
-                                'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }, # Do not process event messages on your server
-                        },
-                        unique_fields: [:product_code, :source_service]
-    
-    # Map from order service's Package model (different fields)  
-    nats_wave_maps_from 'Package',
-                        field_mappings: { 'order_item_id' => 'external_order_id', 'item_name' => 'name' },
-                        subjects: ['order_service.packages.*'],
-                        conditions: {
-                                'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }, # Do not process event messages on your server
-                        },
-                        unique_fields: [:external_order_id, :source_service]
-    
-    # Custom subscription with service-specific routing
-    nats_wave_subscribes_to(
-            'inventory_service.packages.*',
-            'order_service.packages.*',
-            'fulfillment_service.packages.*'
-    ) do |message|
-        service_name = message.dig('source', 'service')
-        
-        case service_name
-            when 'inventory_service'
-                InventoryPackageProcessor.process(message)
-            when 'order_service'
-                OrderPackageProcessor.process(message)
-            when 'fulfillment_service'
-                FulfillmentPackageProcessor.process(message)
-            else
-                Rails.logger.warn "Unknown service: #{service_name}"
-        end
+  include NatsWave::Concerns::Mappable
+  
+  # Handle packages from different services
+  nats_wave_subscribes_to "inventory_service.packages.*",
+    field_mappings: { 
+      'sku' => 'product_code', 
+      'inventory_status' => 'status' 
+    },
+    unique_fields: [:product_code] do |model_name, action, processed_data, message|
+      source_service = message.dig('source', 'service')
+      Rails.logger.info "📦 Inventory package #{action}: #{processed_data[:product_code]} from #{source_service}"
+      
+      # Inventory-specific processing
+      InventoryPackageProcessor.process(processed_data, action)
+    end
+  
+  nats_wave_subscribes_to "order_service.packages.*",
+    field_mappings: { 
+      'order_item_id' => 'external_order_id', 
+      'item_name' => 'name' 
+    },
+    unique_fields: [:external_order_id] do |model_name, action, processed_data, message|
+      source_service = message.dig('source', 'service')
+      Rails.logger.info "📦 Order package #{action}: #{processed_data[:external_order_id]} from #{source_service}"
+      
+      # Order-specific processing
+      OrderPackageProcessor.process(processed_data, action)
     end
 end
 ```
 
-### Using Different External Model Names
+### Different External Model Names
 
 ```ruby
-
 class Asset < ApplicationRecord
-    include NatsWave::Concerns::Mappable
-    
-    # Map different external model names to local Asset
-    nats_wave_maps_from 'InventoryItem',
-                        field_mappings: { 'sku' => 'product_code', 'stock_level' => 'quantity' },
-                        subjects: ['inventory_service.inventory_items.*'],
-                        unique_fields: [:product_code]
-    
-    nats_wave_maps_from 'OrderItem',
-                        field_mappings: { 'item_id' => 'external_order_id', 'item_name' => 'name' },
-                        subjects: ['order_service.order_items.*'],
-                        unique_fields: [:external_order_id]
-    
-    nats_wave_maps_from 'ShipmentItem',
-                        field_mappings: { 'tracking_code' => 'tracking_number' },
-                        subjects: ['fulfillment_service.shipment_items.*'],
-                        unique_fields: [:tracking_number]
+  include NatsWave::Concerns::Mappable
+  
+  # Map different external model names to local Asset model
+  nats_wave_subscribes_to "inventory_service.inventory_items.*",
+    field_mappings: { 
+      'sku' => 'product_code', 
+      'stock_level' => 'quantity' 
+    },
+    unique_fields: [:product_code] do |model_name, action, processed_data, message|
+      Rails.logger.info "📦 Inventory item -> Asset: #{processed_data[:product_code]}"
+    end
+  
+  nats_wave_subscribes_to "order_service.order_items.*",
+    field_mappings: { 
+      'item_id' => 'external_order_id', 
+      'item_name' => 'name' 
+    },
+    unique_fields: [:external_order_id] do |model_name, action, processed_data, message|
+      Rails.logger.info "🛒 Order item -> Asset: #{processed_data[:external_order_id]}"
+    end
+  
+  nats_wave_subscribes_to "fulfillment_service.shipment_items.*",
+    field_mappings: { 
+      'tracking_code' => 'tracking_number' 
+    },
+    unique_fields: [:tracking_number] do |model_name, action, processed_data, message|
+      Rails.logger.info "🚚 Shipment item -> Asset: #{processed_data[:tracking_number]}"
+    end
 end
 ```
 
 ## 🎯 Message Processing & Handlers
 
-### Automatic Message Processing
+### Auto-Sync Process Flow
+
+When a message is received, NatsWave automatically:
 
-NatsWave includes a comprehensive `MessageHandler` that automatically processes mapped messages:
+1. **Parses the message** and extracts data
+2. **Applies field mappings** to transform field names
+3. **Runs transformations** on the mapped data
+4. **Finds existing records** using unique_fields
+5. **Performs database operation** (create/update/delete)
+6. **Calls custom handler** with the processed data (if provided)
 
 ```ruby
-# When a message is received, NatsWave automatically:
-# 1. Finds local models that can handle the external model
-# 2. Applies field mappings and transformations  
-# 3. Checks conditions
-# 4. Performs create/update/delete based on the action
-# 5. Uses unique_fields to find existing records for updates
-
-module NatsWave
-    class MessageHandler
-        def self.process(message)
-            # Find which local model(s) can handle this external model
-            local_models = ModelRegistry.local_models_for(message['model'])
-            
-            local_models.each do |local_model_name, mapping_config|
-                # Transform data using field mappings
-                transformed_data = transform_data(message['data'], mapping_config)
-                
-                # Get model class and perform the sync
-                model_class = local_model_name.constantize
-                
-                case message['action']
-                    when 'create', 'created'
-                        sync_create(model_class, transformed_data, mapping_config)
-                    when 'update', 'updated'
-                        sync_update(model_class, transformed_data, mapping_config)
-                    when 'delete', 'deleted', 'destroy'
-                        sync_delete(model_class, transformed_data, mapping_config)
-                end
-            end
-        end
-    end
-end
+# Example flow for incoming message:
+{
+  "subject": "inventory_service.items.update",
+  "model": "InventoryItem", 
+  "action": "update",
+  "data": {
+    "item_id": "INV-2024-001",
+    "manufacturer": "ford",
+    "estimated_value": 35000.00
+  }
+}
+
+# NatsWave automatically:
+# 1. Maps 'item_id' -> 'unique_id', 'manufacturer' -> 'make'
+# 2. Transforms 'make' to 'FORD' (uppercase)
+# 3. Finds Asset.find_by(unique_id: 'INV-2024-001')  
+# 4. Updates the asset with transformed data
+# 5. Calls your custom handler with processed data
 ```
 
-### Custom Message Handlers
+### Custom Handler Parameters
 
 ```ruby
-
-class CustomAssetHandler
-    def self.process(message)
-        case message['action']
-            when 'valuation_requested'
-                ValuationService.queue_valuation(message['data'])
-            when 'images_updated'
-                ImageProcessingService.process_asset_images(message['data'])
-            when 'auction_scheduled'
-                AuctionNotificationService.notify_subscribers(message['data'])
-        end
-    end
+nats_wave_subscribes_to "external_service.items.*" do |model_name, action, processed_data, original_message|
+  # model_name: The local model name ('Asset')
+  # action: The action performed ('create', 'update', 'delete')
+  # processed_data: Hash of the final processed/transformed data
+  # original_message: Full original NATS message hash
+  
+  Rails.logger.info "Handler called for #{model_name}##{action}"
+  Rails.logger.info "Processed data keys: #{processed_data.keys}"
+  Rails.logger.info "Original message source: #{original_message.dig('source', 'service')}"
+  
+  # Your custom logic here
+  case action
+  when 'create'
+    WelcomeEmailJob.perform_later(processed_data[:id])
+  when 'update'
+    CacheInvalidationJob.perform_later(processed_data[:id])
+  when 'delete'
+    CleanupJob.perform_later(processed_data[:id])
+  end
 end
+```
 
-class Asset < ApplicationRecord
-    include NatsWave::Concerns::Mappable
-    
-    # Use custom handler for specific subjects
-    nats_wave_subscribes_to 'valuation.assets.*' do |message|
-        CustomAssetHandler.process(message)
+### Error Handling in Handlers
+
+```ruby
+nats_wave_subscribes_to "risky_service.items.*",
+  unique_fields: [:external_id] do |model_name, action, processed_data, message|
+    begin
+      # Your processing logic
+      RiskyExternalService.process(processed_data)
+      
+      Rails.logger.info "✅ Successfully processed #{model_name} #{action}"
+      
+    rescue RiskyExternalService::RateLimitError => e
+      # Retry later for rate limits
+      Rails.logger.warn "⏱️ Rate limited, retrying later: #{e.message}"
+      RetryProcessingJob.set(wait: 5.minutes).perform_later(processed_data, message)
+      
+    rescue => e
+      # Log error but don't re-raise (would kill subscription)
+      Rails.logger.error "❌ Handler error for #{model_name} #{action}: #{e.message}"
+      ErrorTracker.notify(e, context: { model: model_name, action: action, data: processed_data })
+      
+      # Send to dead letter queue for manual review
+      DeadLetterQueue.store(message, e)
     end
-end
+  end
 ```
 
 ## 📊 Monitoring & Metrics
@@ -923,28 +701,46 @@ end
 ### ModelRegistry Inspection
 
 ```ruby
-# View all registered subscriptions
-NatsWave::ModelRegistry.debug_registrations
+# View all registered subscriptions and mappings
+rails console
 
-# Get subscription statistics
-stats = NatsWave::ModelRegistry.subscription_stats
+# Debug all registrations
+> NatsWave::ModelRegistry.debug_registrations
+
+# Get subscription statistics  
+> stats = NatsWave::ModelRegistry.subscription_stats
 # => {
 #   total_subscriptions: 5,
-#   unique_subjects: 8, 
+#   unique_subjects: 8,
 #   models_with_subscriptions: 3,
 #   subscription_breakdown: {"Asset"=>2, "Package"=>2, "User"=>1}
 # }
 
-# View all mappings
-mappings = NatsWave::ModelRegistry.all_mappings
+# View subscriptions for specific model
+> NatsWave::ModelRegistry.subscriptions_for_model('Asset')
+
+# Check if external model can be synced
+> NatsWave::ModelRegistry.can_sync_external_model?('InventoryItem')
+# => true
+```
+
+### Built-in Health Checks
+
+```ruby
+# Check overall system health
+> NatsWave.health_check
 # => {
-#   local_to_external: {...},
-#   external_to_local: {"InventoryItem" => {"Asset" => {...}}}
+#   "nats_connected": true,
+#   "database_connected": true,
+#   "timestamp": "2024-01-21T12:00:00Z",
+#   "service_name": "valuation_service", 
+#   "version": "1.2.0",
+#   "instance_id": "web-1",
+#   "model_registry_stats": {
+#     "total_subscriptions": 5,
+#     "unique_subjects": 8
+#   }
 # }
-
-# Find local models for external model
-local_models = NatsWave::ModelRegistry.local_models_for('InventoryItem')
-# => {"Asset" => {field_mappings: {...}, transformations: {...}}}
 ```
 
 ### Datadog Integration
@@ -953,93 +749,117 @@ NatsWave provides comprehensive Datadog metrics:
 
 ```ruby
 # Automatic metrics tracked:
--nats_wave.messages.published # Messages published by subject/model
--nats_wave.messages.received # Messages received by subject/model
--nats_wave.processing_time # Message processing duration  
--nats_wave.errors # Errors by type and subject
--nats_wave.connection_status # NATS connection health
--nats_wave.sync.operations # Model sync operations
--nats_wave.retries # Retry attempts
--nats_wave.model_registry.subscriptions # Active subscriptions
+# - nats_wave.messages.published (by subject/model/action)
+# - nats_wave.messages.received (by subject/model/action)  
+# - nats_wave.processing_time (message processing duration)
+# - nats_wave.sync_operations (auto-sync operations by model/action)
+# - nats_wave.handler_execution_time (custom handler duration)
+# - nats_wave.errors (errors by type and subject)
+# - nats_wave.connection_status (NATS connection health)
+# - nats_wave.retries (retry attempts)
+
+# Enable in config/initializers/nats_wave.rb
+if defined?(Datadog::Statsd) && !Rails.env.test?
+  NatsWave::Metrics.configure_datadog(
+    namespace: "#{Rails.application.class.name.deconstantize.underscore}.nats_wave",
+    tags: {
+      service: NatsWave.configuration.service_name,
+      environment: Rails.env,
+      version: Rails.application.config.version
+    }
+  )
+end
 ```
 
-### Health Checks
+### Health Check Endpoint
 
 ```ruby
-# Built-in health check
-health = NatsWave.health_check
+# config/routes.rb
+Rails.application.routes.draw do
+  get '/health/nats_wave', to: 'health#nats_wave'
+end
 
-# Response:
-{
-        "nats_connected": true,
-        "database_connected": true,
-        "timestamp": "2024-01-01T12:00:00Z",
-        "service_name": "valuation_service",
-        "version": "1.2.0",
-        "instance_id": "web-1",
-        "published_subjects": [
-                "valuation_service.events.assets.*",
-                "valuation_service.events.packages.*"
-        ],
-        "subscribed_subjects": [
-                "inventory_service.items.*",
-                "auction_service.assets.*"
-        ],
-        "model_registry_stats": {
-                "total_subscriptions": 5,
-                "unique_subjects": 8
-        }
-}
+# app/controllers/health_controller.rb
+class HealthController < ApplicationController
+  def nats_wave
+    health_data = NatsWave.health_check
+    
+    if health_data[:nats_connected]
+      render json: health_data, status: :ok
+    else
+      render json: health_data.merge(error: 'NATS not connected'), 
+             status: :service_unavailable
+    end
+  rescue => e
+    render json: {
+      error: e.message,
+      nats_connected: false,
+      timestamp: Time.current.iso8601
+    }, status: :service_unavailable
+  end
+end
 ```
 
 ## 🛡️ Error Handling
 
-### Dead Letter Queue
+### Automatic Error Recovery
 
-Failed messages are automatically stored with retry logic:
+NatsWave includes robust automatic error handling:
 
-```ruby
-# Automatic retry with exponential backoff
-# Retry 1: after 5 seconds
-# Retry 2: after 25 seconds
-# Retry 3: after 125 seconds  
-# After max retries: moved to permanent failure storage
-```
+- **Auto-Reconnection**: Automatic reconnection with exponential backoff
+- **Health Monitoring**: Continuous connection health checks
+- **Dead Letter Queue**: Failed messages stored for manual review
+- **Retry Logic**: Configurable retry attempts with delays
 
-### Error Recovery Commands
-
-```bash
-# View failed messages
-rails nats_wave:show_failed
+### Connection Recovery
 
-# Retry failed messages
-rails nats_wave:retry_failed
-
-# Clear failed messages (after manual review)
-rails nats_wave:clear_failed
-
-# Monitor live activity
-rails nats_wave:monitor
+```ruby
+# The client automatically handles:
+# - Network disconnections
+# - NATS server restarts  
+# - Temporary connection issues
+# - Subscription restoration after reconnection
+
+# Monitor connection health in logs:
+# 💜 Subscriber connection healthy - 3 active subscriptions
+# 🔌 NATS disconnected: Connection lost
+# 🔄 Attempting to reconnect to NATS... (attempt #1)
+# ✅ NATS client reconnected successfully
+# ✅ Subscriptions restored (3 active)
 ```
 
 ### Custom Error Handling
 
 ```ruby
-
 class CustomErrorHandler
-    def self.handle_failed_message(message, error, retry_count)
-        # Send to monitoring service
-        ErrorTracker.notify(error, {
-                message: message,
-                retry_count: retry_count,
-                service: 'nats_wave'
-        })
-        
-        # Custom retry logic for specific errors
-        if error.is_a?(ValidationError) && retry_count < 5
-            RetryValidationJob.set(wait: 30.seconds).perform_later(message)
-        end
+  def self.handle_subscription_error(error, message, model_name)
+    # Custom error processing
+    case error
+    when ValidationError
+      Rails.logger.warn "⚠️ Validation failed for #{model_name}: #{error.message}"
+      # Maybe send to a separate queue for data cleanup
+      
+    when ExternalServiceError
+      Rails.logger.error "🔌 External service error: #{error.message}"
+      # Retry with exponential backoff
+      RetryJob.set(wait: 2.minutes).perform_later(message)
+      
+    else
+      Rails.logger.error "❌ Unexpected error processing #{model_name}: #{error.message}"
+      # Send to monitoring
+      ErrorTracker.notify(error, context: { model: model_name, message: message })
     end
+  end
+end
+
+# Use in your model handlers
+nats_wave_subscribes_to "external.items.*" do |model_name, action, data, message|
+  begin
+    # Your processing logic
+    ExternalService.process(data)
+  rescue => e
+    CustomErrorHandler.handle_subscription_error(e, message, model_name)
+  end
 end
 ```
 
@@ -1050,72 +870,160 @@ end
 ```ruby
 # spec/spec_helper.rb or test/test_helper.rb
 RSpec.configure do |config|
-    config.before(:suite) do
-        # Clear ModelRegistry before tests
-        NatsWave::ModelRegistry.clear!
-    end
-    
-    config.before(:each) do
-        # Mock NATS in tests
-        allow(NatsWave.client).to receive(:publish)
-        allow(NatsWave.client).to receive(:subscribe)
+  config.before(:suite) do
+    # Clear ModelRegistry before tests
+    NatsWave::ModelRegistry.clear! if defined?(NatsWave::ModelRegistry)
+  end
+  
+  config.before(:each) do
+    # Mock NATS operations in tests by default
+    if defined?(NatsWave)
+      allow(NatsWave).to receive(:publish)
+      allow(NatsWave.client).to receive(:publish) if NatsWave.client
+      allow(NatsWave.client).to receive(:subscribe) if NatsWave.client
     end
+  end
 end
 ```
 
-### Testing Model Subscriptions
+### Testing Model Configuration
 
 ```ruby
 # spec/models/asset_spec.rb
 RSpec.describe Asset, type: :model do
-    describe 'NATS Wave configuration' do
-        it 'registers correct subscriptions' do
-            subscriptions = NatsWave::ModelRegistry.subscriptions_for_model('Asset')
-            expect(subscriptions.size).to eq(2)
-            
-            subjects = subscriptions.flat_map { |s| s[:subjects] }
-            expect(subjects).to include('inventory_service.items.*')
-            expect(subjects).to include('auction_service.assets.*')
-        end
-        
-        it 'has correct field mappings' do
-            mapping = Asset.nats_wave_mapping_for('InventoryItem')
-            expect(mapping[:field_mappings]['item_id']).to eq('unique_id')
-            expect(mapping[:field_mappings]['manufacturer']).to eq('make')
-        end
+  describe 'NATS Wave configuration' do
+    it 'registers correct subscriptions' do
+      subscriptions = NatsWave::ModelRegistry.subscriptions_for_model('Asset')
+      expect(subscriptions.size).to eq(1)
+      
+      subjects = subscriptions.flat_map { |s| s[:subjects] }
+      expect(subjects).to include('inventory_service.items.*')
+    end
+    
+    it 'has correct field mappings for inventory items' do
+      # Test that the model is registered to handle InventoryItem
+      local_models = NatsWave::ModelRegistry.local_models_for('InventoryItem')
+      expect(local_models).to have_key('Asset')
+      
+      mapping = local_models['Asset']
+      expect(mapping[:field_mappings]['item_id']).to eq('unique_id')
+      expect(mapping[:field_mappings]['manufacturer']).to eq('make')
+    end
+    
+    it 'has correct transformations' do
+      local_models = NatsWave::ModelRegistry.local_models_for('InventoryItem')
+      mapping = local_models['Asset']
+      
+      # Test transformation functions
+      make_transformer = mapping[:transformations]['make']
+      expect(make_transformer.call('ford')).to eq('FORD')
+      expect(make_transformer.call('  Caterpillar  ')).to eq('CATERPILLAR')
     end
+  end
 end
 ```
 
 ### Testing Message Processing
 
 ```ruby
-# spec/services/message_handler_spec.rb
-RSpec.describe NatsWave::MessageHandler do
-    describe '.process' do
-        it 'creates asset from inventory message' do
-            message = {
-                    'model' => 'InventoryItem',
-                    'action' => 'create',
-                    'data' => {
-                            'item_id' => 'INV-001',
-                            'manufacturer' => 'caterpillar',
-                            'model_number' => '320D',
-                            'year_built' => '2020'
-                    },
-                    'source' => { 'service' => 'inventory_service' }
-            }
-            
-            expect {
-                NatsWave::MessageHandler.process(message)
-            }.to change(Asset, :count).by(1)
-            
-            asset = Asset.last
-            expect(asset.unique_id).to eq('INV-001')
-            expect(asset.make).to eq('CATERPILLAR') # Uppercased by transformation
-            expect(asset.year).to eq(2020) # Converted to integer
-        end
+# spec/services/nats_wave_integration_spec.rb  
+RSpec.describe 'NATS Wave Integration' do
+  let(:sample_message) do
+    {
+      'model' => 'InventoryItem',
+      'action' => 'create',
+      'data' => {
+        'item_id' => 'INV-001',
+        'manufacturer' => 'caterpillar',
+        'model_name' => '320D',
+        'year_manufactured' => '2020',
+        'estimated_value' => 125000.00
+      },
+      'source' => { 'service' => 'inventory_service' }
+    }
+  end
+
+  describe 'message processing' do
+    it 'creates asset from inventory message' do
+      expect {
+        # Simulate message processing (this would normally happen automatically)
+        NatsWave::MessageHandler.process(sample_message)
+      }.to change(Asset, :count).by(1)
+      
+      asset = Asset.last
+      expect(asset.unique_id).to eq('INV-001')
+      expect(asset.make).to eq('CATERPILLAR') # Uppercased by transformation
+      expect(asset.model).to eq('320D')
+      expect(asset.year).to eq(2020) # Converted to integer
+      expect(asset.estimated_hammer).to eq(12500000) # Converted to cents
     end
+    
+    it 'calls custom handler after auto-sync' do
+      expect(ValuationRequestJob).to receive(:perform_later).with('INV-001')
+      
+      # This would trigger both auto-sync and custom handler
+      NatsWave::MessageHandler.process(sample_message)
+    end
+  end
+  
+  describe 'publishing' do
+    it 'publishes asset updates with field mappings' do
+      asset = Asset.create!(
+        unique_id: 'TEST-001',
+        make: 'FORD',
+        model: 'F-150',
+        year: 2020
+      )
+      
+      expect(NatsWave).to receive(:publish) do |args|
+        expect(args[:subject]).to match(/assets\.update/)
+        expect(args[:data]['asset_id']).to eq('TEST-001') # Mapped from unique_id
+        expect(args[:data]['manufacturer']).to eq('FORD') # Mapped from make
+      end
+      
+      asset.update!(make: 'FORD-UPDATED')
+    end
+  end
+end
+```
+
+### Testing Custom Handlers
+
+```ruby
+# spec/models/asset_nats_handlers_spec.rb
+RSpec.describe 'Asset NATS Handlers' do
+  describe 'subscription handler' do
+    let(:message) do
+      {
+        'model' => 'InventoryItem',
+        'action' => 'create', 
+        'data' => { 'item_id' => 'TEST-001', 'estimated_value' => nil }
+      }
+    end
+    
+    it 'queues valuation request for assets without estimates' do
+      expect(ValuationRequestJob).to receive(:perform_later).with('TEST-001')
+      
+      # Simulate the handler being called
+      # In real usage, this happens automatically when messages are received
+      Asset.new.instance_eval do
+        # Call the handler block manually for testing
+        processed_data = { unique_id: 'TEST-001', estimated_hammer: nil }
+        # Your handler logic here...
+      end
+    end
+  end
+  
+  describe 'publishing handler' do
+    it 'sends notifications after publishing valuation updates' do
+      asset = Asset.create!(unique_id: 'TEST-001', workflow_status: 'pending')
+      
+      expect(NotificationService).to receive(:notify_valuation_complete)
+      
+      # This would trigger publishing + custom handler
+      asset.update!(workflow_status: 'complete')
+    end
+  end
 end
 ```
 
@@ -1177,71 +1085,58 @@ spec:
         app: valuation-service
     spec:
       containers:
-        - name: app
-          image: valuation-service:latest
-          env:
-            - name: NATS_URL
-              value: "nats://nats-cluster:4222"
-            - name: NATS_SERVICE_NAME
-              value: "valuation-service"
-          ports:
-            - containerPort: 3000
-          livenessProbe:
-            httpGet:
-              path: /health/nats_wave
-              port: 3000
-            initialDelaySeconds: 30
-            periodSeconds: 10
-          readinessProbe:
-            httpGet:
-              path: /health/nats_wave
-              port: 3000
-            initialDelaySeconds: 5
-            periodSeconds: 5
+      - name: app
+        image: valuation-service:latest
+        env:
+        - name: NATS_URL
+          value: "nats://nats-cluster:4222"
+        - name: NATS_SERVICE_NAME
+          value: "valuation-service"
+        - name: NATS_AUTH_SECRET
+          valueFrom:
+            secretKeyRef:
+              name: nats-wave-secrets
+              key: auth-secret
+        ports:
+        - containerPort: 3000
+        livenessProbe:
+          httpGet:
+            path: /health/nats_wave
+            port: 3000
+          initialDelaySeconds: 30
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /health/nats_wave
+            port: 3000
+          initialDelaySeconds: 5
+          periodSeconds: 5
 ```
 
 ## 💡 Examples
 
-### Complete Asset Valuation Integration
+### Complete Asset Workflow Integration
 
 ```ruby
 # app/models/asset.rb
 class Asset < ApplicationRecord
-  include NatsWave::NatsPublishable
   include NatsWave::Concerns::Mappable
   
   belongs_to :package
-  belongs_to :creator, class_name: 'User', optional: true
-  belongs_to :last_updater, class_name: 'User', optional: true
-  belongs_to :subpackage, optional: true
   has_many :estimates, dependent: :destroy
   has_many :images, dependent: :destroy
-  has_many :videos, dependent: :destroy
-  has_many :links, dependent: :destroy
-  has_many :attachments, dependent: :destroy
-  
-  # Publish asset changes to other services
-  nats_publishable(
-    actions: [:create, :update],
-    skip_attributes: [:notes, :edge_data, :source_data, :ims_forms_data],
-    include_associations: [:package, :estimates],
-    subject_prefix: 'assets',
-    if: -> { asset_status != 'draft' }
-  )
   
-  # Sync from external inventory management system
-  nats_wave_maps_from 'InventoryAsset',
+  # Subscribe to inventory system - auto-sync with custom processing
+  nats_wave_subscribes_to "inventory_service.assets.*", "warehouse_service.assets.*",
     field_mappings: {
       'inventory_id' => 'unique_id',
       'asset_description' => 'description',
       'manufacturer' => 'make',
-      'model_number' => 'model',
+      'model_number' => 'model', 
       'year_manufactured' => 'year',
       'serial_number' => 'serial',
       'vin_number' => 'vin',
       'location_name' => 'location',
-      'inventory_tag' => 'inventory_tag',
-      'sticker_number' => 'sticker',
       'estimated_value' => 'estimated_hammer'
     },
     transformations: {
@@ -1249,19 +1144,43 @@ class Asset < ApplicationRecord
       'model' => ->(model) { model&.titleize&.strip },
       'year' => ->(year) { year.to_i if year.present? },
       'estimated_hammer' => ->(value) { (value.to_f * 100).round }, # Convert to cents
-      'asset_status' => ->(status) { status&.downcase || 'in_progress' }
+      'asset_status' => ->(status) { status&.downcase || 'active' }
     },
     unique_fields: [:unique_id, :vin, :serial],
-    sync_strategy: :upsert,
-    conditions: {
-      'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] },
-      'status' => ['available', 'reserved', 'active'],
-      'estimated_value' => ->(value) { value.to_f > 0 }
-    },
-    subjects: ['inventory_service.assets.*']
-    
-  # Sync from auction management system
-  nats_wave_maps_from 'AuctionLot',
+    skip_fields: ['internal_inventory_code', 'warehouse_notes'] do |model_name, action, processed_data, message|
+      Rails.logger.info "📦 Inventory sync: #{action} for #{processed_data[:unique_id]}"
+      
+      case action
+      when 'create'
+        # Auto-request valuation for new assets without estimates
+        if processed_data[:estimated_hammer].blank?
+          ValuationRequestJob.perform_later(processed_data[:unique_id])
+          Rails.logger.info "🔍 Queued valuation request for #{processed_data[:unique_id]}"
+        end
+        
+        # Download images if provided
+        if message.dig('data', 'image_urls').present?
+          ImageDownloadJob.perform_later(processed_data[:unique_id], message['data']['image_urls'])
+        end
+        
+      when 'update'
+        # Track significant value changes
+        original_value = Asset.find_by(unique_id: processed_data[:unique_id])&.estimated_hammer
+        if original_value != processed_data[:estimated_hammer]
+          AssetValueChangeNotificationJob.perform_later(processed_data[:unique_id])
+        end
+        
+      when 'delete', 'destroy'
+        # Clean up related data
+        CleanupAssetDataJob.perform_later(processed_data[:unique_id])
+      end
+      
+      # Always update search index
+      SearchIndexUpdateJob.perform_later(processed_data[:unique_id], 'Asset')
+    end
+  
+  # Subscribe to auction results  
+  nats_wave_subscribes_to "auction_service.lots.*",
     field_mappings: {
       'lot_number' => 'lot_number',
       'hammer_price' => 'pw_contract_price',
@@ -1272,65 +1191,81 @@ class Asset < ApplicationRecord
       'pw_contract_price' => ->(price) { (price.to_f * 100).round }, # Convert to cents
       'pw_contract_date' => ->(date) { Time.parse(date.to_s) rescue nil }
     },
-    conditions: {
-      'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] },
-      'status' => 'sold'
-    },
-    subjects: ['auction_service.lots.*']
-    
-  # Listen for valuation requests
-  nats_wave_subscribes_to 'valuation_service.requests.*' do |message|
-    AssetValuationProcessor.process_request(message)
-  end
-  
-  private
+    unique_fields: [:lot_number] do |model_name, action, processed_data, message|
+      if action == 'sold'
+        Rails.logger.info "🔨 Asset sold: #{processed_data[:lot_number]} for $#{processed_data[:pw_contract_price] / 100}"
+        
+        # Create final estimate based on actual sale
+        asset = Asset.find_by(lot_number: processed_data[:lot_number])
+        if asset
+          Estimate.create!(
+            asset: asset,
+            user: User.find_by(email: 'auction@system.com'),
+            estimate_type: EstimateType.find_by(name: 'Auction Result'),
+            status: 'current',
+            value_category: 'final',
+            value: processed_data[:pw_contract_price],
+            version_number: 1,
+            notes: "Actual auction sale price from #{processed_data[:pw_auction]}"
+          )
+          
+          # Notify stakeholders
+          AuctionResultNotificationJob.perform_later(asset.id)
+        end
+      end
+    end
   
-  def nats_wave_metadata
-    {
-      package_key: package&.key,
-      organization_id: package&.organization_id,
-      creator_name: creator&.name,
-      valuation_type: valuation_type,
-      estimated_value: estimated_hammer,
-      image_count: images.where(deleted: false).count,
-      video_count: videos.where(deleted: false).count,
-      has_estimates: estimates.where(status: 'current').exists?
-    }
-  end
+  # Publish asset changes to other services
+  nats_wave_publishes_to "#{ENV['NATS_SERVICE_NAME']}.assets.{action}",
+    field_mappings: {
+      'unique_id' => 'asset_id',
+      'make' => 'manufacturer', 
+      'model' => 'model_name',
+      'estimated_hammer' => 'estimated_value'
+    },
+    transformations: {
+      'created_at' => lambda(&:iso8601),
+      'updated_at' => lambda(&:iso8601),
+      'estimated_value' => ->(cents) { cents.to_f / 100 } # Convert back to dollars
+    },
+    skip_fields: %w[notes edge_data source_data package_id creator_id last_updater_id],
+    actions: %i[create update] do |model_name, action, published_data, record|
+      Rails.logger.info "📤 Published #{action} for asset: #{record.unique_id}"
+      
+      # Custom processing after publishing
+      if action == 'update' && record.estimated_hammer_changed?
+        # Notify external pricing services
+        ExternalPricingService.update_asset_value(record.unique_id, record.estimated_hammer)
+      end
+      
+      # Update external inventory systems
+      if record.location_changed?
+        ExternalInventoryService.update_location(record.unique_id, record.location)
+      end
+    end
 end
+```
 
-# app/models/package.rb
+### Package Management Integration
+
+```ruby
+# app/models/package.rb  
 class Package < ApplicationRecord
-  include NatsWave::NatsPublishable
   include NatsWave::Concerns::Mappable
   
   belongs_to :organization
-  belongs_to :contact_user, class_name: 'User', optional: true
   has_many :assets, dependent: :destroy
-  has_many :subpackages, dependent: :destroy
   has_many :valuation_requests, dependent: :destroy
-  has_many :ims_submissions, dependent: :destroy
   
-  # Publish package workflow changes
-  nats_publishable(
-    actions: [:create, :update],
-    skip_attributes: [:notes, :source_data],
-    include_associations: [:organization, :assets],
-    subject_prefix: 'packages',
-    if: -> { workflow_status.in?(['active', 'finalized']) }
-  )
-  
-  # Sync from CRM/Project management systems
-  nats_wave_maps_from 'CRMProject',
+  # Subscribe to CRM project updates
+  nats_wave_subscribes_to "crm_service.projects.*",
     field_mappings: {
       'project_id' => 'key',
       'client_name' => 'owner_name',
       'client_email' => 'owner_email',
       'project_location' => 'location',
       'project_status' => 'workflow_status',
-      'project_notes' => 'notes',
-      'opportunity_reference' => 'opportunity_id',
-      'contact_person' => 'primary_contact'
+      'opportunity_reference' => 'opportunity_id'
     },
     transformations: {
       'workflow_status' => ->(status) { 
@@ -1342,354 +1277,108 @@ class Package < ApplicationRecord
         end
       }
     },
-    unique_fields: [:key],
-    conditions: {
-      'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }
-    },
-    subjects: ['crm_service.projects.*']
-    
-  # Listen for import completion notifications
-  nats_wave_subscribes_to 'ims_service.imports.*' do |message|
-    IMSImportProcessor.process_completion(message)
-  end
-  
-  private
-  
-  def nats_wave_metadata
-    {
-      organization_name: organization&.name,
-      organization_key: organization&.key,
-      asset_count: assets.count,
-      total_estimated_value: assets.sum(:estimated_hammer),
-      workflow_status: workflow_status,
-      import_status: {
-        requested: import_requested,
-        completed: import_completed
-      },
-      valuation_summary: {
-        reasons: valuation_reasons,
-        notes_present: valuation_notes.present?
-      }
-    }
-  end
-end
-
-# app/models/estimate.rb
-class Estimate < ApplicationRecord
-  include NatsWave::NatsPublishable
-  include NatsWave::Concerns::Mappable
-  
-  belongs_to :asset
-  belongs_to :user
-  belongs_to :estimate_type
-  
-  # Publish estimate changes for consensus tracking
-  nats_publishable(
-    actions: [:create, :update],
-    skip_attributes: [:notes, :source_data],
-    subject_prefix: 'estimates',
-    if: -> { status == 'current' && value_category == 'final' }
-  )
+    unique_fields: [:key] do |model_name, action, processed_data, message|
+      Rails.logger.info "📋 CRM project sync: #{action} for #{processed_data[:key]}"
+      
+      if action == 'create'
+        # Auto-create valuation request for new projects
+        ValuationRequest.create!(
+          package_id: Package.find_by(key: processed_data[:key])&.id,
+          user: User.find_by(email: 'system@valuation.com'),
+          notes: 'Auto-created from CRM project'
+        )
+      end
+    end
   
-  # Sync from external valuation services
-  nats_wave_maps_from 'ExternalValuation',
+  # Publish package workflow changes
+  nats_wave_publishes_to "#{ENV['NATS_SERVICE_NAME']}.packages.{action}",
     field_mappings: {
-      'valuation_id' => 'key',
-      'asset_identifier' => 'asset_id',
-      'appraiser_id' => 'user_id',
-      'estimated_value' => 'value',
-      'valuation_notes' => 'notes',
-      'valuation_type' => 'estimate_type_id'
+      'key' => 'package_key',
+      'owner_name' => 'client_name',
+      'workflow_status' => 'status'
     },
     transformations: {
-      'value' => ->(value) { (value.to_f * 100).round }, # Convert to cents
-      'estimate_type_id' => ->(type_name) { 
-        EstimateType.find_by(name: type_name)&.id || 1 
-      },
-      'status' => ->(_) { 'current' },
-      'value_category' => ->(_) { 'temporary' },
-      'version_number' => ->(_) { 1 }
+      'created_at' => lambda(&:iso8601),
+      'updated_at' => lambda(&:iso8601)
     },
-    unique_fields: [:key],
-    conditions: {
-      'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }
-    },
-    subjects: ['valuation_service.estimates.*']
+    skip_fields: %w[notes source_data],
+    actions: %i[create update] do |model_name, action, published_data, record|
+      Rails.logger.info "📤 Published package #{action}: #{record.key}"
+      
+      # Notify CRM of workflow changes
+      if action == 'update' && record.workflow_status_changed?
+        CRMNotificationService.notify_status_change(record)
+      end
+    end
 end
+```
 
-# app/models/user.rb  
+### User & Organization Sync
+
+```ruby
+# app/models/user.rb
 class User < ApplicationRecord
-  include NatsWave::NatsPublishable
   include NatsWave::Concerns::Mappable
   
-  has_many :organization_users
-  has_many :organizations, through: :organization_users
-  has_many :estimates
-  has_many :created_assets, class_name: 'Asset', foreign_key: 'creator_id'
-  has_many :updated_assets, class_name: 'Asset', foreign_key: 'last_updater_id'
-  
-  # Publish user changes for authentication sync
-  nats_publishable(
-    actions: [:create, :update],
-    skip_attributes: [:api_auth_key, :source_details],
-    subject_prefix: 'users',
-    if: -> { active? }
-  )
-  
-  # Sync from authentication service
-  nats_wave_maps_from 'AuthUser',
+  # Subscribe to authentication service
+  nats_wave_subscribes_to "auth_service.users.*",
     field_mappings: {
       'user_id' => 'key',
       'email_address' => 'email',
       'full_name' => 'name',
-      'is_active' => 'active',
-      'organization_key' => 'current_organization_key'
+      'is_active' => 'active'
     },
     transformations: {
       'email' => ->(email) { email&.downcase&.strip },
       'name' => ->(name) { name&.strip },
       'active' => ->(active) { active == 'true' || active == true }
     },
-    unique_fields: [:key, :email],
-    conditions: {
-      'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }
-    },
-    subjects: ['auth_service.users.*']
+    unique_fields: [:key, :email] do |model_name, action, processed_data, message|
+      Rails.logger.info "👤 User sync: #{action} for #{processed_data[:email]}"
+      
+      if action == 'create'
+        # Send welcome email
+        UserMailer.welcome_email(processed_data[:email]).deliver_later
+      end
+    end
+  
+  # Publish user activity for analytics
+  nats_wave_publishes_to "#{ENV['NATS_SERVICE_NAME']}.users.{action}",
+    skip_fields: %w[api_auth_key source_details],
+    actions: %i[create update] do |model_name, action, published_data, record|
+      Rails.logger.info "📤 Published user #{action}: #{record.email}"
+    end
 end
 
 # app/models/organization.rb
 class Organization < ApplicationRecord
-  include NatsWave::NatsPublishable
   include NatsWave::Concerns::Mappable
   
-  has_many :packages
-  has_many :organization_users
-  has_many :users, through: :organization_users
-  has_many :organization_estimate_types
-  has_many :estimate_types, through: :organization_estimate_types
-  has_one :organization_branding
-  
-  # Publish organization changes for CRM sync
-  nats_publishable(
-    actions: [:create, :update],
-    skip_attributes: [:api_auth_key, :workflow_config],
-    subject_prefix: 'organizations',
-    if: -> { active? }
-  )
-  
-  # Sync from CRM system
-  nats_wave_maps_from 'CRMAccount',
+  # Subscribe to CRM account updates
+  nats_wave_subscribes_to "crm_service.accounts.*",
     field_mappings: {
       'account_id' => 'key',
       'company_name' => 'name',
       'is_active' => 'active',
       'primary_contact_name' => 'contact',
-      'primary_email' => 'email',
-      'primary_phone' => 'phone',
-      'account_group' => 'group_name'
+      'primary_email' => 'email'
     },
     transformations: {
       'name' => ->(name) { name&.strip },
       'email' => ->(email) { email&.downcase&.strip },
       'active' => ->(active) { active == 'true' || active == true }
     },
-    unique_fields: [:key, :name],
-    conditions: {
-      'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }
-    },
-    subjects: ['crm_service.accounts.*']
-end
-
-# app/models/image.rb
-class Image < ApplicationRecord
-  include NatsWave::NatsPublishable
-  
-  belongs_to :asset
-  
-  # Publish image events for media processing
-  nats_publishable(
-    actions: [:create, :update],
-    skip_attributes: [:source_data, :import_url],
-    subject_prefix: 'images',
-    if: -> { !deleted? && sizes.present? }
-  )
-  
-  private
-  
-  def nats_wave_metadata
-    {
-      asset_key: asset&.key,
-      package_key: asset&.package&.key,
-      image_view: image_view,
-      custom_view: custom_image_view,
-      position: position,
-      file_info: {
-        original_filename: original_filename,
-        file_type: file_type,
-        file_size: file_size,
-        dimensions: {
-          width: original_x,
-          height: original_y
-        }
-      },
-      ims_submission: {
-        name: ims_submission_name,
-        key: ims_image_key,
-        submitted_at: ims_submitted_at,
-        linked_at: ims_linked_at
-      }
-    }
-  end
-end
-```
-
-### Cross-Service Workflow Example
-
-```ruby
-# app/services/asset_valuation_workflow.rb
-class AssetValuationWorkflow
-    def self.process_inventory_asset(message)
-        # Message from inventory service creates/updates local asset
-        inventory_data = message['data']
-        
-        # Find or create asset using field mappings
-        asset = Asset.find_or_initialize_by(unique_id: inventory_data['inventory_id'])
-        
-        # Update with transformed data
-        asset.assign_attributes(
-                make: inventory_data['manufacturer']&.upcase,
-                model: inventory_data['model_number']&.titleize,
-                year: inventory_data['year_manufactured'].to_i,
-                serial: inventory_data['serial_number'],
-                vin: inventory_data['vin_number'],
-                location: inventory_data['location_name'],
-                estimated_hammer: (inventory_data['estimated_value'].to_f * 100).round
-        )
-        
-        asset.save!
-        
-        # Automatically request valuation if needed
-        if asset.estimated_hammer.nil? || asset.estimated_hammer.zero?
-            ValuationRequest.create!(
-                    package: asset.package,
-                    user: User.find_by(email: 'system@valuation.com'),
-                    notes: 'Auto-requested from inventory sync'
-            )
-        end
+    unique_fields: [:key, :name] do |model_name, action, processed_data, message|
+      Rails.logger.info "🏢 Organization sync: #{action} for #{processed_data[:name]}"
     end
-    
-    def self.process_auction_result(message)
-        # Message from auction service updates contract prices
-        auction_data = message['data']
-        
-        asset = Asset.find_by(lot_number: auction_data['lot_number'])
-        return unless asset
-        
-        asset.update!(
-                pw_contract_price: (auction_data['hammer_price'].to_f * 100).round,
-                pw_contract_date: Time.parse(auction_data['sale_date']),
-                pw_auction: auction_data['auction_house']
-        )
-        
-        # Create final estimate based on actual sale
-        Estimate.create!(
-                asset: asset,
-                user: User.find_by(email: 'auction@system.com'),
-                estimate_type: EstimateType.find_by(name: 'Auction Result'),
-                status: 'current',
-                value_category: 'final',
-                value: asset.pw_contract_price,
-                version_number: 1,
-                notes: 'Actual auction sale price'
-        )
-    end
-end
-
-# Message handlers
-class NatsWave::MessageHandler
-    def self.process(message)
-        Rails.logger.info "🔍 Processing #{message['action']} for #{message['model']} from #{message.dig('source', 'service')}"
-        
-        case message['model']
-            when 'InventoryAsset'
-                AssetValuationWorkflow.process_inventory_asset(message)
-            when 'AuctionLot'
-                AssetValuationWorkflow.process_auction_result(message)
-            when 'CRMProject'
-                CRMProjectHandler.process(message)
-            when 'AuthUser'
-                AuthUserHandler.process(message)
-            else
-                # Use automatic field mapping for registered models
-                super
-        end
-    end
-end
-```
-
-### User & Organization Sync
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-    include NatsWave::NatsPublishable
-    include NatsWave::Concerns::Mappable
-    
-    nats_publishable(
-            skip_attributes: [:api_auth_key, :source_details],
-            subject_prefix: 'users'
-    )
-    
-    # Sync from authentication service
-    nats_wave_maps_from 'AuthUser',
-                        field_mappings: {
-                                'user_id' => 'key',
-                                'email_address' => 'email',
-                                'full_name' => 'name',
-                                'is_active' => 'active',
-                                'organization_id' => 'current_organization_key'
-                        },
-                        transformations: {
-                                'email' => ->(email) { email&.downcase&.strip },
-                                'name' => ->(name) { name&.titleize&.strip },
-                                'active' => ->(active) { active == 'true' || active == true }
-                        },
-                        unique_fields: [:key, :email],
-                        subjects: ['auth_service.users.*']
-    
-    # Custom subscription for user activity tracking
-    nats_wave_subscribes_to 'activity_service.user_actions.*' do |message|
-        UserActivityTracker.track_activity(message)
+  
+  # Publish organization changes
+  nats_wave_publishes_to "#{ENV['NATS_SERVICE_NAME']}.organizations.{action}",
+    skip_fields: %w[api_auth_key workflow_config],
+    actions: %i[create update] do |model_name, action, published_data, record|
+      Rails.logger.info "📤 Published organization #{action}: #{record.name}"
     end
 end
-
-# app/models/organization.rb  
-class Organization < ApplicationRecord
-    include NatsWave::NatsPublishable
-    include NatsWave::Concerns::Mappable
-    
-    nats_publishable(
-            skip_attributes: [:api_auth_key, :workflow_config],
-            subject_prefix: 'organizations'
-    )
-    
-    # Sync from CRM system
-    nats_wave_maps_from 'CRMOrganization',
-                        field_mappings: {
-                                'organization_id' => 'key',
-                                'company_name' => 'name',
-                                'primary_contact' => 'contact',
-                                'email_address' => 'email',
-                                'phone_number' => 'phone',
-                                'is_active' => 'active'
-                        },
-                        transformations: {
-                                'name' => ->(name) { name&.strip },
-                                'email' => ->(email) { email&.downcase&.strip }
-                        },
-                        unique_fields: [:key, :name],
-                        subjects: ['crm_service.organizations.*']
-end
 ```
 
 ## 🤝 Contributing
@@ -1729,9 +1418,8 @@ This gem is available as open source under the terms of the [MIT License](LICENS
 
 ## 🏢 About Purple Wave
 
-NatsWave is developed and maintained by [Purple Wave](https://purplewave.com) to enable seamless communication between
-our microservices and teams in the asset valuation and auction industry.
+NatsWave is developed and maintained by [Purple Wave](https://purplewave.com) to enable seamless communication between our microservices and teams in the asset valuation and auction industry.
 
 ---
 
-**Made with ❤️ by the Purple Wave Team**
+**Made with ❤️ by Jeffrey Dabo**