Restructure omni services and add Chatwoot research snapshot

research/chatwoot/app/services/mailbox/conversation_finder.rb

@@ -0,0 +1,29 @@
+class Mailbox::ConversationFinder
+  DEFAULT_STRATEGIES = [
+    Mailbox::ConversationFinderStrategies::ReceiverUuidStrategy,
+    Mailbox::ConversationFinderStrategies::InReplyToStrategy,
+    Mailbox::ConversationFinderStrategies::ReferencesStrategy,
+    Mailbox::ConversationFinderStrategies::NewConversationStrategy
+  ].freeze
+
+  def initialize(mail, strategies: DEFAULT_STRATEGIES)
+    @mail = mail
+    @strategies = strategies
+  end
+
+  def find
+    @strategies.each do |strategy_class|
+      conversation = strategy_class.new(@mail).find
+
+      next unless conversation
+
+      strategy_name = strategy_class.name.demodulize.underscore
+      Rails.logger.info "Conversation found via #{strategy_name} strategy"
+      return conversation
+    end
+
+    # Should not reach here if NewConversationStrategy is in the chain
+    Rails.logger.error 'No conversation found via any strategy (NewConversationStrategy missing?)'
+    nil
+  end
+end

research/chatwoot/app/services/mailbox/conversation_finder_strategies/base_strategy.rb

@@ -0,0 +1,13 @@
+class Mailbox::ConversationFinderStrategies::BaseStrategy
+  attr_reader :mail
+
+  def initialize(mail)
+    @mail = mail
+  end
+
+  # Returns Conversation or nil
+  # Subclasses must implement this method
+  def find
+    raise NotImplementedError, "#{self.class} must implement #find"
+  end
+end

research/chatwoot/app/services/mailbox/conversation_finder_strategies/in_reply_to_strategy.rb

@@ -0,0 +1,48 @@
+class Mailbox::ConversationFinderStrategies::InReplyToStrategy < Mailbox::ConversationFinderStrategies::BaseStrategy
+  # Patterns from ApplicationMailbox
+  MESSAGE_PATTERN = %r{conversation/([a-zA-Z0-9-]+)/messages/(\d+)@}
+
+  # FALLBACK_PATTERN is used when building In-Reply-To headers in ConversationReplyMailer
+  # when there's no actual message to reply to (see app/mailers/conversation_reply_mailer.rb#in_reply_to_email).
+  # This happens when:
+  # - A conversation is started by an agent (no incoming message yet)
+  # - The conversation originated from a non-email channel (widget, WhatsApp, etc.) but is now using email
+  # - The incoming message doesn't have email metadata with a message_id
+  # In these cases, we use a conversation-level identifier instead of a message-level one.
+  FALLBACK_PATTERN = %r{account/(\d+)/conversation/([a-zA-Z0-9-]+)@}
+
+  def find
+    return nil if mail.in_reply_to.blank?
+
+    in_reply_to_addresses = Array.wrap(mail.in_reply_to)
+
+    in_reply_to_addresses.each do |in_reply_to|
+      # Try extracting UUID from patterns
+      uuid = extract_uuid_from_patterns(in_reply_to)
+      if uuid
+        conversation = Conversation.find_by(uuid: uuid)
+        return conversation if conversation
+      end
+
+      # Try finding by message source_id
+      message = Message.find_by(source_id: in_reply_to)
+      return message.conversation if message&.conversation
+    end
+
+    nil
+  end
+
+  private
+
+  def extract_uuid_from_patterns(message_id)
+    # Try message-specific pattern first
+    match = MESSAGE_PATTERN.match(message_id)
+    return match[1] if match
+
+    # Try conversation fallback pattern
+    match = FALLBACK_PATTERN.match(message_id)
+    return match[2] if match
+
+    nil
+  end
+end

research/chatwoot/app/services/mailbox/conversation_finder_strategies/new_conversation_strategy.rb

@@ -0,0 +1,83 @@
+class Mailbox::ConversationFinderStrategies::NewConversationStrategy < Mailbox::ConversationFinderStrategies::BaseStrategy
+  include MailboxHelper
+  include IncomingEmailValidityHelper
+
+  attr_accessor :processed_mail, :account, :inbox, :contact, :contact_inbox, :conversation, :channel
+
+  def initialize(mail)
+    super(mail)
+    @channel = EmailChannelFinder.new(mail).perform
+    return unless @channel
+
+    @account = @channel.account
+    @inbox = @channel.inbox
+    @processed_mail = MailPresenter.new(mail, @account)
+  end
+
+  # This strategy prepares a new conversation but doesn't persist it yet.
+  # Why we don't use create! here:
+  # - Avoids orphan conversations if message/attachment creation fails later
+  # - Prevents duplicate conversations on job retry (no idempotency issue)
+  # - Follows the pattern from old SupportMailbox where everything was in one transaction
+  # The actual persistence happens in ReplyMailbox within a transaction that includes message creation.
+  def find
+    return nil unless @channel # No valid channel found
+    return nil unless incoming_email_from_valid_email? # Skip edge cases
+
+    # Check if conversation already exists by in_reply_to
+    existing_conversation = find_conversation_by_in_reply_to
+    return existing_conversation if existing_conversation
+
+    # Prepare contact (persisted) and build conversation (not persisted)
+    find_or_create_contact
+    build_conversation
+  end
+
+  private
+
+  def find_or_create_contact
+    @contact = @inbox.contacts.from_email(original_sender_email)
+    if @contact.present?
+      @contact_inbox = ContactInbox.find_by(inbox: @inbox, contact: @contact)
+    else
+      create_contact
+    end
+  end
+
+  def original_sender_email
+    @processed_mail.original_sender&.downcase
+  end
+
+  def identify_contact_name
+    @processed_mail.sender_name || @processed_mail.from.first.split('@').first
+  end
+
+  def build_conversation
+    # Build but don't persist - ReplyMailbox will save in transaction with message
+    @conversation = ::Conversation.new(
+      account_id: @account.id,
+      inbox_id: @inbox.id,
+      contact_id: @contact.id,
+      contact_inbox_id: @contact_inbox.id,
+      additional_attributes: {
+        in_reply_to: in_reply_to,
+        source: 'email',
+        auto_reply: @processed_mail.auto_reply?,
+        mail_subject: @processed_mail.subject,
+        initiated_at: {
+          timestamp: Time.now.utc
+        }
+      }
+    )
+  end
+
+  def in_reply_to
+    mail['In-Reply-To'].try(:value)
+  end
+
+  def find_conversation_by_in_reply_to
+    return if in_reply_to.blank?
+
+    @account.conversations.where("additional_attributes->>'in_reply_to' = ?", in_reply_to).first
+  end
+end

research/chatwoot/app/services/mailbox/conversation_finder_strategies/receiver_uuid_strategy.rb

@@ -0,0 +1,26 @@
+class Mailbox::ConversationFinderStrategies::ReceiverUuidStrategy < Mailbox::ConversationFinderStrategies::BaseStrategy
+  # Pattern from ApplicationMailbox::REPLY_EMAIL_UUID_PATTERN
+  UUID_PATTERN = /^reply\+([0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12})$/i
+
+  def find
+    uuid = extract_uuid_from_receivers
+    return nil unless uuid
+
+    Conversation.find_by(uuid: uuid)
+  end
+
+  private
+
+  def extract_uuid_from_receivers
+    mail_presenter = MailPresenter.new(mail)
+    return nil if mail_presenter.mail_receiver.blank?
+
+    mail_presenter.mail_receiver.each do |email|
+      username = email.split('@').first
+      match = username.match(UUID_PATTERN)
+      return match[1] if match
+    end
+
+    nil
+  end
+end

research/chatwoot/app/services/mailbox/conversation_finder_strategies/references_strategy.rb

@@ -0,0 +1,59 @@
+class Mailbox::ConversationFinderStrategies::ReferencesStrategy < Mailbox::ConversationFinderStrategies::BaseStrategy
+  # Patterns from ApplicationMailbox
+  MESSAGE_PATTERN = %r{conversation/([a-zA-Z0-9-]+)/messages/(\d+)@}
+
+  # FALLBACK_PATTERN is used when building References headers in ConversationReplyMailer
+  # when there's no actual message to reply to (see app/mailers/conversation_reply_mailer.rb#in_reply_to_email).
+  # This happens when:
+  # - A conversation is started by an agent (no incoming message yet)
+  # - The conversation originated from a non-email channel (widget, WhatsApp, etc.) but is now using email
+  # - The incoming message doesn't have email metadata with a message_id
+  # In these cases, we use a conversation-level identifier instead of a message-level one.
+  FALLBACK_PATTERN = %r{account/(\d+)/conversation/([a-zA-Z0-9-]+)@}
+
+  def initialize(mail)
+    super(mail)
+    # Get channel once upfront to use for scoped queries
+    @channel = EmailChannelFinder.new(mail).perform
+  end
+
+  def find
+    return nil if mail.references.blank?
+    return nil unless @channel # No valid channel found
+
+    references = Array.wrap(mail.references)
+
+    references.each do |reference|
+      conversation = find_conversation_from_reference(reference)
+      return conversation if conversation
+    end
+
+    nil
+  end
+
+  private
+
+  def find_conversation_from_reference(reference)
+    # Try extracting UUID from patterns
+    uuid = extract_uuid_from_patterns(reference)
+    if uuid
+      # Query scoped to inbox - prevents cross-account/cross-inbox matches at database level
+      conversation = Conversation.find_by(uuid: uuid, inbox_id: @channel.inbox.id)
+      return conversation if conversation
+    end
+
+    # We scope to the inbox, that way we filter out messages and conversations that don't belong to the channel
+    message = Message.find_by(source_id: reference, inbox_id: @channel.inbox.id)
+    message&.conversation
+  end
+
+  def extract_uuid_from_patterns(message_id)
+    match = MESSAGE_PATTERN.match(message_id)
+    return match[1] if match
+
+    match = FALLBACK_PATTERN.match(message_id)
+    return match[2] if match
+
+    nil
+  end
+end