nats_wave 1.1.5 → 1.1.8

data/README.md

@@ -18,9 +18,12 @@ different teams, products, and services in asset management and valuation workfl
 - [Publishing Events](#-publishing-events)
 - [Subscribing to Events](#-subscribing-to-events)
 - [Data Mapping & Transformation](#-data-mapping--transformation)
+- [Cross-Service Integration](#-cross-service-integration)
+- [Message Processing & Handlers](#-message-processing--handlers)
 - [Monitoring & Metrics](#-monitoring--metrics)
 - [Error Handling](#-error-handling)
 - [Production Deployment](#-production-deployment)
+- [Testing](#-testing)
 - [API Reference](#-api-reference)
 - [Examples](#-examples)
 - [Contributing](#-contributing)
@@ -30,13 +33,16 @@ different teams, products, and services in asset management and valuation workfl
 
 - **🚀 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
+- **🗺️ 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
 - **📊 Datadog Integration** - Built-in metrics and monitoring support
-- **🛡️ Error Handling** - Dead letter queues, retries, and graceful failure handling
+- **🛡️ 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
+- **📈 Auto-Discovery** - Automatic registration of model subscriptions via ModelRegistry
 - **🧪 Test-Friendly** - Comprehensive test helpers and mocking support
 
 ## 📦 Installation
@@ -73,6 +79,14 @@ 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"
 end
 ```
 
@@ -88,14 +102,14 @@ class Asset < ApplicationRecord
     nats_publishable(
             actions: [:create, :update, :destroy],
             skip_attributes: [:notes, :edge_data],
-            include_associations: [:package, :estimates]
+            include_associations: [:package, :estimates],
+            subject_prefix: 'assets'
     )
     
-    # Subscribe to external asset data from IMS
-    nats_wave_maps_from 'IMSAsset',
-                        subjects: ['ims.assets.*', 'inventory.assets.*'],
+    # Map from external inventory system  
+    nats_wave_maps_from 'InventoryItem',
                         field_mappings: {
-                                'asset_id' => 'unique_id',
+                                'item_id' => 'unique_id',
                                 'description' => 'description',
                                 'manufacturer' => 'make',
                                 'model_name' => 'model',
@@ -105,18 +119,33 @@ class Asset < ApplicationRecord
                         },
                         transformations: {
                                 'make' => ->(make) { make&.upcase&.strip },
-                                'year' => ->(year) { year.to_i if year.present? }
+                                'year' => ->(year) { year.to_i if year.present? },
+                                'estimated_hammer' => ->(value) { value.to_f.round(2) }
                         },
-                        unique_fields: [:unique_id, :vin, :serial]
+                        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)
+    end
 end
 ```
 
 ### 3. Start the Subscriber
 
+The subscriber automatically starts with Rails and processes registered model subscriptions:
+
 ```bash
 # Development - auto-starts with Rails
 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
+
 # Production - run dedicated subscriber process
 rails nats_wave:start
 ```
@@ -127,11 +156,17 @@ rails nats_wave:start
 # Test connectivity
 rails nats_wave:health
 
-# Show model subscriptions
+# Show model subscriptions  
 rails nats_wave:model_subscriptions
 
 # Publish a test message
-rails nats_wave:test
+rails console
+> NatsWave.publish(
+    subject: 'assets.create',
+    model: 'Asset', 
+    action: 'create',
+    data: { id: 123, make: 'Caterpillar', model: '320D' }
+  )
 ```
 
 ## ⚙️ Configuration
@@ -141,60 +176,309 @@ rails nats_wave:test
 ```bash
 # Required
 NATS_URL=nats://your-nats-server:4222
+
+# Optional - defaults to Rails application name
 NATS_SERVICE_NAME=valuation_service
 
-# Optional
+# 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
 DD_AGENT_PORT=8125
 ```
 
-### Advanced Configuration
+### Complete Configuration Setup
+
+Create or update `config/initializers/nats_wave.rb`:
 
 ```ruby
-# config/initializers/nats_wave.rb
-NatsWave.configure do |config|
-    # NATS Connection
-    config.nats_url = ENV.fetch('NATS_URL')
-    config.service_name = ENV.fetch('NATS_SERVICE_NAME')
-    config.connection_pool_size = 10
-    config.reconnect_attempts = 3
-    
-    # Publishing
-    config.publishing_enabled = !Rails.env.test?
-    config.async_publishing = Rails.env.production?
-    config.default_subject_prefix = "#{config.service_name}.events"
+# frozen_string_literal: true
+
+begin
+    Rails.logger.info "Initializing NATS Wave with URL: #{ENV['NATS_URL']}"
     
-    # Subscription
-    config.subscription_enabled = !Rails.env.test?
-    config.queue_group = "#{config.service_name}_consumers"
+    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'
+    end
     
-    # Middleware
-    config.middleware_authentication_enabled = Rails.env.production?
-    config.auth_secret_key = ENV['NATS_AUTH_SECRET']
-    config.middleware_logging_enabled = true
-    config.log_level = Rails.env.production? ? 'info' : 'debug'
+    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")
     
-    # Error Handling
-    config.max_retries = 3
-    config.retry_delay = 5
+    # Optional: Re-raise in development to catch configuration issues early
+    raise e if Rails.env.development?
 end
 
-# Configure Datadog metrics
-if defined?(Datadog::Statsd)
+# === 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
+    
     NatsWave::Metrics.configure_datadog(
-            namespace: 'valuation_app.nats_wave',
+            namespace: "#{Rails.application.class.name.deconstantize.underscore}.nats_wave",
             tags: {
                     service: NatsWave.configuration.service_name,
-                    environment: Rails.env
+                    environment: Rails.env,
+                    version: app_version
             }
     )
+    Rails.logger.info "📈 Datadog metrics integration enabled"
+end
+
+# === GRACEFUL SHUTDOWN (Optional) ===
+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}"
+    end
 end
 ```
 
+### Environment-Specific Configuration
+
+#### Development Environment
+
+```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
+```
+
+#### Production Environment
+
+```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
+```
+
+#### Test Environment
+
+```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
+    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:
+
+```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>
+```
+
 ## 🏗️ Model-Based Architecture
 
-NatsWave uses a model-centric approach where each model defines its own subscriptions and mappings.
+NatsWave uses a model-centric approach where each model defines its own subscriptions and mappings through the *
+*ModelRegistry** system.
 
 ### Publishing Events
 
@@ -235,7 +519,6 @@ class Asset < ApplicationRecord
     
     # Map from inventory management system
     nats_wave_maps_from 'InventoryAsset',
-                        subjects: ['inventory.assets.*', 'warehouse.assets.*'],
                         field_mappings: {
                                 'inventory_id' => 'unique_id',
                                 'asset_description' => 'description',
@@ -255,44 +538,28 @@ class Asset < ApplicationRecord
                         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
+    # Map from auction system (different external model name)
     nats_wave_maps_from 'AuctionItem',
-                        subjects: ['auction.items.*'],
                         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'
-                        }
-end
-```
-
-### Custom Event Handlers
-
-```ruby
-
-class Estimate < ApplicationRecord
-    include NatsWave::Concerns::Mappable
-    
-    # Subscribe to valuation requests
-    nats_wave_subscribes_to 'valuation.requests.*' do |message|
-        ValuationRequestProcessor.process_request(message)
-    end
-    
-    # Subscribe to market price updates
-    nats_wave_subscribes_to 'market.prices.*' do |message|
-        MarketPriceService.update_estimates(message)
-    end
+                        },
+                        subjects: ['auction_service.items.*']
     
-    # Subscribe to auction results for comparison
-    nats_wave_subscribes_to 'auction.results.*' do |message|
-        AuctionResultAnalyzer.analyze_accuracy(message)
+    # Custom subscription with handler
+    nats_wave_subscribes_to "market_service.prices.*" do |message|
+        MarketPriceService.update_asset_estimates(message)
     end
 end
 ```
@@ -301,10 +568,10 @@ end
 
 ### Automatic Publishing
 
-Events are automatically published when you include `NatsPublishable` in your models:
+Events are automatically published when you include `NatsPublishable`:
 
 ```ruby
-# This automatically publishes to "valuation_service.events.asset.create"
+# This automatically publishes to "valuation_service.events.assets.create"
 asset = Asset.create!(
         make: "Caterpillar",
         model: "320D",
@@ -313,10 +580,10 @@ asset = Asset.create!(
         description: "Excavator - Track Type"
 )
 
-# This publishes to "valuation_service.events.asset.update"
+# This publishes to "valuation_service.events.assets.update"
 asset.update!(estimated_hammer: 125000)
 
-# This publishes to "valuation_service.events.asset.destroy"
+# This publishes to "valuation_service.events.assets.destroy" 
 asset.destroy!
 ```
 
@@ -354,43 +621,22 @@ end
 NatsWave.client.publish_batch(events)
 ```
 
-### Conditional Publishing
-
-```ruby
-
-class Asset < ApplicationRecord
-    include NatsWave::NatsPublishable
-    
-    nats_publishable(
-            if: -> { should_publish_to_external_systems? },
-            unless: -> { asset_status == 'draft' }
-    )
-    
-    private
-    
-    def should_publish_to_external_systems?
-        asset_status == 'completed' &&
-                package.workflow_status == 'finalized' &&
-                !package.is_shared?
-    end
-end
-```
-
 ## 📥 Subscribing to Events
 
-### Automatic Model Syncing
+### Automatic Model Syncing with Field Mapping
 
 When you configure `nats_wave_maps_from`, NatsWave automatically:
 
-1. Subscribes to the specified subjects
-2. Transforms incoming data using field mappings
-3. Applies custom transformations
-4. Syncs data to your local models
+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
-# Incoming message from inventory system:
+# Example: Incoming message from inventory system
 {
-        "subject": "inventory.assets.update",
+        "subject": "inventory_service.assets.update",
         "model": "InventoryAsset",
         "action": "update",
         "data": {
@@ -401,139 +647,327 @@ When you configure `nats_wave_maps_from`, NatsWave automatically:
                 "year_built": "2020",
                 "serial_num": "1FTFW1ET5LFA12345",
                 "vin_code": "1FTFW1ET5LFA12345",
-                "estimated_value": 35000.00
+                "estimated_value": 35000.00,
+                "status": "available"
+        },
+        "source": {
+                "service": "inventory_service",
+                "instance_id": "inv-worker-1"
         }
 }
 
-# Automatically transforms to:
+# NatsWave automatically transforms this to:
 {
         "unique_id": "INV-2024-001",
         "description": "2020 Ford F-150 Pickup Truck",
-        "make": "FORD",
+        "make": "FORD", # Uppercased via transformation
         "model": "F-150",
-        "year": 2020,
+        "year": 2020, # Converted to integer
         "serial": "1FTFW1ET5LFA12345",
         "vin": "1FTFW1ET5LFA12345",
         "estimated_hammer": 35000.00
 }
 
-# And updates/creates the local Asset record
+# And creates/updates the local Asset record using unique_fields [:unique_id, :vin, :serial]
+```
+
+## 🗺️ Data Mapping & Transformation
+
+### 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.*'
+                    ]
 ```
 
-### Custom Subscription Handlers
+### Advanced Transformations
 
 ```ruby
 
-class Organization < ApplicationRecord
+class Asset < ApplicationRecord
     include NatsWave::Concerns::Mappable
     
-    # Process user activity for analytics
-    nats_wave_subscribes_to 'users.*.login', 'users.*.logout' do |message|
-        UserActivityTracker.track_activity(message)
+    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
     
-    # Process package completions with custom queue group
-    nats_wave_subscribes_to 'packages.*.completed',
-                            queue_group: 'reporting_processors' do |message|
-        PackageCompletionReporter.generate_report(message)
+    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
 ```
 
-## 🗺️ Data Mapping & Transformation
+## 🔀 Cross-Service Integration
 
-### Field Mappings
+### Handling Different Services with Same Model Names
 
 ```ruby
-nats_wave_maps_from 'ExternalAsset',
-                    field_mappings: {
-                            'external_id' => 'unique_id',
-                            'asset_make' => 'make',
-                            'asset_model' => 'model',
-                            'manufacture_year' => 'year',
-                            'serial_number' => 'serial',
-                            'vehicle_identification' => 'vin',
-                            'asset_location' => 'location'
-                    }
+
+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
+    end
+end
 ```
 
-### Data Transformations
+### Using Different External Model Names
 
 ```ruby
-nats_wave_maps_from 'ExternalAsset',
-                    transformations: {
-                            # Lambda transformations
-                            'estimated_hammer' => ->(value) { value.to_f.round(2) },
-                            'make' => ->(make) { make&.upcase&.strip },
-                            'model' => ->(model) { model&.titleize&.strip },
-                            
-                            # Method transformations
-                            'vin' => :normalize_vin,
-                            'serial' => :normalize_serial,
-                            
-                            # Complex transformations with access to full record
-                            'description' => ->(value, record) {
-                                "#{record['year']} #{record['make']} #{record['model']} #{value}".strip
-                            }
-                    }
-
-private
 
-def normalize_vin(vin)
-    vin&.upcase&.gsub(/[^A-Z0-9]/, '')
-end
-
-def normalize_serial(serial)
-    serial&.upcase&.strip
+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]
 end
 ```
 
-### Conditional Syncing
+## 🎯 Message Processing & Handlers
+
+### Automatic Message Processing
+
+NatsWave includes a comprehensive `MessageHandler` that automatically processes mapped messages:
 
 ```ruby
-nats_wave_maps_from 'ExternalAsset',
-                    conditions: {
-                            'status' => 'available', # Exact match
-                            'condition' => ['good', 'fair', 'excellent'], # Array inclusion
-                            'value' => ->(value) { value.to_f > 1000 }, # Custom logic
-                            'category' => /^(vehicle|equipment|machinery)$/ # Regex match
-                    }
+# 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
 ```
 
-### Sync Strategies
+### Custom Message Handlers
 
 ```ruby
-nats_wave_maps_from 'ExternalAsset',
-                    sync_strategy: :upsert, # Create or update (default)
-                    # sync_strategy: :create_only, # Only create new records
-                    # sync_strategy: :update_only, # Only update existing records
-                    unique_fields: [:unique_id, :vin, :serial] # Fields to match existing records
+
+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
+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)
+    end
+end
 ```
 
 ## 📊 Monitoring & Metrics
 
+### ModelRegistry Inspection
+
+```ruby
+# View all registered subscriptions
+NatsWave::ModelRegistry.debug_registrations
+
+# Get subscription statistics
+stats = NatsWave::ModelRegistry.subscription_stats
+# => {
+#   total_subscriptions: 5,
+#   unique_subjects: 8, 
+#   models_with_subscriptions: 3,
+#   subscription_breakdown: {"Asset"=>2, "Package"=>2, "User"=>1}
+# }
+
+# View all mappings
+mappings = NatsWave::ModelRegistry.all_mappings
+# => {
+#   local_to_external: {...},
+#   external_to_local: {"InventoryItem" => {"Asset" => {...}}}
+# }
+
+# Find local models for external model
+local_models = NatsWave::ModelRegistry.local_models_for('InventoryItem')
+# => {"Asset" => {field_mappings: {...}, transformations: {...}}}
+```
+
 ### Datadog Integration
 
-NatsWave provides comprehensive Datadog metrics out of the box:
+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.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.valuations.completed # Valuation completion events
--nats_wave.assets.synced # Asset synchronization events
+-nats_wave.model_registry.subscriptions # Active subscriptions
 ```
 
 ### Health Checks
 
 ```ruby
-# Built-in health check endpoint
-GET /health/n ats_wave
+# Built-in health check
+health = NatsWave.health_check
 
 # Response:
 {
@@ -541,71 +975,51 @@ GET /health/n ats_wave
         "database_connected": true,
         "timestamp": "2024-01-01T12:00:00Z",
         "service_name": "valuation_service",
-        "version": "1.1.1",
+        "version": "1.2.0",
         "instance_id": "web-1",
         "published_subjects": [
-                "valuation_service.events.asset.*",
-                "valuation_service.events.package.*",
-                "valuation_service.events.estimate.*"
+                "valuation_service.events.assets.*",
+                "valuation_service.events.packages.*"
         ],
         "subscribed_subjects": [
-                "inventory.assets.*",
-                "auction.results.*",
-                "market.prices.*"
+                "inventory_service.items.*",
+                "auction_service.assets.*"
         ],
-        "nats_url": "nats://your-server:4222"
+        "model_registry_stats": {
+                "total_subscriptions": 5,
+                "unique_subjects": 8
+        }
 }
 ```
 
-### Monitoring Commands
-
-```bash
-# Check overall health
-rails nats_wave:health
-
-# Show all model subscriptions
-rails nats_wave:model_subscriptions
-
-# Monitor live NATS activity
-rails nats_wave:monitor
-
-# Show failed messages
-rails nats_wave:show_failed
-
-# Retry failed messages
-rails nats_wave:retry_failed
-```
-
 ## 🛡️ Error Handling
 
 ### Dead Letter Queue
 
-Failed messages are automatically stored in a dead letter queue with retry logic:
+Failed messages are automatically stored with retry logic:
 
 ```ruby
 # Automatic retry with exponential backoff
 # Retry 1: after 5 seconds
-# Retry 2: after 25 seconds  
-# Retry 3: after 125 seconds
+# Retry 2: after 25 seconds
+# Retry 3: after 125 seconds  
 # After max retries: moved to permanent failure storage
 ```
 
-### Error Recovery
+### Error Recovery Commands
+
+```bash
+# View failed messages
+rails nats_wave:show_failed
 
-```ruby
 # Retry failed messages
-rails nats_wave: retry_failed
+rails nats_wave:retry_failed
 
 # Clear failed messages (after manual review)
-rails nats_wave: clear_failed
+rails nats_wave:clear_failed
 
-# View failed message details
-failed_messages = NatsWave::DeadLetterQueue.new(NatsWave.configuration)
-failed_messages.get_failed_messages.each do |msg|
-    puts "Error: #{msg[:error]}"
-    puts "Retry Count: #{msg[:retry_count]}"
-    puts "Message: #{msg[:message]}"
-end
+# Monitor live activity
+rails nats_wave:monitor
 ```
 
 ### Custom Error Handling
@@ -621,9 +1035,85 @@ class CustomErrorHandler
                 service: 'nats_wave'
         })
         
-        # Custom retry logic for valuation-specific errors
-        if retry_count < 5 && error.is_a?(ValuationTimeoutError)
-            RetryValuationJob.set(wait: 30.seconds).perform_later(message)
+        # Custom retry logic for specific errors
+        if error.is_a?(ValidationError) && retry_count < 5
+            RetryValidationJob.set(wait: 30.seconds).perform_later(message)
+        end
+    end
+end
+```
+
+## 🧪 Testing
+
+### Test Configuration
+
+```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)
+    end
+end
+```
+
+### Testing Model Subscriptions
+
+```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
+    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
     end
 end
@@ -651,30 +1141,21 @@ EXPOSE 3000
 CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]
 ```
 
-### Docker Compose
+### Environment Configuration
 
-```yaml
-# docker-compose.yml
-version: '3.8'
-services:
-  nats:
-    image: nats:latest
-    ports:
-      - "4222:4222"
-      - "8222:8222"
-    command: "--http_port 8222 --js"
+```bash
+# Production environment variables
+NATS_URL=nats://nats-cluster:4222
+NATS_SERVICE_NAME=valuation_service
+NATS_AUTH_SECRET=your-production-secret
 
-  valuation_app:
-    build: .
-    depends_on:
-      - nats
-      - redis
-      - postgres
-    environment:
-      - NATS_URL=nats://nats:4222
-      - NATS_SERVICE_NAME=valuation_service
-    ports:
-      - "3000:3000"
+# Monitoring
+DD_AGENT_HOST=datadog-agent
+DD_AGENT_PORT=8125
+
+# Performance
+RAILS_MAX_THREADS=10
+WEB_CONCURRENCY=3
 ```
 
 ### Kubernetes Deployment
@@ -711,131 +1192,442 @@ spec:
               port: 3000
             initialDelaySeconds: 30
             periodSeconds: 10
-```
-
-### Separate Subscriber Process
-
-For high-volume applications, run subscribers in dedicated processes:
-
-```bash
-# Procfile
-web: bundle exec rails server -p $PORT
-worker: bundle exec rails nats_wave:start
+          readinessProbe:
+            httpGet:
+              path: /health/nats_wave
+              port: 3000
+            initialDelaySeconds: 5
+            periodSeconds: 5
 ```
 
 ## 💡 Examples
 
-### Asset Management Integration
+### Complete Asset Valuation Integration
 
 ```ruby
 # app/models/asset.rb
 class Asset < ApplicationRecord
-    include NatsWave::NatsPublishable
-    include NatsWave::Concerns::Mappable
+  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',
+    field_mappings: {
+      'inventory_id' => 'unique_id',
+      'asset_description' => 'description',
+      'manufacturer' => 'make',
+      '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: {
+      '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 || 'in_progress' }
+    },
+    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.*']
     
-    nats_publishable(
-            actions: [:create, :update],
-            include_associations: [:package, :estimates, :images]
-    )
+  # Sync from auction management system
+  nats_wave_maps_from 'AuctionLot',
+    field_mappings: {
+      'lot_number' => 'lot_number',
+      'hammer_price' => 'pw_contract_price',
+      'sale_date' => 'pw_contract_date',
+      'auction_house' => 'pw_auction'
+    },
+    transformations: {
+      '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.*']
     
-    # Sync from inventory management system
-    nats_wave_maps_from 'InventoryItem',
-                        subjects: ['inventory.items.*'],
-                        field_mappings: {
-                                'item_id' => 'unique_id',
-                                'description' => 'description',
-                                'manufacturer' => 'make',
-                                'model_name' => 'model',
-                                'year_manufactured' => 'year',
-                                'serial_number' => 'serial',
-                                'vin_number' => 'vin',
-                                'location_code' => 'location'
-                        },
-                        transformations: {
-                                'estimated_hammer' => ->(value) { value.to_f.round(2) },
-                                'make' => ->(make) { make&.upcase&.strip }
-                        }
-    
-    # Sync from auction management
-    nats_wave_maps_from 'AuctionAsset',
-                        subjects: ['auction.assets.*'],
-                        field_mappings: {
-                                'lot_number' => 'lot_number',
-                                'hammer_price' => 'pw_contract_price',
-                                'sale_date' => 'pw_contract_date'
-                        },
-                        conditions: {
-                                'status' => 'sold'
-                        }
+  # Listen for valuation requests
+  nats_wave_subscribes_to 'valuation_service.requests.*' do |message|
+    AssetValuationProcessor.process_request(message)
+  end
+  
+  private
+  
+  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
 end
 
 # app/models/package.rb
 class Package < ApplicationRecord
-    include NatsWave::NatsPublishable
-    
-    nats_publishable(
-            actions: [:create, :update],
-            if: -> { workflow_status == 'finalized' }
-    )
+  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',
+    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'
+    },
+    transformations: {
+      'workflow_status' => ->(status) { 
+        case status&.downcase
+        when 'new', 'created' then 'active'
+        when 'in_progress', 'working' then 'active'
+        when 'completed', 'done' then 'finalized'
+        else 'active'
+        end
+      }
+    },
+    unique_fields: [:key],
+    conditions: {
+      'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }
+    },
+    subjects: ['crm_service.projects.*']
     
-    # Listen for IMS submission confirmations
-    nats_wave_subscribes_to 'ims.submissions.confirmed.*' do |message|
-        package = Package.find_by(id: message['data']['package_id'])
-        package&.mark_as_submitted!
-    end
+  # 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' }
+  )
+  
+  # Sync from external valuation services
+  nats_wave_maps_from 'ExternalValuation',
+    field_mappings: {
+      'valuation_id' => 'key',
+      'asset_identifier' => 'asset_id',
+      'appraiser_id' => 'user_id',
+      'estimated_value' => 'value',
+      'valuation_notes' => 'notes',
+      'valuation_type' => 'estimate_type_id'
+    },
+    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 }
+    },
+    unique_fields: [:key],
+    conditions: {
+      'source.service' => ->(service) { service != ENV['NATS_SERVICE_NAME'] }
+    },
+    subjects: ['valuation_service.estimates.*']
+end
+
+# 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',
+    field_mappings: {
+      'user_id' => 'key',
+      'email_address' => 'email',
+      'full_name' => 'name',
+      'is_active' => 'active',
+      'organization_key' => 'current_organization_key'
+    },
+    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.*']
+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',
+    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'
+    },
+    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
 ```
 
-### Valuation Workflow
+### Cross-Service Workflow Example
 
 ```ruby
-# app/models/estimate.rb
-class Estimate < ApplicationRecord
-    include NatsWave::NatsPublishable
-    include NatsWave::Concerns::Mappable
-    
-    nats_publishable(
-            skip_attributes: [:notes, :source_data]
-    )
-    
-    # Sync from external valuation service
-    nats_wave_maps_from 'ExternalValuation',
-                        subjects: ['valuations.external.*'],
-                        field_mappings: {
-                                'valuation_id' => 'key',
-                                'asset_identifier' => 'asset_id',
-                                'appraiser_id' => 'user_id',
-                                'estimated_value' => 'value',
-                                'valuation_notes' => 'notes'
-                        },
-                        transformations: {
-                                'value' => ->(value) { (value.to_f * 100).round }, # Convert to cents
-                                'notes' => ->(notes) { notes&.strip }
-                        },
-                        unique_fields: [:key, :asset_id, :user_id]
+# 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
+    end
     
-    # Listen for market price updates
-    nats_wave_subscribes_to 'market.prices.*' do |message|
-        MarketPriceAnalyzer.update_estimates_based_on_market(message)
+    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
 
-# app/models/valuation_request.rb
-class ValuationRequest < ApplicationRecord
-    include NatsWave::NatsPublishable
-    
-    nats_publishable(
-            actions: [:create, :update]
-    )
-    
-    # Process valuation assignments
-    nats_wave_subscribes_to 'valuations.assignments.*' do |message|
-        ValuationAssignmentProcessor.process_assignment(message)
+# 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
 ```
 
-### Organization & User Management
+### User & Organization Sync
 
 ```ruby
 # app/models/user.rb
@@ -844,37 +1636,45 @@ class User < ApplicationRecord
     include NatsWave::Concerns::Mappable
     
     nats_publishable(
-            skip_attributes: [:api_auth_key, :source_details]
+            skip_attributes: [:api_auth_key, :source_details],
+            subject_prefix: 'users'
     )
     
     # Sync from authentication service
     nats_wave_maps_from 'AuthUser',
-                        subjects: ['auth.users.*'],
                         field_mappings: {
                                 'user_id' => 'key',
                                 'email_address' => 'email',
                                 'full_name' => 'name',
-                                'is_active' => 'active'
+                                'is_active' => 'active',
+                                'organization_id' => 'current_organization_key'
                         },
                         transformations: {
-                                'email' => ->(email) { email&.downcase },
+                                'email' => ->(email) { email&.downcase&.strip },
+                                'name' => ->(name) { name&.titleize&.strip },
                                 'active' => ->(active) { active == 'true' || active == true }
                         },
-                        unique_fields: [:key, :email]
+                        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)
+    end
 end
 
-# app/models/organization.rb
+# app/models/organization.rb  
 class Organization < ApplicationRecord
     include NatsWave::NatsPublishable
     include NatsWave::Concerns::Mappable
     
     nats_publishable(
-            skip_attributes: [:api_auth_key, :workflow_config]
+            skip_attributes: [:api_auth_key, :workflow_config],
+            subject_prefix: 'organizations'
     )
     
     # Sync from CRM system
     nats_wave_maps_from 'CRMOrganization',
-                        subjects: ['crm.organizations.*'],
                         field_mappings: {
                                 'organization_id' => 'key',
                                 'company_name' => 'name',
@@ -883,53 +1683,18 @@ class Organization < ApplicationRecord
                                 'phone_number' => 'phone',
                                 'is_active' => 'active'
                         },
-                        unique_fields: [:key, :name]
-end
-```
-
-### Image and Media Processing
-
-```ruby
-# app/models/image.rb
-class Image < ApplicationRecord
-    include NatsWave::NatsPublishable
-    
-    nats_publishable(
-            actions: [:create, :update],
-            skip_attributes: [:source_data, :import_url],
-            if: -> { !deleted? && sizes.present? }
-    )
-    
-    # Listen for image processing completion
-    nats_wave_subscribes_to 'media.processing.completed.*' do |message|
-        ImageProcessingService.handle_completion(message)
-    end
-    
-    # Listen for IMS image submissions
-    nats_wave_subscribes_to 'ims.images.*' do |message|
-        IMSImageProcessor.process_submission(message)
-    end
-end
-
-# app/models/video.rb
-class Video < ApplicationRecord
-    include NatsWave::NatsPublishable
-    
-    nats_publishable(
-            actions: [:create, :update],
-            if: -> { !deleted? && url.present? }
-    )
-    
-    # Listen for video processing updates
-    nats_wave_subscribes_to 'media.videos.*' do |message|
-        VideoProcessingService.handle_update(message)
-    end
+                        transformations: {
+                                'name' => ->(name) { name&.strip },
+                                'email' => ->(email) { email&.downcase&.strip }
+                        },
+                        unique_fields: [:key, :name],
+                        subjects: ['crm_service.organizations.*']
 end
 ```
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CODE_OF_CONDUCT.md) for details.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
 ### Development Setup
 
@@ -948,19 +1713,6 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
-### Testing
-
-```bash
-# Run all tests
-bundle exec rspec
-
-# Run specific test files
-bundle exec rspec spec/nats_wave/publisher_spec.rb
-
-# Run with coverage
-COVERAGE=true bundle exec rspec
-```
-
 ## 📝 Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for details about changes in each version.
@@ -982,4 +1734,4 @@ our microservices and teams in the asset valuation and auction industry.
 
 ---
 
-**Made with ❤️ by Jeffrey Dabo**
+**Made with ❤️ by the Purple Wave Team**