smart_domain 0.1.0

data/lib/smart_domain/event/base.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support/core_ext/object/blank"
+require "securerandom"
+require "logger"
+
+module SmartDomain
+  module Event
+    # Base class for all domain events in the system.
+    #
+    # Domain events represent significant business occurrences that other
+    # parts of the system need to know about, such as user registrations,
+    # order placements, or inventory changes.
+    #
+    # Events are immutable once created - all attributes are frozen.
+    #
+    # @example Define a custom event
+    #   class UserCreatedEvent < SmartDomain::Event::Base
+    #     attribute :user_id, :string
+    #     attribute :email, :string
+    #
+    #     validates :user_id, :email, presence: true
+    #   end
+    #
+    # @example Create and publish an event
+    #   event = UserCreatedEvent.new(
+    #     event_type: 'user.created',
+    #     aggregate_id: user.id,
+    #     aggregate_type: 'User',
+    #     organization_id: org.id,
+    #     user_id: user.id,
+    #     email: user.email
+    #   )
+    #
+    #   SmartDomain::Event.bus.publish(event)
+    class Base
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+      include ActiveModel::Validations
+
+      # Core event fields
+      attribute :event_id, :string, default: -> { SecureRandom.uuid }
+      attribute :event_type, :string
+      attribute :aggregate_id, :string
+      attribute :aggregate_type, :string
+      attribute :organization_id, :string
+      attribute :occurred_at, :datetime, default: -> { Time.current }
+      attribute :version, :integer, default: 1
+      attribute :correlation_id, :string
+      attribute :causation_id, :string
+      attribute :metadata, default: -> { {} }
+
+      # Validate required fields
+      validates :event_type, :aggregate_id, :aggregate_type, :organization_id, presence: true
+
+      # Initialize event and freeze it (immutability)
+      def initialize(attributes = {})
+        super
+        freeze_event
+        validate!
+      end
+
+      # Convert event to hash
+      # @return [Hash] Event attributes as hash
+      def to_h
+        attributes.deep_symbolize_keys
+      end
+
+      # String representation
+      # @return [String] Event representation
+      def to_s
+        "<#{self.class.name}(id=#{event_id}, type=#{event_type})>"
+      end
+
+      alias inspect to_s
+
+      private
+
+      # Freeze the event to make it immutable
+      def freeze_event
+        @attributes.freeze
+        freeze
+      end
+    end
+
+    # Event bus for publishing and subscribing to domain events.
+    #
+    # The event bus follows the publish-subscribe pattern, allowing
+    # decoupled communication between different parts of the application.
+    #
+    # In production, this can be replaced with more robust message brokers
+    # like Redis, RabbitMQ, or AWS EventBridge via adapters.
+    #
+    # @example Subscribe to events
+    #   bus = SmartDomain::Event::Bus.new
+    #   handler = UserEmailHandler.new
+    #   bus.subscribe('user.created', handler)
+    #
+    # @example Publish an event
+    #   event = UserCreatedEvent.new(...)
+    #   bus.publish(event)
+    class Bus
+      attr_reader :adapter, :logger
+
+      # Initialize event bus with optional adapter
+      # @param adapter [Object, Symbol] Event bus adapter or adapter name (default: Memory adapter)
+      def initialize(adapter: nil)
+        @adapter = resolve_adapter(adapter)
+        @logger = ActiveSupport::TaggedLogging.new(Logger.new($stdout))
+      end
+
+      # Subscribe a handler to a specific event type
+      # @param event_type [String] Event type to subscribe to (e.g., 'user.created')
+      # @param handler [Object] Handler object that responds to #handle(event)
+      def subscribe(event_type, handler)
+        @adapter.subscribe(event_type, handler)
+        @logger.info "[SmartDomain] Event handler subscribed: #{handler.class.name} -> #{event_type}"
+      end
+
+      # Publish an event to all registered handlers
+      # @param event [SmartDomain::Event::Base] Event to publish
+      # @raise [ArgumentError] If event is invalid
+      def publish(event)
+        validate_event!(event)
+
+        @logger.info "[SmartDomain] Publishing event: #{event.event_type} (#{event.event_id})"
+        @logger.debug "[SmartDomain] Event details: #{event.to_h}"
+
+        @adapter.publish(event)
+      end
+
+      private
+
+      # Resolve adapter from symbol or object
+      # @param adapter [Object, Symbol, nil] Adapter instance, symbol, or nil
+      # @return [Object] Adapter instance
+      def resolve_adapter(adapter)
+        return Adapters::Memory.new if adapter.nil?
+        return adapter unless adapter.is_a?(Symbol)
+
+        case adapter
+        when :memory
+          Adapters::Memory.new
+        else
+          raise ArgumentError, "Unknown adapter: #{adapter}. Available adapters: :memory"
+        end
+      end
+
+      # Validate event before publishing
+      # @param event [Object] Event to validate
+      # @raise [ArgumentError] If event is not valid
+      def validate_event!(event)
+        unless event.is_a?(Base)
+          raise ArgumentError, "Event must be a SmartDomain::Event::Base, got #{event.class.name}"
+        end
+
+        return if event.valid?
+
+        raise ArgumentError, "Event validation failed: #{event.errors.full_messages.join(', ')}"
+      end
+    end
+
+    # Global event bus singleton
+    # @return [SmartDomain::Event::Bus] Global event bus instance
+    def self.bus
+      @bus ||= Bus.new(adapter: SmartDomain.configuration&.event_bus_adapter)
+    end
+
+    # Reset the global event bus (useful for testing)
+    # @api private
+    def self.reset_bus!
+      @bus = nil
+    end
+  end
+end

data/lib/smart_domain/event/handler.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Event
+    # Base class for event handlers.
+    #
+    # Event handlers process domain events and trigger side effects like
+    # sending emails, updating read models, logging, or triggering workflows.
+    #
+    # Handlers must implement the #handle method.
+    #
+    # @example Define a custom handler
+    #   class UserEmailHandler < SmartDomain::Event::Handler
+    #     def handle(event)
+    #       case event.event_type
+    #       when 'user.created'
+    #         UserMailer.welcome_email(event.user_id).deliver_later
+    #       when 'user.activated'
+    #         UserMailer.account_activated(event.user_id).deliver_later
+    #       end
+    #     end
+    #
+    #     def can_handle?(event_type)
+    #       ['user.created', 'user.activated'].include?(event_type)
+    #     end
+    #   end
+    #
+    # @example Subscribe the handler
+    #   handler = UserEmailHandler.new
+    #   SmartDomain::Event.bus.subscribe('user.created', handler)
+    #   SmartDomain::Event.bus.subscribe('user.activated', handler)
+    class Handler
+      # Handle a domain event
+      #
+      # Subclasses must implement this method to process events.
+      #
+      # @param event [SmartDomain::Event::Base] Event to handle
+      # @raise [NotImplementedError] If not implemented by subclass
+      def handle(event)
+        raise NotImplementedError, "#{self.class.name} must implement #handle(event)"
+      end
+
+      # Check if this handler can handle a specific event type
+      #
+      # Subclasses should implement this for filtering events.
+      # The default implementation returns true for all events.
+      #
+      # @param event_type [String] Event type to check
+      # @return [Boolean] True if handler can handle this event type
+      def can_handle?(event_type)
+        raise NotImplementedError, "#{self.class.name} must implement #can_handle?(event_type)"
+      end
+
+      # Handle event asynchronously using ActiveJob
+      #
+      # This method queues the event handling in a background job.
+      # Requires ActiveJob to be configured in the Rails application.
+      #
+      # @param event [SmartDomain::Event::Base] Event to handle
+      # @raise [RuntimeError] If ActiveJob is not loaded
+      def handle_async(event)
+        unless defined?(ActiveJob)
+          raise "ActiveJob is required for async event handling. Please require 'active_job' in your application."
+        end
+
+        event.validate!
+        HandlerJob.perform_later(self.class.name, event.to_h)
+      end
+    end
+
+    # ActiveJob for asynchronous event handling
+    #
+    # This job handles events in the background, allowing the main
+    # request thread to continue without waiting for handlers to complete.
+    #
+    # @api private
+    if defined?(ActiveJob)
+      class HandlerJob < ActiveJob::Base
+        queue_as :default
+
+        # Perform asynchronous event handling
+        # @param handler_class_name [String] Handler class name
+        # @param event_data [Hash] Event data
+        def perform(handler_class_name, event_data)
+          handler = handler_class_name.constantize.new
+          event_class = event_data[:event_type].camelize.constantize
+          event = event_class.new(event_data)
+
+          handler.handle(event)
+        rescue StandardError => e
+          Rails.logger.error "[SmartDomain] Async handler failed: #{e.message}"
+          Rails.logger.error e.backtrace.join("\n")
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/smart_domain/event/mixins.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module SmartDomain
+  module Event
+    # Reusable mixins for domain events to reduce boilerplate.
+    #
+    # These mixins provide common event fields following the pattern:
+    # - WHO performed the action (ActorMixin)
+    # - WHEN it occurred (AuditMixin)
+    # - WHAT changed (ChangeTrackingMixin)
+    # - WHERE from (SecurityContextMixin)
+    # - WHY (ReasonMixin)
+    #
+    # @example Using mixins in an event
+    #   class UserUpdatedEvent < SmartDomain::Event::Base
+    #     include SmartDomain::Event::ActorMixin
+    #     include SmartDomain::Event::ChangeTrackingMixin
+    #
+    #     attribute :user_id, :string
+    #   end
+
+    # Mixin for tracking WHO performed the action
+    #
+    # Adds actor_id and actor_email fields to track which user
+    # triggered the event.
+    #
+    # @example
+    #   class UserCreatedEvent < SmartDomain::Event::Base
+    #     include SmartDomain::Event::ActorMixin
+    #   end
+    #
+    #   event = UserCreatedEvent.new(
+    #     ...,
+    #     actor_id: current_user.id,
+    #     actor_email: current_user.email
+    #   )
+    module ActorMixin
+      extend ActiveSupport::Concern
+
+      included do
+        attribute :actor_id, :string
+        attribute :actor_email, :string
+
+        validates :actor_id, presence: true
+      end
+    end
+
+    # Mixin for tracking WHEN the action occurred
+    #
+    # Adds occurred_at timestamp field. This is usually redundant with
+    # the base event class but can be included for explicit tracking.
+    #
+    # @example
+    #   class PaymentProcessedEvent < SmartDomain::Event::Base
+    #     include SmartDomain::Event::AuditMixin
+    #   end
+    module AuditMixin
+      extend ActiveSupport::Concern
+
+      included do
+        attribute :occurred_at, :datetime, default: -> { Time.current }
+      end
+    end
+
+    # Mixin for tracking WHAT changed in an update event
+    #
+    # Adds fields for tracking field-level changes:
+    # - changed_fields: Array of field names that changed
+    # - old_values: Hash of field => old value
+    # - new_values: Hash of field => new value
+    #
+    # @example
+    #   class UserUpdatedEvent < SmartDomain::Event::Base
+    #     include SmartDomain::Event::ChangeTrackingMixin
+    #   end
+    #
+    #   event = UserUpdatedEvent.new(
+    #     ...,
+    #     changed_fields: ['email', 'name'],
+    #     old_values: { email: 'old@example.com', name: 'Old Name' },
+    #     new_values: { email: 'new@example.com', name: 'New Name' }
+    #   )
+    module ChangeTrackingMixin
+      extend ActiveSupport::Concern
+
+      included do
+        attribute :changed_fields, default: -> { [] }
+        attribute :old_values, default: -> { {} }
+        attribute :new_values, default: -> { {} }
+      end
+
+      # Helper to extract changes from an ActiveRecord model
+      # @param record [ActiveRecord::Base] Record with changes
+      # @return [Hash] Hash with changed_fields, old_values, new_values
+      def self.changes_from(record)
+        return { changed_fields: [], old_values: {}, new_values: {} } unless record.respond_to?(:saved_changes)
+
+        changes = record.saved_changes
+        {
+          changed_fields: changes.keys,
+          old_values: changes.transform_values(&:first),
+          new_values: changes.transform_values(&:last)
+        }
+      end
+    end
+
+    # Mixin for tracking WHERE the action came from
+    #
+    # Adds security context fields:
+    # - ip_address: IP address of the request
+    # - user_agent: User agent string from the request
+    #
+    # @example
+    #   class UserLoggedInEvent < SmartDomain::Event::Base
+    #     include SmartDomain::Event::SecurityContextMixin
+    #   end
+    #
+    #   event = UserLoggedInEvent.new(
+    #     ...,
+    #     ip_address: request.remote_ip,
+    #     user_agent: request.user_agent
+    #   )
+    module SecurityContextMixin
+      extend ActiveSupport::Concern
+
+      included do
+        attribute :ip_address, :string
+        attribute :user_agent, :string
+      end
+    end
+
+    # Mixin for tracking WHY an action was performed
+    #
+    # Adds a reason field for documenting why an administrative
+    # action was taken.
+    #
+    # @example
+    #   class UserSuspendedEvent < SmartDomain::Event::Base
+    #     include SmartDomain::Event::ReasonMixin
+    #   end
+    #
+    #   event = UserSuspendedEvent.new(
+    #     ...,
+    #     reason: 'Violation of terms of service - spam activity detected'
+    #   )
+    module ReasonMixin
+      extend ActiveSupport::Concern
+
+      included do
+        attribute :reason, :string
+      end
+    end
+  end
+end

data/lib/smart_domain/event/registration.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "../handlers/audit_handler"
+require_relative "../handlers/metrics_handler"
+
+module SmartDomain
+  module Event
+    # Event registration helpers for standardized handler setup.
+    #
+    # This module provides convenience methods to register common event handlers
+    # (audit, metrics) for domains, reducing boilerplate by approximately 70%.
+    #
+    # Instead of manually subscribing audit and metrics handlers to each event:
+    #
+    #   audit = AuditHandler.new('user')
+    #   metrics = MetricsHandler.new('user')
+    #   bus.subscribe('user.created', audit)
+    #   bus.subscribe('user.created', metrics)
+    #   bus.subscribe('user.updated', audit)
+    #   bus.subscribe('user.updated', metrics)
+    #   # ... repeat for all events ...
+    #
+    # Use this one-liner:
+    #
+    #   SmartDomain::Event::Registration.register_standard_handlers(
+    #     domain: 'user',
+    #     events: ['created', 'updated', 'deleted'],
+    #     include_audit: true,
+    #     include_metrics: true
+    #   )
+    #
+    # Custom handlers (email, security, etc.) should still be registered explicitly.
+    module Registration
+      # Register standard audit and metrics handlers for a domain's events.
+      #
+      # This helper reduces boilerplate by automatically registering generic
+      # audit and metrics handlers for all events in a domain. Custom handlers
+      # (email, security, etc.) should still be registered explicitly.
+      #
+      # @param domain [String] Domain name (e.g., 'user', 'order', 'product')
+      # @param events [Array<String>] List of event actions (e.g., ['created', 'updated', 'deleted'])
+      # @param include_audit [Boolean] Whether to register audit handler (default: true)
+      # @param include_metrics [Boolean] Whether to register metrics handler (default: true)
+      # @return [Hash] Dictionary mapping handler type to list of registered event types
+      #
+      # @example Domain setup file
+      #   # app/domains/user_management/setup.rb
+      #   module UserManagement
+      #     def self.setup!
+      #       # Register standard handlers
+      #       SmartDomain::Event::Registration.register_standard_handlers(
+      #         domain: 'user',
+      #         events: %w[created updated deleted activated suspended],
+      #         include_audit: true,
+      #         include_metrics: true
+      #       )
+      #
+      #       # Custom handlers still explicit
+      #       email_handler = UserEmailHandler.new
+      #       SmartDomain::Event.bus.subscribe('user.created', email_handler)
+      #       SmartDomain::Event.bus.subscribe('user.activated', email_handler)
+      #     end
+      #   end
+      def self.register_standard_handlers(domain:, events:, include_audit: true, include_metrics: true)
+        registered = { audit: [], metrics: [] }
+        logger = SmartDomain.configuration.logger
+
+        if include_audit
+          audit_handler = SmartDomain::Handlers::AuditHandler.new(domain)
+          events.each do |action|
+            event_type = "#{domain}.#{action}"
+            SmartDomain::Event.bus.subscribe(event_type, audit_handler)
+            registered[:audit] << event_type
+          end
+        end
+
+        if include_metrics
+          metrics_handler = SmartDomain::Handlers::MetricsHandler.new(domain)
+          events.each do |action|
+            event_type = "#{domain}.#{action}"
+            SmartDomain::Event.bus.subscribe(event_type, metrics_handler)
+            registered[:metrics] << event_type
+          end
+        end
+
+        # Log what was registered
+        if include_audit || include_metrics
+          handlers_registered = []
+          handlers_registered << "audit" if include_audit
+          handlers_registered << "metrics" if include_metrics
+
+          logger.info "[SmartDomain::Registration] Standard handlers registered for #{domain} domain: " \
+                      "#{handlers_registered.join(', ')} (#{events.size} events)"
+          logger.debug "[SmartDomain::Registration] Event types: #{events.map { |a| "#{domain}.#{a}" }.join(', ')}"
+        end
+
+        registered
+      end
+
+      # Register custom event handlers for a domain.
+      #
+      # This is a convenience method for registering multiple custom handlers
+      # to multiple events. Use this when you have custom handlers that need to
+      # listen to multiple events.
+      #
+      # @param domain [String] Domain name (for logging purposes)
+      # @param handlers [Hash] Hash mapping handler instances to list of event actions
+      #
+      # @example
+      #   # app/domains/user_management/setup.rb
+      #   email_handler = UserEmailHandler.new
+      #   security_handler = UserSecurityHandler.new
+      #
+      #   SmartDomain::Event::Registration.register_domain_handlers(
+      #     domain: 'user',
+      #     handlers: {
+      #       email_handler => ['created', 'activated', 'suspended'],
+      #       security_handler => ['suspended', 'deleted']
+      #     }
+      #   )
+      def self.register_domain_handlers(domain:, handlers:)
+        logger = SmartDomain.configuration.logger
+
+        handlers.each do |handler, event_actions|
+          event_actions.each do |action|
+            event_type = "#{domain}.#{action}"
+            SmartDomain::Event.bus.subscribe(event_type, handler)
+          end
+        end
+
+        logger.info "[SmartDomain::Registration] Custom handlers registered for #{domain} domain " \
+                    "(#{handlers.size} handler(s))"
+      end
+    end
+  end
+end

data/lib/smart_domain/generators/domain_generator.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Load the domain generator
+require_relative "../../generators/smart_domain/domain/domain_generator"

data/lib/smart_domain/generators/install_generator.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Load the install generator
+require_relative "../../generators/smart_domain/install/install_generator"