sequenceDiagram
  participant Caller
  participant BSS as BaileysStartupService
  participant PR as PrismaRepository

  Caller->>BSS: fetchMessages(query)
  BSS->>BSS: Construct filterOptions from query
  BSS->>PR: message.count(filterOptions)
  PR-->>BSS: count
  BSS->>PR: message.findMany(filterOptions, pagination, selectFields)
  PR-->>BSS: rawMessages
  BSS->>BSS: Loop: Format each message (apply pushName logic)
  BSS-->>Caller: { total, pages, currentPage, records: formattedMessages }

sequenceDiagram
  participant BaileysSocket
  participant BSS as BaileysStartupService
  participant ContactsMap as contactsMap (internal)

  BaileysSocket->>BSS: Event: 'messages.upsert' (messagesUpdate)
  BSS->>BSS: Populate contactsMap from available contacts data
  loop For each message 'm' in messagesUpdate.messages
    alt If !m.pushName AND !m.key.fromMe
      BSS->>BSS: participantJid = m.participant || m.key.participant || m.key.remoteJid
      alt participantJid AND contactsMap.has(participantJid)
        BSS->>ContactsMap: get(participantJid)
        ContactsMap-->>BSS: contactInfo (with name)
        BSS->>BSS: m.pushName = contactInfo.name
      else if participantJid
        BSS->>BSS: m.pushName = participantJid.split('@')[0] (fallback)
      end
    end
    BSS->>BSS: preparedMessage = prepareMessage(m)
    note right of BSS: prepareMessage itself also contains updated pushName fallback logic
    BSS->>BSS: Further processing of preparedMessage (e.g., save, emit)
  end

classDiagram
  class BaileysStartupService {
    -authStateProvider: AuthStateProvider
    -msgRetryCounterCache: CacheStore
    -userDevicesCache: CacheStore
    +fetchMessages(query: Query_Message): Promise<FetchMessagesResponse>
    +prepareMessage(message: any): any
    #upsertMessage(messagesUpdate: any, messageType: any): Promise<void>
  }
  class Query_Message {
    +where: MessageWhereInput
    +offset: number
    +page: number
  }
  class MessageWhereInput {
    +id: string
    +source: string
    +messageType: string
    +messageTimestamp: TimestampFilter
    +key: KeyFilter
  }
  class KeyFilter {
    +id: string
    +fromMe: boolean
    +remoteJid: string
    +participants: string
  }
  class TimestampFilter {
    +gte: string
    +lte: string
  }
  class FetchMessagesResponse {
    +messages: PaginatedMessages
  }
  class PaginatedMessages {
    +total: number
    +pages: number
    +currentPage: number
    +records: object[]
  }

  BaileysStartupService ..> Query_Message : uses
  BaileysStartupService ..> FetchMessagesResponse : uses
  Query_Message *-- MessageWhereInput : contains
  MessageWhereInput *-- KeyFilter : contains
  MessageWhereInput *-- TimestampFilter : contains
  FetchMessagesResponse *-- PaginatedMessages : contains

  note for BaileysStartupService "New method fetchMessages added.\npushName logic enhanced in upsertMessage and prepareMessage."