smart_domain 0.1.0

data/lib/smart_domain/handlers/audit_handler.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Handlers
+    # Generic audit handler for domain events.
+    #
+    # This handler provides standardized audit logging for any domain.
+    # It logs all events with structured data and optionally writes to
+    # an audit_events table for compliance.
+    #
+    # Features:
+    # - Structured logging to Rails logger
+    # - Optional database audit table writes
+    # - Event categorization (authentication, data_access, admin_action, etc.)
+    # - Risk level assessment (HIGH, MEDIUM, LOW)
+    # - Field extraction from event mixins
+    #
+    # @example
+    #   user_audit = SmartDomain::Handlers::AuditHandler.new('user')
+    #   SmartDomain::Event.bus.subscribe('user.created', user_audit)
+    #   SmartDomain::Event.bus.subscribe('user.updated', user_audit)
+    #
+    # Or use the registration helper for one-line setup:
+    #   SmartDomain::Event::Registration.register_standard_handlers(
+    #     domain: 'user',
+    #     events: ['created', 'updated', 'deleted'],
+    #     include_audit: true
+    #   )
+    class AuditHandler < Event::Handler
+      attr_reader :domain, :logger
+
+      # Initialize audit handler for a specific domain
+      # @param domain [String] Domain name (e.g., 'user', 'order', 'product')
+      def initialize(domain)
+        super()
+        @domain = domain
+        @logger = SmartDomain.configuration.logger
+      end
+
+      # Check if this handler can handle an event type
+      # @param event_type [String] Event type to check
+      # @return [Boolean] True if event belongs to this domain
+      def can_handle?(event_type)
+        return true if @domain == "*"
+
+        event_type.start_with?("#{@domain}.")
+      end
+
+      # Handle audit logging for an event
+      # @param event [SmartDomain::Event::Base] Event to audit
+      def handle(event)
+        action = event.event_type.split(".").last
+
+        # 1. Log to Rails logger (structured)
+        log_audit_event(event, action)
+
+        # 2. Write to audit_events table (if configured)
+        write_to_audit_table(event) if SmartDomain.configuration.audit_table_enabled?
+      rescue StandardError => e
+        # Never fail on audit handler errors
+        @logger.warn "[SmartDomain::AuditHandler] Audit logging failed: #{e.message}"
+        @logger.warn e.backtrace.join("\n")
+      end
+
+      private
+
+      # Log event to Rails logger with structured data
+      # @param event [SmartDomain::Event::Base] Event to log
+      # @param action [String] Event action (e.g., 'created', 'updated')
+      def log_audit_event(event, action)
+        log_data = build_log_data(event)
+        message = "[AUDIT] #{event.aggregate_type} #{action}"
+        @logger.info("#{message} - #{log_data.to_json}")
+      end
+
+      # Build structured log data from event
+      # @param event [SmartDomain::Event::Base] Event to extract data from
+      # @return [Hash] Structured log data
+      def build_log_data(event)
+        log_data = {
+          audit: true,
+          event_id: event.event_id,
+          event_type: event.event_type,
+          aggregate_type: event.aggregate_type,
+          aggregate_id: event.aggregate_id,
+          organization_id: event.organization_id,
+          occurred_at: event.occurred_at.iso8601
+        }
+
+        # Add all event-specific fields (including mixin fields)
+        event.attributes.each do |key, value|
+          next if log_data.key?(key.to_sym) || value.nil?
+
+          log_data[key.to_sym] = serialize_value(value)
+        end
+
+        log_data
+      end
+
+      # Serialize a value for logging
+      # @param value [Object] Value to serialize
+      # @return [Object] Serialized value
+      def serialize_value(value)
+        case value
+        when Time, DateTime, Date
+          value.iso8601
+        when Hash, Array
+          value
+        else
+          value
+        end
+      end
+
+      # Write event to audit_events table for compliance
+      # @param event [SmartDomain::Event::Base] Event to write
+      def write_to_audit_table(event)
+        return unless defined?(AuditEvent)
+
+        AuditEvent.create!(
+          event_type: event.event_type.upcase.tr(".", "_"),
+          event_category: map_event_category(event.event_type),
+          user_id: extract_actor_id(event),
+          organization_id: event.organization_id,
+          ip_address: extract_ip_address(event),
+          user_agent: extract_user_agent(event),
+          old_values: extract_old_values(event),
+          new_values: extract_new_values(event),
+          occurred_at: event.occurred_at,
+          risk_level: assess_risk_level(event.event_type),
+          compliance_flags: build_compliance_flags(event)
+        )
+      rescue StandardError => e
+        @logger.warn "[SmartDomain::AuditHandler] Failed to write to audit table: #{e.message}"
+      end
+
+      # Map event type to audit category
+      # @param event_type [String] Event type
+      # @return [String] Audit category
+      def map_event_category(event_type)
+        case event_type
+        when /^auth\./
+          "authentication"
+        when /accessed|viewed|patient\./
+          "data_access"
+        when /created|updated|deleted|assigned|removed/
+          "admin_action"
+        else
+          "system_event"
+        end
+      end
+
+      # Assess risk level of event
+      # @param event_type [String] Event type
+      # @return [String] Risk level (HIGH, MEDIUM, LOW)
+      def assess_risk_level(event_type)
+        case event_type
+        when /suspended|deleted|revoked|failed|rejected/
+          "HIGH"
+        when /updated|changed|assigned/
+          "MEDIUM"
+        else
+          "LOW"
+        end
+      end
+
+      # Extract actor_id from event (ActorMixin)
+      # @param event [SmartDomain::Event::Base] Event
+      # @return [String, nil] Actor ID
+      def extract_actor_id(event)
+        event.try(:actor_id) || event.attributes["actor_id"]
+      end
+
+      # Extract ip_address from event (SecurityContextMixin)
+      # @param event [SmartDomain::Event::Base] Event
+      # @return [String, nil] IP address
+      def extract_ip_address(event)
+        event.try(:ip_address) || event.attributes["ip_address"]
+      end
+
+      # Extract user_agent from event (SecurityContextMixin)
+      # @param event [SmartDomain::Event::Base] Event
+      # @return [String, nil] User agent
+      def extract_user_agent(event)
+        event.try(:user_agent) || event.attributes["user_agent"]
+      end
+
+      # Extract old_values from event (ChangeTrackingMixin)
+      # @param event [SmartDomain::Event::Base] Event
+      # @return [Hash, nil] Old values
+      def extract_old_values(event)
+        event.try(:old_values) || event.attributes["old_values"]
+      end
+
+      # Extract new_values from event (ChangeTrackingMixin)
+      # @param event [SmartDomain::Event::Base] Event
+      # @return [Hash, nil] New values
+      def extract_new_values(event)
+        event.try(:new_values) || event.attributes["new_values"]
+      end
+
+      # Build compliance flags for audit record
+      # @param event [SmartDomain::Event::Base] Event
+      # @return [Hash] Compliance flags
+      def build_compliance_flags(event)
+        {
+          event_id: event.event_id,
+          aggregate_id: event.aggregate_id,
+          aggregate_type: event.aggregate_type,
+          domain: @domain,
+          correlation_id: event.correlation_id,
+          causation_id: event.causation_id
+        }.compact
+      end
+    end
+  end
+end

data/lib/smart_domain/handlers/metrics_handler.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Handlers
+    # Generic metrics handler for domain events.
+    #
+    # This handler collects metrics from domain events for monitoring
+    # and analytics. It can integrate with metrics systems like StatsD,
+    # Datadog, Prometheus, or CloudWatch.
+    #
+    # By default, it logs metrics to the Rails logger. You can override
+    # #emit_metric to send to your metrics backend.
+    #
+    # @example
+    #   user_metrics = SmartDomain::Handlers::MetricsHandler.new('user')
+    #   SmartDomain::Event.bus.subscribe('user.created', user_metrics)
+    #
+    # @example Custom metrics backend
+    #   class CustomMetricsHandler < SmartDomain::Handlers::MetricsHandler
+    #     def emit_metric(metric_name, tags)
+    #       StatsD.increment(metric_name, tags: tags)
+    #     end
+    #   end
+    class MetricsHandler < Event::Handler
+      attr_reader :domain, :logger
+
+      # Initialize metrics handler for a specific domain
+      # @param domain [String] Domain name (e.g., 'user', 'order', 'product')
+      def initialize(domain)
+        super()
+        @domain = domain
+        @logger = SmartDomain.configuration.logger
+      end
+
+      # Check if this handler can handle an event type
+      # @param event_type [String] Event type to check
+      # @return [Boolean] True if event belongs to this domain
+      def can_handle?(event_type)
+        return true if @domain == "*"
+
+        event_type.start_with?("#{@domain}.")
+      end
+
+      # Handle metrics collection for an event
+      # @param event [SmartDomain::Event::Base] Event to collect metrics from
+      def handle(event)
+        metric_name = build_metric_name(event)
+        tags = build_metric_tags(event)
+
+        emit_metric(metric_name, tags)
+      rescue StandardError => e
+        # Never fail on metrics handler errors
+        @logger.warn "[SmartDomain::MetricsHandler] Metrics collection failed: #{e.message}"
+      end
+
+      private
+
+      # Build metric name from event
+      # @param event [SmartDomain::Event::Base] Event
+      # @return [String] Metric name (e.g., 'domain_events.user.created')
+      def build_metric_name(event)
+        "domain_events.#{event.event_type}"
+      end
+
+      # Build metric tags from event
+      # @param event [SmartDomain::Event::Base] Event
+      # @return [Hash] Metric tags
+      def build_metric_tags(event)
+        {
+          aggregate_type: event.aggregate_type,
+          organization_id: event.organization_id,
+          domain: @domain
+        }
+      end
+
+      # Emit metric to backend
+      #
+      # Override this method to integrate with your metrics backend.
+      # Default implementation logs to Rails logger.
+      #
+      # @param metric_name [String] Metric name
+      # @param tags [Hash] Metric tags
+      def emit_metric(metric_name, tags)
+        @logger.info("[METRIC] #{metric_name} - #{tags.to_json}")
+
+        # Example integrations (commented out):
+        #
+        # StatsD:
+        # StatsD.increment(metric_name, tags: tags)
+        #
+        # Datadog:
+        # Datadog::Statsd.new.increment(metric_name, tags: tags.map { |k, v| "#{k}:#{v}" })
+        #
+        # Prometheus:
+        # counter = Prometheus::Client.registry.counter(
+        #   metric_name.tr('.', '_').to_sym,
+        #   docstring: 'Domain event counter',
+        #   labels: tags.keys
+        # )
+        # counter.increment(labels: tags)
+      end
+    end
+  end
+end

data/lib/smart_domain/integration/active_record.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Integration
+    # ActiveRecord integration for domain events.
+    #
+    # This module provides ActiveRecord models with the ability to queue
+    # and publish domain events after transactions commit successfully.
+    #
+    # Key features:
+    # - Events are queued during the request/transaction
+    # - Events are published AFTER the database transaction commits
+    # - If transaction rolls back, events are discarded
+    # - Thread-safe event queue per model instance
+    #
+    # @example Include in a model
+    #   class User < ApplicationRecord
+    #     include SmartDomain::Integration::ActiveRecord
+    #
+    #     after_create :publish_created_event
+    #     after_update :publish_updated_event
+    #
+    #     private
+    #
+    #     def publish_created_event
+    #       add_domain_event(UserCreatedEvent.new(
+    #         event_type: 'user.created',
+    #         aggregate_id: id,
+    #         aggregate_type: 'User',
+    #         organization_id: organization_id,
+    #         user_id: id,
+    #         email: email
+    #       ))
+    #     end
+    #
+    #     def publish_updated_event
+    #       add_domain_event(UserUpdatedEvent.new(
+    #         event_type: 'user.updated',
+    #         aggregate_id: id,
+    #         aggregate_type: 'User',
+    #         organization_id: organization_id,
+    #         user_id: id,
+    #         changed_fields: saved_changes.keys,
+    #         old_values: saved_changes.transform_values(&:first),
+    #         new_values: saved_changes.transform_values(&:last)
+    #       ))
+    #     end
+    #   end
+    module ActiveRecord
+      extend ActiveSupport::Concern
+
+      included do
+        # Register after_commit callback to publish events
+        after_commit :publish_domain_events
+
+        # Register after_rollback callback to clear events
+        after_rollback :clear_domain_events
+      end
+
+      # Queue a domain event for publishing after commit
+      #
+      # Events are stored in an instance variable and published
+      # when the transaction commits successfully.
+      #
+      # @param event [SmartDomain::Event::Base] Event to queue
+      #
+      # @example
+      #   user = User.new(email: 'test@example.com')
+      #   user.save!
+      #
+      #   # In after_create callback
+      #   event = UserCreatedEvent.new(...)
+      #   add_domain_event(event)
+      def add_domain_event(event)
+        @pending_domain_events ||= []
+        @pending_domain_events << event
+      end
+
+      # Queue multiple domain events
+      #
+      # @param events [Array<SmartDomain::Event::Base>] Events to queue
+      def add_domain_events(events)
+        events.each { |event| add_domain_event(event) }
+      end
+
+      # Get pending events (useful for debugging/testing)
+      #
+      # @return [Array<SmartDomain::Event::Base>] Queued events
+      def pending_domain_events
+        @pending_domain_events || []
+      end
+
+      # Build an event with automatic field population
+      #
+      # This helper automatically fills in common event fields from the model:
+      # - aggregate_id: Uses model's id
+      # - aggregate_type: Uses model's class name
+      # - organization_id: Uses model's organization_id (if present)
+      #
+      # @param event_class [Class] Event class to instantiate
+      # @param attributes [Hash] Additional event attributes
+      # @return [SmartDomain::Event::Base] Instantiated event
+      #
+      # @example
+      #   event = build_domain_event(UserCreatedEvent,
+      #     event_type: 'user.created',
+      #     user_id: id,
+      #     email: email
+      #   )
+      #   add_domain_event(event)
+      def build_domain_event(event_class, attributes = {})
+        # Auto-fill aggregate fields
+        attributes[:aggregate_id] ||= id.to_s
+        attributes[:aggregate_type] ||= self.class.name
+
+        # Auto-fill organization_id if model has it
+        if respond_to?(:organization_id) && organization_id.present?
+          attributes[:organization_id] ||= organization_id.to_s
+        end
+
+        event_class.new(attributes)
+      end
+
+      # Helper to extract changes for ChangeTrackingMixin
+      #
+      # @return [Hash] Hash with changed_fields, old_values, new_values
+      def domain_event_changes
+        return { changed_fields: [], old_values: {}, new_values: {} } unless respond_to?(:saved_changes)
+
+        changes = saved_changes
+        {
+          changed_fields: changes.keys,
+          old_values: changes.transform_values(&:first),
+          new_values: changes.transform_values(&:last)
+        }
+      end
+
+      private
+
+      # Publish all pending events after commit
+      #
+      # This callback is automatically registered when the module is included.
+      # It publishes all queued events to the event bus and clears the queue.
+      def publish_domain_events
+        return if @pending_domain_events.blank?
+
+        @pending_domain_events.each do |event|
+          begin
+            SmartDomain::Event.bus.publish(event)
+          rescue StandardError => e
+            # Log error but don't raise (events should be fire-and-forget)
+            logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+            logger.error "[SmartDomain] Failed to publish event: #{e.message}"
+            logger.error e.backtrace.join("\n")
+          end
+        end
+
+        clear_domain_events
+      end
+
+      # Clear pending events
+      #
+      # Called after successful publish or after transaction rollback
+      def clear_domain_events
+        @pending_domain_events = []
+      end
+    end
+  end
+end

data/lib/smart_domain/integration/multi_tenancy.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Integration
+    # Multi-tenancy support for SmartDomain.
+    #
+    # Provides thread-safe tenant context management for multi-tenant applications.
+    # The current tenant is stored in thread-local storage to ensure isolation
+    # between concurrent requests.
+    #
+    # @example Set tenant in a controller
+    #   class ApplicationController < ActionController::Base
+    #     around_action :set_current_tenant
+    #
+    #     private
+    #
+    #     def set_current_tenant
+    #       SmartDomain::Integration::TenantContext.with_tenant(current_organization.id) do
+    #         yield
+    #       end
+    #     end
+    #   end
+    #
+    # @example Use in service
+    #   class UserService < SmartDomain::Domain::Service
+    #     def create_user(attributes)
+    #       tenant_id = SmartDomain::Integration::TenantContext.current
+    #       # ... use tenant_id ...
+    #     end
+    #   end
+    module TenantContext
+      # Get the current tenant ID from thread-local storage
+      #
+      # @return [String, Integer, nil] Current tenant ID
+      def self.current
+        Thread.current[:smart_domain_tenant_id]
+      end
+
+      # Set the current tenant ID
+      #
+      # @param tenant_id [String, Integer, nil] Tenant ID to set
+      def self.current=(tenant_id)
+        Thread.current[:smart_domain_tenant_id] = tenant_id
+      end
+
+      # Execute a block within a tenant context
+      #
+      # Ensures the previous tenant is restored after the block executes,
+      # even if an exception is raised.
+      #
+      # @param tenant_id [String, Integer] Tenant ID
+      # @yield Block to execute within tenant context
+      # @return [Object] Result of the block
+      #
+      # @example
+      #   TenantContext.with_tenant('org-123') do
+      #     user = User.create!(email: 'test@example.com')
+      #     # user.organization_id will be 'org-123'
+      #   end
+      def self.with_tenant(tenant_id)
+        previous_tenant = current
+        self.current = tenant_id
+        yield
+      ensure
+        self.current = previous_tenant
+      end
+
+      # Clear the current tenant
+      def self.clear!
+        Thread.current[:smart_domain_tenant_id] = nil
+      end
+
+      # Check if a tenant is set
+      #
+      # @return [Boolean]
+      def self.tenant_set?
+        current.present?
+      end
+    end
+
+    # ActiveRecord concern for automatic tenant assignment
+    #
+    # @example Include in a model
+    #   class User < ApplicationRecord
+    #     include SmartDomain::Integration::TenantScoped
+    #
+    #     # organization_id will be automatically set from TenantContext.current
+    #   end
+    module TenantScoped
+      extend ActiveSupport::Concern
+
+      included do
+        # Set tenant on create if not already set
+        before_validation :set_tenant_from_context, on: :create
+
+        # Validate tenant is present
+        validates SmartDomain.configuration.tenant_key, presence: true
+
+        # Default scope to current tenant (optional - can be disabled)
+        # default_scope -> { where(organization_id: TenantContext.current) if TenantContext.tenant_set? }
+      end
+
+      private
+
+      # Set tenant from thread-local context
+      def set_tenant_from_context
+        tenant_key = SmartDomain.configuration.tenant_key
+        return if public_send(tenant_key).present?
+        return unless TenantContext.tenant_set?
+
+        public_send("#{tenant_key}=", TenantContext.current)
+      end
+    end
+  end
+end

data/lib/smart_domain/railtie.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  # Rails integration via Railtie
+  #
+  # This Railtie automatically integrates SmartDomain with Rails:
+  # - Adds lib/generators to generator paths
+  # - Auto-loads domain setup files on boot
+  # - Provides rake tasks
+  class Railtie < Rails::Railtie
+    railtie_name :smart_domain
+
+    # Add generators to load path
+    generators do
+      require_relative "generators/install_generator"
+      require_relative "generators/domain_generator"
+    end
+
+    # Configuration hook
+    config.smart_domain = SmartDomain.configuration
+
+    # Initialize SmartDomain after Rails is loaded
+    config.after_initialize do
+      # Auto-load domain setup files from app/domains/**/setup.rb
+      load_domain_setups if defined?(Rails.root)
+    end
+
+    # Rake tasks
+    rake_tasks do
+      load "smart_domain/tasks/domains.rake"
+    end
+
+    private
+
+    # Load all domain setup files
+    def self.load_domain_setups
+      setup_files = Dir[Rails.root.join("app/domains/**/setup.rb")]
+
+      setup_files.each do |setup_file|
+        begin
+          require setup_file
+
+          # Extract domain module name from path
+          # e.g., app/domains/user_management/setup.rb -> UserManagement
+          domain_path = setup_file.gsub(Rails.root.join("app/domains/").to_s, "")
+          domain_name = domain_path.split("/").first.camelize
+
+          # Call setup! method if defined
+          domain_module = domain_name.constantize rescue nil
+          if domain_module && domain_module.respond_to?(:setup!)
+            domain_module.setup!
+            Rails.logger.info "[SmartDomain] Loaded domain: #{domain_name}"
+          end
+        rescue StandardError => e
+          Rails.logger.error "[SmartDomain] Failed to load domain setup: #{setup_file}"
+          Rails.logger.error e.message
+          Rails.logger.error e.backtrace.join("\n")
+        end
+      end
+    end
+  end
+end