smart_domain 0.1.0

data/lib/generators/active_domain/domain/templates/service.rb.tt

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module <%= domain_module_name %>
+  # Service for <%= class_name %> business logic
+  #
+  # This service encapsulates all business operations for <%= plural_name %>.
+  # Controllers should delegate to this service rather than directly
+  # manipulating <%= class_name %> models.
+  class <%= class_name %>Service < ApplicationService
+    # Create a new <%= file_name %>
+    #
+    # @param attributes [Hash] <%= class_name %> attributes
+    # @return [<%= class_name %>] Created <%= file_name %>
+    # @raise [ActiveDomain::Domain::AlreadyExistsError] If <%= file_name %> already exists
+    # @raise [ActiveDomain::Domain::ValidationError] If validation fails
+    def create_<%= file_name %>(attributes)
+      # Example business rule validation
+      # if <%= class_name %>.exists?(email: attributes[:email])
+      #   raise ActiveDomain::Domain::AlreadyExistsError.new('<%= class_name %>', 'email', attributes[:email])
+      # end
+
+      <%= class_name %>.transaction do
+        <%= file_name %> = <%= class_name %>.create!(attributes)
+
+        # Event is published via ActiveRecord integration
+        # Or manually:
+        # event = build_event(<%= class_name %>CreatedEvent,
+        #   event_type: '<%= file_name %>.created',
+        #   aggregate_id: <%= file_name %>.id,
+        #   aggregate_type: '<%= class_name %>',
+        #   <%= file_name %>_id: <%= file_name %>.id
+        # )
+        # publish_after_commit(event)
+
+        log(:info, "<%= class_name %> created", <%= file_name %>_id: <%= file_name %>.id)
+        <%= file_name %>
+      end
+    end
+
+    # Update an existing <%= file_name %>
+    #
+    # @param <%= file_name %>_id [Integer, String] <%= class_name %> ID
+    # @param attributes [Hash] Attributes to update
+    # @return [<%= class_name %>] Updated <%= file_name %>
+    # @raise [ActiveRecord::RecordNotFound] If <%= file_name %> not found
+    # @raise [ActiveDomain::Domain::UnauthorizedError] If not authorized
+    def update_<%= file_name %>(<%= file_name %>_id, attributes)
+      <%= file_name %> = <%= class_name %>.find(<%= file_name %>_id)
+
+      # Authorization check
+      policy = <%= class_name %>Policy.new(current_user, <%= file_name %>)
+      authorize!(policy, :update?)
+
+      <%= class_name %>.transaction do
+        <%= file_name %>.update!(attributes)
+
+        # Event published via ActiveRecord integration
+        log(:info, "<%= class_name %> updated", <%= file_name %>_id: <%= file_name %>.id, changes: <%= file_name %>.saved_changes.keys)
+        <%= file_name %>
+      end
+    end
+
+    # Delete a <%= file_name %>
+    #
+    # @param <%= file_name %>_id [Integer, String] <%= class_name %> ID
+    # @return [Boolean] True if deleted
+    # @raise [ActiveRecord::RecordNotFound] If <%= file_name %> not found
+    # @raise [ActiveDomain::Domain::UnauthorizedError] If not authorized
+    def delete_<%= file_name %>(<%= file_name %>_id)
+      <%= file_name %> = <%= class_name %>.find(<%= file_name %>_id)
+
+      # Authorization check
+      policy = <%= class_name %>Policy.new(current_user, <%= file_name %>)
+      authorize!(policy, :destroy?)
+
+      <%= class_name %>.transaction do
+        <%= file_name %>.destroy!
+
+        # Event published via ActiveRecord integration
+        log(:info, "<%= class_name %> deleted", <%= file_name %>_id: <%= file_name %>_id)
+        true
+      end
+    end
+
+    # List <%= plural_name %> with policy scope
+    #
+    # @param scope [ActiveRecord::Relation] Optional base scope
+    # @return [ActiveRecord::Relation] Scoped <%= plural_name %>
+    def list_<%= plural_name %>(scope = <%= class_name %>.all)
+      policy_scope(scope, <%= class_name %>Policy)
+    end
+  end
+end

data/lib/generators/active_domain/domain/templates/setup.rb.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module <%= domain_module_name %>
+  # Setup event handlers for <%= file_name %> domain
+  #
+  # This file is automatically loaded by ActiveDomain::Railtie
+  # when the Rails application starts.
+  def self.setup!
+    # Register standard handlers (audit and metrics)
+    # This one line replaces ~50 lines of boilerplate!
+    ActiveDomain::Event::Registration.register_standard_handlers(
+      domain: '<%= file_name %>',
+      events: %w[created updated deleted],
+      include_audit: true,
+      include_metrics: true
+    )
+
+    # Register custom handlers here
+    # Example:
+    #
+    # email_handler = <%= class_name %>EmailHandler.new
+    # ActiveDomain::Event.bus.subscribe('<%= file_name %>.created', email_handler)
+    # ActiveDomain::Event.bus.subscribe('<%= file_name %>.updated', email_handler)
+
+    Rails.logger.info "[<%= domain_module_name %>] Domain setup complete"
+  end
+end

data/lib/generators/active_domain/install/install_generator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module SmartDomain
+  module Generators
+    # Generator for installing SmartDomain in a Rails application
+    #
+    # Usage:
+    #   rails generate smart_domain:install
+    #
+    # Creates:
+    #   - config/initializers/smart_domain.rb
+    #   - app/domains/ directory
+    #   - app/events/ directory
+    #   - app/handlers/ directory
+    #   - app/policies/ directory
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install SmartDomain into your Rails application"
+
+      # Create initializer
+      def create_initializer
+        template "initializer.rb", "config/initializers/smart_domain.rb"
+      end
+
+      # Create directory structure
+      def create_directory_structure
+        create_file "app/domains/.keep"
+        create_file "app/events/.keep"
+        create_file "app/handlers/.keep"
+        create_file "app/policies/.keep"
+        create_file "app/services/.keep"
+      end
+
+      # Create base event class
+      def create_application_event
+        template "application_event.rb", "app/events/application_event.rb"
+      end
+
+      # Create base policy class
+      def create_application_policy
+        template "application_policy.rb", "app/policies/application_policy.rb"
+      end
+
+      # Create base service class
+      def create_application_service
+        template "application_service.rb", "app/services/application_service.rb"
+      end
+
+      # Show post-install message
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/active_domain/install/templates/README

@@ -0,0 +1,28 @@
+===============================================================================
+
+ActiveDomain has been installed!
+
+Created files:
+  config/initializers/active_domain.rb  - Configuration
+  app/events/application_event.rb       - Base event class
+  app/policies/application_policy.rb    - Base policy class
+  app/services/application_service.rb   - Base service class
+
+Created directories:
+  app/domains/   - Domain modules go here
+  app/events/    - Domain events go here
+  app/handlers/  - Custom event handlers go here
+  app/policies/  - Domain policies go here
+  app/services/  - Domain services go here
+
+Next steps:
+
+1. Review and configure config/initializers/active_domain.rb
+
+2. Generate your first domain:
+   rails generate active_domain:domain User
+
+3. Read the documentation:
+   https://github.com/rachidalmaach/active_domain
+
+===============================================================================

data/lib/generators/active_domain/install/templates/application_event.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Base class for all domain events in this application
+#
+# Inherit from this class to create domain-specific events
+#
+# Example:
+#   class UserCreatedEvent < ApplicationEvent
+#     attribute :user_id, :string
+#     attribute :email, :string
+#     validates :user_id, :email, presence: true
+#   end
+class ApplicationEvent < SmartDomain::Event::Base
+  # Add application-wide event fields here
+  # Example:
+  # attribute :tenant_id, :string
+  # validates :tenant_id, presence: true
+end

data/lib/generators/active_domain/install/templates/application_policy.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Base class for all domain policies in this application
+#
+# Inherit from this class to create domain-specific policies
+#
+# Example:
+#   class UserPolicy < ApplicationPolicy
+#     def update?
+#       user.admin? || owner?
+#     end
+#
+#     def destroy?
+#       user.admin?
+#     end
+#   end
+class ApplicationPolicy < SmartDomain::Domain::Policy
+  # Add application-wide policy methods here
+  # Example:
+  # def manager?
+  #   user.present? && user.role == 'manager'
+  # end
+end

data/lib/generators/active_domain/install/templates/application_service.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Base class for all domain services in this application
+#
+# Inherit from this class to create domain-specific services
+#
+# Example:
+#   class UserService < ApplicationService
+#     def create_user(attributes)
+#       User.transaction do
+#         user = User.create!(attributes)
+#         event = build_event(UserCreatedEvent, ...)
+#         publish_after_commit(event)
+#         user
+#       end
+#     end
+#   end
+class ApplicationService < SmartDomain::Domain::Service
+  # Add application-wide service methods here
+  # Example:
+  # def current_organization
+  #   @current_organization ||= Organization.find(current_organization_id)
+  # end
+end

data/lib/generators/active_domain/install/templates/initializer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# SmartDomain configuration
+SmartDomain.configure do |config|
+  # Event bus adapter (:memory, :redis, :active_job)
+  # :memory is synchronous and suitable for development/testing
+  # :redis and :active_job are asynchronous and suitable for production
+  config.event_bus_adapter = :memory
+
+  # Enable automatic writes to audit_events table
+  # Set to true if you have an AuditEvent model for compliance
+  config.audit_table_enabled = false
+
+  # Enable multi-tenancy support
+  # Set to true if your application is multi-tenant
+  config.multi_tenancy_enabled = false
+
+  # Key used for tenant identification (e.g., :organization_id, :account_id)
+  config.tenant_key = :organization_id
+
+  # Use ActiveJob for asynchronous event handling
+  # Requires config.event_bus_adapter to support async (not :memory)
+  config.async_handlers = false
+
+  # Logger instance
+  config.logger = Rails.logger
+end
+
+# Example: Register standard handlers for a domain
+# Uncomment and modify for your domains:
+#
+# SmartDomain::Event::Registration.register_standard_handlers(
+#   domain: 'user',
+#   events: %w[created updated deleted],
+#   include_audit: true,
+#   include_metrics: true
+# )

data/lib/smart_domain/configuration.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module SmartDomain
+  # Configuration for SmartDomain gem.
+  #
+  # Configure the gem in an initializer:
+  #
+  # @example config/initializers/smart_domain.rb
+  #   SmartDomain.configure do |config|
+  #     config.event_bus_adapter = :memory
+  #     config.audit_table_enabled = true
+  #     config.multi_tenancy_enabled = true
+  #     config.tenant_key = :organization_id
+  #     config.async_handlers = false
+  #     config.logger = Rails.logger
+  #   end
+  class Configuration
+    # Event bus adapter to use (:memory, :redis, :active_job)
+    # @return [Symbol, Object] Adapter symbol or adapter instance
+    attr_accessor :event_bus_adapter
+
+    # Enable automatic writes to audit_events table
+    # @return [Boolean]
+    attr_accessor :audit_table_enabled
+
+    # Enable multi-tenancy support
+    # @return [Boolean]
+    attr_accessor :multi_tenancy_enabled
+
+    # Key used for tenant identification (e.g., :organization_id, :account_id)
+    # @return [Symbol]
+    attr_accessor :tenant_key
+
+    # Use ActiveJob for asynchronous event handling
+    # @return [Boolean]
+    attr_accessor :async_handlers
+
+    # Logger instance for SmartDomain
+    # @return [Logger]
+    attr_accessor :logger
+
+    # Initialize configuration with defaults
+    def initialize
+      @event_bus_adapter = nil # Will use Memory adapter
+      @audit_table_enabled = false
+      @multi_tenancy_enabled = false
+      @tenant_key = :organization_id
+      @async_handlers = false
+      @logger = Logger.new($stdout)
+    end
+
+    # Check if audit table writes are enabled
+    # @return [Boolean]
+    def audit_table_enabled?
+      @audit_table_enabled == true
+    end
+
+    # Check if multi-tenancy is enabled
+    # @return [Boolean]
+    def multi_tenancy_enabled?
+      @multi_tenancy_enabled == true
+    end
+
+    # Check if async handlers are enabled
+    # @return [Boolean]
+    def async_handlers?
+      @async_handlers == true
+    end
+  end
+
+  # Get or create the configuration instance
+  # @return [SmartDomain::Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Configure SmartDomain
+  #
+  # @example
+  #   SmartDomain.configure do |config|
+  #     config.event_bus_adapter = :memory
+  #     config.audit_table_enabled = true
+  #   end
+  #
+  # @yield [Configuration] The configuration object
+  def self.configure
+    yield(configuration)
+  end
+
+  # Reset configuration to defaults (useful for testing)
+  # @api private
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

data/lib/smart_domain/domain/exceptions.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Domain
+    # Base exception for all domain errors
+    #
+    # Domain exceptions represent business rule violations and should be
+    # handled differently from technical errors (like database errors).
+    #
+    # @example Define domain-specific exceptions
+    #   class UserNotFoundError < SmartDomain::Domain::Error
+    #     def initialize(user_id)
+    #       super("User not found: #{user_id}")
+    #     end
+    #   end
+    #
+    #   class UserAlreadyExistsError < SmartDomain::Domain::Error
+    #     def initialize(email)
+    #       super("User with email #{email} already exists")
+    #     end
+    #   end
+    class Error < StandardError
+      attr_reader :code, :details
+
+      # Initialize domain error
+      #
+      # @param message [String] Error message
+      # @param code [Symbol, nil] Error code for programmatic handling
+      # @param details [Hash, nil] Additional error details
+      def initialize(message, code: nil, details: {})
+        super(message)
+        @code = code
+        @details = details
+      end
+
+      # Convert error to hash (useful for API responses)
+      #
+      # @return [Hash] Error representation
+      def to_h
+        {
+          error: self.class.name,
+          message: message,
+          code: code,
+          details: details
+        }.compact
+      end
+
+      alias to_hash to_h
+    end
+
+    # Error raised when an entity is not found
+    #
+    # @example
+    #   raise SmartDomain::Domain::NotFoundError.new('User', user_id)
+    class NotFoundError < Error
+      def initialize(entity_type, entity_id)
+        super(
+          "#{entity_type} not found: #{entity_id}",
+          code: :not_found,
+          details: { entity_type: entity_type, entity_id: entity_id }
+        )
+      end
+    end
+
+    # Error raised when an entity already exists
+    #
+    # @example
+    #   raise SmartDomain::Domain::AlreadyExistsError.new('User', 'email', email)
+    class AlreadyExistsError < Error
+      def initialize(entity_type, attribute, value)
+        super(
+          "#{entity_type} with #{attribute} '#{value}' already exists",
+          code: :already_exists,
+          details: { entity_type: entity_type, attribute: attribute, value: value }
+        )
+      end
+    end
+
+    # Error raised when a business rule is violated
+    #
+    # @example
+    #   raise SmartDomain::Domain::BusinessRuleError.new(
+    #     'Cannot delete user with active orders'
+    #   )
+    class BusinessRuleError < Error
+      def initialize(message, code: :business_rule_violation, details: {})
+        super(message, code: code, details: details)
+      end
+    end
+
+    # Error raised when an invalid state transition is attempted
+    #
+    # @example
+    #   raise SmartDomain::Domain::InvalidStateError.new(
+    #     'User',
+    #     from: 'suspended',
+    #     to: 'active',
+    #     reason: 'User must be pending to activate'
+    #   )
+    class InvalidStateError < Error
+      def initialize(entity_type, from:, to:, reason: nil)
+        message = "Invalid state transition for #{entity_type}: #{from} -> #{to}"
+        message += " (#{reason})" if reason
+
+        super(
+          message,
+          code: :invalid_state,
+          details: { entity_type: entity_type, from: from, to: to, reason: reason }
+        )
+      end
+    end
+
+    # Error raised when validation fails
+    #
+    # @example
+    #   raise SmartDomain::Domain::ValidationError.new(
+    #     'User validation failed',
+    #     errors: { email: ['is required'], name: ['is too short'] }
+    #   )
+    class ValidationError < Error
+      def initialize(message, errors: {})
+        super(
+          message,
+          code: :validation_failed,
+          details: { validation_errors: errors }
+        )
+      end
+    end
+
+    # Error raised when authorization fails
+    #
+    # @example
+    #   raise SmartDomain::Domain::UnauthorizedError.new(
+    #     'User does not have permission to delete this resource'
+    #   )
+    class UnauthorizedError < Error
+      def initialize(message = "Unauthorized", action: nil, resource: nil)
+        super(
+          message,
+          code: :unauthorized,
+          details: { action: action, resource: resource }.compact
+        )
+      end
+    end
+
+    # Error raised when a required dependency is not available
+    #
+    # @example
+    #   raise SmartDomain::Domain::DependencyError.new(
+    #     'Redis',
+    #     'Redis is required for caching'
+    #   )
+    class DependencyError < Error
+      def initialize(dependency_name, message = nil)
+        message ||= "Required dependency not available: #{dependency_name}"
+        super(
+          message,
+          code: :dependency_missing,
+          details: { dependency: dependency_name }
+        )
+      end
+    end
+  end
+end