smart_domain 0.1.0

data/examples/blog_app/README_EXAMPLE.md

@@ -0,0 +1,328 @@
+# SmartDomain Example: Blog Application
+
+This is a complete example Rails application demonstrating all the features of the **SmartDomain** gem.
+
+## What This Example Demonstrates
+
+This blog application showcases how SmartDomain brings Domain-Driven Design (DDD) and Event-Driven Architecture (EDA) patterns to Rails:
+
+1. **Domain Services** - Business logic encapsulated in service objects
+2. **Domain Events** - Immutable events with type safety and validation
+3. **Event Bus** - Publish-subscribe pattern for event distribution
+4. **Generic Handlers** - 70% boilerplate reduction with `register_standard_handlers`
+5. **Custom Event Handlers** - Domain-specific handlers for side effects
+6. **Event Mixins** - Reusable event attributes (Actor, ChangeTracking, etc.)
+7. **Domain Policies** - Pundit-style authorization
+8. **Multi-tenancy** - Organization-based data isolation
+9. **ActiveRecord Integration** - Transaction-safe event publishing
+
+## Application Structure
+
+This example uses a **domain-centric structure** where all domain-specific files (models, events, handlers, policies) are grouped within each domain directory. This follows Domain-Driven Design (DDD) best practices and the Aeyes architecture pattern.
+
+```
+app/
+├── domains/
+│   ├── user_management/           # User domain (bounded context)
+│   │   ├── models/
+│   │   │   └── user.rb            # User model with SmartDomain integration
+│   │   ├── events/
+│   │   │   ├── user_created_event.rb  # User created event
+│   │   │   ├── user_updated_event.rb  # User updated event
+│   │   │   └── user_deleted_event.rb  # User deleted event
+│   │   ├── handlers/
+│   │   │   └── user_welcome_handler.rb  # Custom: Send welcome emails
+│   │   ├── policies/
+│   │   │   └── user_policy.rb     # User authorization
+│   │   ├── user_service.rb        # Business logic for users
+│   │   └── setup.rb               # Event handler registration
+│   │
+│   └── post_management/           # Post domain (bounded context)
+│       ├── models/
+│       │   └── post.rb            # Post model with SmartDomain integration
+│       ├── events/
+│       │   ├── post_created_event.rb  # Post created event
+│       │   ├── post_updated_event.rb  # Post updated event
+│       │   └── post_deleted_event.rb  # Post deleted event
+│       ├── handlers/
+│       │   └── post_notification_handler.rb  # Custom: Notify on publish
+│       ├── policies/
+│       │   └── post_policy.rb     # Post authorization
+│       ├── post_service.rb        # Business logic for posts
+│       └── setup.rb               # Event handler registration
+│
+├── events/
+│   └── application_event.rb       # Base event class (shared)
+├── handlers/
+│   └── .keep
+├── policies/
+│   └── application_policy.rb      # Base policy class (shared)
+└── models/
+    ├── organization.rb            # Multi-tenant organization (shared)
+    └── application_record.rb      # Base model class (shared)
+```
+
+**Key Design Decisions:**
+
+1. **Domain-Centric Organization**: All domain-specific code lives within `app/domains/{domain}/` subdirectories
+2. **Shared Base Classes**: Base classes like `ApplicationEvent` and `ApplicationPolicy` remain at the top level since they're shared across domains
+3. **Bounded Contexts**: Each domain is a self-contained bounded context with its own models, events, handlers, and policies
+4. **Autoloading Configuration**: Rails is configured to autoload from domain subdirectories (see `config/application.rb`)
+
+## Setup Instructions
+
+### 1. Install Dependencies
+
+```bash
+cd examples/blog_app
+bundle install
+```
+
+### 2. Setup Database
+
+```bash
+rails db:create db:migrate
+```
+
+### 3. Run the Demo Script
+
+```bash
+rails runner lib/demo.rb
+```
+
+This will run a comprehensive demonstration showing:
+- Creating an organization (multi-tenancy)
+- Creating users via domain services
+- Publishing domain events
+- Generic and custom event handlers
+- Creating and publishing blog posts
+- Authorization with policies
+- Multi-tenant data isolation
+
+## Key Features Demonstrated
+
+### 1. Domain Services
+
+Services encapsulate business logic and publish domain events:
+
+```ruby
+service = UserManagement::UserService.new(
+  current_user: admin,
+  organization_id: org.id
+)
+
+user = service.create(User, {
+  email: "john@example.com",
+  name: "John Doe",
+  role: "admin"
+})
+# Automatically publishes UserCreatedEvent
+```
+
+### 2. Event Publishing with Mixins
+
+Events use mixins for common attributes:
+
+```ruby
+event = UserCreatedEvent.new(
+  event_type: "user.created",
+  aggregate_id: user.id,
+  aggregate_type: "User",
+  organization_id: org.id,
+  actor_id: current_user.id,           # From ActorMixin
+  actor_email: current_user.email,     # From ActorMixin
+  user_id: user.id,
+  email: user.email
+)
+```
+
+### 3. Generic Handlers (70% Boilerplate Reduction)
+
+One line registers audit and metrics handlers for all events:
+
+```ruby
+# In app/domains/user_management/setup.rb
+SmartDomain::Event::Registration.register_standard_handlers(
+  domain: 'user',
+  events: %w[created updated deleted],
+  include_audit: true,
+  include_metrics: true
+)
+# Replaces ~50 lines of manual subscription code!
+```
+
+### 4. Custom Event Handlers
+
+Add domain-specific side effects:
+
+```ruby
+class UserWelcomeHandler < SmartDomain::Event::Handler
+  def can_handle?(event_type)
+    event_type == "user.created"
+  end
+
+  def handle(event)
+    UserMailer.welcome_email(event.user_id).deliver_later
+  end
+end
+
+# Register in setup.rb
+welcome_handler = UserWelcomeHandler.new
+SmartDomain::Event.bus.subscribe('user.created', welcome_handler)
+```
+
+### 5. Change Tracking
+
+Track what changed in update events:
+
+```ruby
+event = PostUpdatedEvent.new(
+  event_type: "post.updated",
+  aggregate_id: post.id,
+  aggregate_type: "Post",
+  organization_id: org.id,
+  changed_fields: ["published", "published_at"],
+  old_values: { "published" => false, "published_at" => nil },
+  new_values: { "published" => true, "published_at" => Time.current }
+)
+```
+
+### 6. Authorization with Policies
+
+Pundit-style policies for domain authorization:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  def update?
+    user_present? && (
+      user.role == "admin" ||
+      (user.role == "editor" && owner?)
+    )
+  end
+
+  def destroy?
+    user_present? && user.role == "admin"
+  end
+
+  private
+
+  def owner?
+    record.user_id == user.id
+  end
+end
+```
+
+### 7. Multi-tenancy
+
+Organization-based data isolation:
+
+```ruby
+# Set tenant context
+SmartDomain::Integration::TenantContext.with_tenant(org.id) do
+  # All queries are automatically scoped to this organization
+  users = User.all  # Only returns users from org
+  posts = Post.all  # Only returns posts from org
+end
+
+# Models use TenantScoped mixin
+class User < ApplicationRecord
+  include SmartDomain::Integration::TenantScoped
+  tenant_key :organization_id
+end
+```
+
+### 8. ActiveRecord Integration
+
+Transaction-safe event publishing:
+
+```ruby
+class Post < ApplicationRecord
+  include SmartDomain::Integration::ActiveRecord
+
+  after_commit :publish_created_event, on: :create
+
+  def publish_created_event
+    event = PostCreatedEvent.new(...)
+    add_domain_event(event)
+  end
+end
+# Events only publish after transaction commits!
+```
+
+## Event Flow Example
+
+When a user is created through the service:
+
+```
+User.create! → UserService.create
+    ↓
+UserCreatedEvent published
+    ↓
+    ├─→ AuditHandler          (logs to Rails.logger + audit table)
+    ├─→ MetricsHandler         (increments metrics)
+    └─→ UserWelcomeHandler     (sends welcome email)
+```
+
+All handlers run synchronously in the current thread with error isolation.
+
+## Running Tests
+
+The example app doesn't include tests, but demonstrates patterns you can test:
+
+```ruby
+# Test event publishing
+expect {
+  service.create(User, attributes)
+}.to publish_event(UserCreatedEvent)
+
+# Test handlers
+handler = UserWelcomeHandler.new
+event = UserCreatedEvent.new(...)
+expect { handler.handle(event) }.to send_email
+
+# Test policies
+policy = PostPolicy.new(user, post)
+expect(policy.update?).to be true
+```
+
+## Viewing Logs
+
+All events and handler executions are logged. Run the demo and watch the logs:
+
+```bash
+rails runner lib/demo.rb | grep -E '\[SmartDomain|User|Post'
+```
+
+You'll see:
+- Event publications
+- Handler subscriptions
+- Audit logs
+- Metrics increments
+- Custom handler executions
+
+## Next Steps
+
+1. **Explore the generated files**: Look at the domain services, events, and policies
+2. **Customize the business logic**: Add validation, workflows, or complex rules
+3. **Add more handlers**: Create handlers for emails, notifications, webhooks
+4. **Try multi-tenancy**: Create multiple organizations and see data isolation
+5. **Add authorization**: Use policies in controllers to enforce permissions
+6. **Extend events**: Add more mixins like SecurityContextMixin or ReasonMixin
+
+## Learn More
+
+- **Gem Documentation**: ../../README.md
+- **SmartDomain GitHub**: https://github.com/rachid/smart_domain
+- **Configuration**: config/initializers/smart_domain.rb
+
+## Key Takeaways
+
+1. **Services own business logic**, controllers delegate
+2. **Events are immutable** and published after transaction commits
+3. **Generic handlers** eliminate 70% of boilerplate code
+4. **Custom handlers** enable domain-specific side effects
+5. **Policies centralize** authorization logic
+6. **Multi-tenancy** is automatic with TenantContext
+7. **Everything is type-safe** and validated
+
+This architecture scales from small apps to large platforms while maintaining clean, maintainable code.

data/examples/blog_app/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/examples/blog_app/app/assets/stylesheets/application.css

@@ -0,0 +1,10 @@
+/*
+ * This is a manifest file that'll be compiled into application.css.
+ *
+ * With Propshaft, assets are served efficiently without preprocessing steps. You can still include
+ * application-wide styles in this file, but keep in mind that CSS precedence will follow the standard
+ * cascading order, meaning styles declared later in the document or manifest will override earlier ones,
+ * depending on specificity.
+ *
+ * Consider organizing styles into separate files for maintainability.
+ */

data/examples/blog_app/app/controllers/api/base_controller.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Api
+  # Base API controller with common functionality
+  class BaseController < ApplicationController
+    # Skip CSRF for API requests
+    skip_before_action :verify_authenticity_token
+
+    # Simple authentication simulation
+    # In a real app, this would use JWT, sessions, etc.
+    before_action :set_current_organization
+    before_action :set_current_user
+
+    rescue_from ActiveRecord::RecordNotFound, with: :not_found
+    rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
+    rescue_from SmartDomain::Domain::Exceptions::UnauthorizedError, with: :forbidden
+
+    private
+
+    def set_current_organization
+      # In real app: decode from JWT, session, subdomain, etc.
+      # For demo: use header or first organization
+      org_id = request.headers['X-Organization-Id']
+      @current_organization = if org_id
+        Organization.find(org_id)
+      else
+        Organization.first || Organization.create!(name: "Demo Organization")
+      end
+    end
+
+    def set_current_user
+      # In real app: decode from JWT token
+      # For demo: use header or create demo user
+      user_id = request.headers['X-User-Id']
+      @current_user = if user_id
+        User.find(user_id)
+      else
+        # Create a demo admin user if none exists
+        @current_organization.users.first || @current_organization.users.create!(
+          email: "admin@example.com",
+          name: "Demo Admin",
+          role: "admin"
+        )
+      end
+    end
+
+    attr_reader :current_user, :current_organization
+
+    def not_found(exception)
+      render json: { error: exception.message }, status: :not_found
+    end
+
+    def unprocessable_entity(exception)
+      render json: { error: exception.message, details: exception.record.errors }, status: :unprocessable_entity
+    end
+
+    def forbidden(exception)
+      render json: { error: exception.message }, status: :forbidden
+    end
+  end
+end

data/examples/blog_app/app/controllers/api/v1/posts_controller.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    # Posts API Controller
+    #
+    # Demonstrates:
+    # - Thin controller delegating to PostService (domain layer)
+    # - Policy authorization using PostPolicy
+    # - Custom actions (publish/unpublish) triggering events
+    # - Change tracking in update events
+    class PostsController < Api::BaseController
+      before_action :set_post, only: [:show, :update, :destroy, :publish, :unpublish]
+
+      # GET /api/v1/posts
+      def index
+        @posts = SmartDomain::Integration::TenantContext.with_tenant(current_organization.id) do
+          # Optional filter by published status
+          scope = Post.includes(:user)
+          scope = params[:published] == 'true' ? scope.published : scope if params[:published].present?
+          scope.all
+        end
+
+        render json: @posts, include: :user
+      end
+
+      # GET /api/v1/posts/:id
+      def show
+        authorize @post, :show?
+        render json: @post, include: :user
+      end
+
+      # POST /api/v1/posts
+      def create
+        service = PostManagement::PostService.new(
+          current_user: current_user,
+          organization_id: current_organization.id
+        )
+
+        # Service handles:
+        # 1. Validation
+        # 2. Creating the post
+        # 3. Publishing PostCreatedEvent
+        # 4. Triggering audit and metrics handlers
+        @post = service.create_post(post_params.merge(user_id: current_user.id))
+
+        render json: @post, status: :created
+      end
+
+      # PATCH/PUT /api/v1/posts/:id
+      def update
+        authorize @post, :update?
+
+        service = PostManagement::PostService.new(
+          current_user: current_user,
+          organization_id: current_organization.id
+        )
+
+        # Service publishes PostUpdatedEvent with change tracking
+        @post = service.update_post(@post, post_params)
+
+        render json: @post
+      end
+
+      # DELETE /api/v1/posts/:id
+      def destroy
+        authorize @post, :destroy?
+
+        service = PostManagement::PostService.new(
+          current_user: current_user,
+          organization_id: current_organization.id
+        )
+
+        # Service publishes PostDeletedEvent
+        service.delete_post(@post)
+
+        head :no_content
+      end
+
+      # POST /api/v1/posts/:id/publish
+      # Custom action demonstrating change tracking events
+      def publish
+        authorize @post, :update?
+
+        # Track old state for change tracking
+        old_published = @post.published
+        old_published_at = @post.published_at
+
+        @post.publish!
+
+        # Publish event with change tracking
+        event = PostUpdatedEvent.new(
+          event_type: "post.updated",
+          aggregate_id: @post.id.to_s,
+          aggregate_type: "Post",
+          organization_id: current_organization.id.to_s,
+          actor_id: current_user.id.to_s,
+          actor_email: current_user.email,
+          post_id: @post.id.to_s,
+          changed_fields: ["published", "published_at"],
+          old_values: { "published" => old_published, "published_at" => old_published_at },
+          new_values: { "published" => true, "published_at" => @post.published_at.iso8601 }
+        )
+
+        SmartDomain::Event.bus.publish(event)
+
+        render json: @post
+      end
+
+      # POST /api/v1/posts/:id/unpublish
+      def unpublish
+        authorize @post, :update?
+
+        old_published = @post.published
+        old_published_at = @post.published_at
+
+        @post.unpublish!
+
+        # Publish event with change tracking
+        event = PostUpdatedEvent.new(
+          event_type: "post.updated",
+          aggregate_id: @post.id.to_s,
+          aggregate_type: "Post",
+          organization_id: current_organization.id.to_s,
+          actor_id: current_user.id.to_s,
+          actor_email: current_user.email,
+          post_id: @post.id.to_s,
+          changed_fields: ["published", "published_at"],
+          old_values: { "published" => old_published, "published_at" => old_published_at&.iso8601 },
+          new_values: { "published" => false, "published_at" => nil }
+        )
+
+        SmartDomain::Event.bus.publish(event)
+
+        render json: @post
+      end
+
+      private
+
+      def set_post
+        @post = SmartDomain::Integration::TenantContext.with_tenant(current_organization.id) do
+          Post.find(params[:id])
+        end
+      end
+
+      def post_params
+        params.require(:post).permit(:title, :body, :published)
+      end
+
+      def authorize(post, action)
+        policy = PostPolicy.new(current_user, post)
+        unless policy.public_send(action)
+          raise SmartDomain::Domain::Exceptions::UnauthorizedError, "Not authorized to #{action} this post"
+        end
+      end
+    end
+  end
+end

data/examples/blog_app/app/controllers/api/v1/users_controller.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    # Users API Controller
+    #
+    # Demonstrates:
+    # - Thin controller delegating to UserService (domain layer)
+    # - Policy authorization using UserPolicy
+    # - Multi-tenancy with current_organization
+    # - Events automatically published via service layer
+    class UsersController < Api::BaseController
+      before_action :set_user, only: [:show, :update, :destroy]
+
+      # GET /api/v1/users
+      def index
+        # Automatically scoped to current_organization via TenantScoped
+        @users = SmartDomain::Integration::TenantContext.with_tenant(current_organization.id) do
+          User.all
+        end
+
+        render json: @users
+      end
+
+      # GET /api/v1/users/:id
+      def show
+        authorize @user, :show?
+        render json: @user
+      end
+
+      # POST /api/v1/users
+      def create
+        service = UserManagement::UserService.new(
+          current_user: current_user,
+          organization_id: current_organization.id
+        )
+
+        # Service handles:
+        # 1. Business logic validation
+        # 2. Creating the user
+        # 3. Publishing UserCreatedEvent
+        # 4. Triggering handlers (audit, metrics, welcome email)
+        @user = service.create_user(user_params)
+
+        render json: @user, status: :created
+      end
+
+      # PATCH/PUT /api/v1/users/:id
+      def update
+        authorize @user, :update?
+
+        service = UserManagement::UserService.new(
+          current_user: current_user,
+          organization_id: current_organization.id
+        )
+
+        # Service publishes UserUpdatedEvent with change tracking
+        @user = service.update_user(@user, user_params)
+
+        render json: @user
+      end
+
+      # DELETE /api/v1/users/:id
+      def destroy
+        authorize @user, :destroy?
+
+        service = UserManagement::UserService.new(
+          current_user: current_user,
+          organization_id: current_organization.id
+        )
+
+        # Service publishes UserDeletedEvent
+        service.delete_user(@user)
+
+        head :no_content
+      end
+
+      private
+
+      def set_user
+        @user = SmartDomain::Integration::TenantContext.with_tenant(current_organization.id) do
+          User.find(params[:id])
+        end
+      end
+
+      def user_params
+        params.require(:user).permit(:email, :name, :role)
+      end
+
+      def authorize(user, action)
+        policy = UserPolicy.new(current_user, user)
+        unless policy.public_send(action)
+          raise SmartDomain::Domain::Exceptions::UnauthorizedError, "Not authorized to #{action} this user"
+        end
+      end
+    end
+  end
+end

data/examples/blog_app/app/controllers/application_controller.rb

@@ -0,0 +1,7 @@
+class ApplicationController < ActionController::Base
+  # Only allow modern browsers supporting webp images, web push, badges, import maps, CSS nesting, and CSS :has.
+  allow_browser versions: :modern
+
+  # Changes to the importmap will invalidate the etag for HTML responses
+  stale_when_importmap_changes
+end

data/examples/blog_app/app/domains/exceptions.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SmartDomain
+  module Domain
+    module Exceptions
+      # Base domain exception
+      class DomainError < StandardError; end
+
+      # Authorization error
+      class UnauthorizedError < DomainError; end
+
+      # Validation error
+      class ValidationError < DomainError; end
+
+      # Not found error
+      class NotFoundError < DomainError; end
+    end
+  end
+end