Skip to main content

Architecture Overview

This document provides a comprehensive overview of the Hexabot + Prophunt multi-agent architecture.

System Components​

The system consists of three main layers:

1. Frontend Layer (Angular + Socket.io)​

  • Responsibility: User interface and real-time communication
  • Technology: Angular 17, Socket.io Client, RxJS
  • Port: 8101 (development)

2. Backend Layer (Hexabot + Multi-Agent Orchestrator)​

  • Responsibility: Message routing, agent orchestration, conversation management
  • Technology: NestJS, Socket.io Server, MongoDB
  • Port: 4000 (host) → 3000 (container)

3. Business Logic Layer (Prophunt Webserver)​

  • Responsibility: Payment processing, document verification, third-party integrations
  • Technology: Node.js/Express (or your stack)
  • Port: 3000 or configured

High-Level Architecture​

┌────────────────────────────────────────────────────────────────────┐
│                          USER                                      │
└────────────────────────┬───────────────────────────────────────────┘
                         │
                         │ Browser
                         │
┌────────────────────────▼───────────────────────────────────────────┐
│                   FRONTEND LAYER                                   │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  Angular Application (Port 8101)                             │ │
│  │  • ChatComponent                                             │ │
│  │  • ChatService (Socket.io Client)                            │ │
│  │  • AuthService                                               │ │
│  └──────────────────────────────────────────────────────────────┘ │
└────────────────────────┬───────────────────────────────────────────┘
                         │
                         │ WebSocket (Socket.io)
                         │ ws://localhost:4000/socket.io
                         │
┌────────────────────────▼───────────────────────────────────────────┐
│                    BACKEND LAYER (Hexabot)                         │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  ChatGateway (@WebSocketGateway)                             │ │
│  │  • Handles Socket.io connections                             │ │
│  │  • join_channel / leave_channel events                       │ │
│  │  • message / event handlers                                  │ │
│  └────────────────┬─────────────────────────────────────────────┘ │
│                   │                                                 │
│  ┌────────────────▼─────────────────────────────────────────────┐ │
│  │  Agent Orchestrator Module                                   │ │
│  │  ┌────────────────────────────────────────────────────────┐ │ │
│  │  │  AgentRouter                                           │ │ │
│  │  │  • Routes messages to correct agent                    │ │ │
│  │  │  • Uses AgentRegistry to find agents                   │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  │  ┌────────────────────────────────────────────────────────┐ │ │
│  │  │  ChannelManager                                        │ │ │
│  │  │  • Maps channel_id → agent_id                          │ │ │
│  │  │  • Isolates conversations per agent                    │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  │  ┌────────────────────────────────────────────────────────┐ │ │
│  │  │  ConversationManager (NEW)                             │ │ │
│  │  │  • Persistent conversation storage                     │ │ │
│  │  │  • Links taskId ↔ verificationId                       │ │ │
│  │  │  • Message persistence                                 │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  │  ┌────────────────────────────────────────────────────────┐ │ │
│  │  │  EventBus                                              │ │ │
│  │  │  • Pub/sub for async agent coordination               │ │ │
│  │  │  • Decouples event producers/consumers                │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  │  ┌────────────────────────────────────────────────────────┐ │ │
│  │  │  SocketAdapter                                         │ │ │
│  │  │  • Emits messages to channels (rooms)                 │ │ │
│  │  │  • Handles typing indicators, state updates           │ │ │
│  │  └────────────────────────────────────────────────────────┘ │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  Agents Module                                               │ │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐            │ │
│  │  │  BGVAgent  │  │ LoanAgent  │  │ListingAgent│            │ │
│  │  │            │  │            │  │            │            │ │
│  │  │• State     │  │• State     │  │• State     │            │ │
│  │  │  Machine   │  │  Machine   │  │  Machine   │            │ │
│  │  │• Message   │  │• Message   │  │• Message   │            │ │
│  │  │  Builder   │  │  Builder   │  │  Builder   │            │ │
│  │  │• Service   │  │• Service   │  │• Service   │            │ │
│  │  │  (API)     │  │  (API)     │  │  (API)     │            │ │
│  │  └──────┬─────┘  └──────┬─────┘  └──────┬─────┘            │ │
│  └─────────┼────────────────┼────────────────┼─────────────────┘ │
│            │                │                │                    │
│            └────────────────┴────────────────┘                    │
│                             │                                      │
│  ┌──────────────────────────▼────────────────────────────────────┐│
│  │  AgentApiController (NEW)                                     ││
│  │  • POST /agent-api/send-message                               ││
│  │  • POST /agent-api/send-custom                                ││
│  │  • POST /agent-api/link-verification                          ││
│  │  • GET  /agent-api/conversation/:taskId/history               ││
│  │  • POST /agent-api/conversation/:taskId/state                 ││
│  └───────────────────────────────────────────────────────────────┘│
│                             │                                      │
│  ┌──────────────────────────▼────────────────────────────────────┐│
│  │  Persistence Layer                                            ││
│  │  • ConversationRepository (Hexabot)                           ││
│  │  • MessageRepository (Hexabot)                                ││
│  │  • MongoDB Collections: conversations, messages               ││
│  └───────────────────────────────────────────────────────────────┘│
└────────────────────────┬───────────────────────────────────────────┘
                         │
                         │ HTTP REST API
                         │ http://localhost:4000/agent-api/*
                         │
┌────────────────────────▼───────────────────────────────────────────┐
│              BUSINESS LOGIC LAYER (Prophunt Webserver)             │
│  • Payment Gateway Integration                                     │
│  • Document OCR & Verification                                     │
│  • BGV Service Provider Integration                                │
│  • Loan Eligibility Calculation                                    │
│  • Listing Management                                              │
└────────────────────────────────────────────────────────────────────┘

Design Principles​

1. Separation of Concerns​

  • Frontend: UI/UX, user input, real-time display
  • Hexabot: Message routing, conversation flow, agent orchestration
  • Webserver: Business logic, external APIs, payment processing

2. Event-Driven Architecture​

  • Components communicate via events (EventBus)
  • Async, non-blocking operations
  • Loose coupling between modules

3. Multi-Tenancy via Channels​

  • Each agent has its own channel (e.g., prophunt_bgv)
  • Conversations are isolated per channel
  • Users can switch agents seamlessly

4. Persistence​

  • All conversations stored in MongoDB
  • Messages persisted for history retrieval
  • Context stored in conversation.context.vars

5. Type Safety​

  • Full TypeScript implementation
  • Compile-time validation
  • Strong typing for messages, events, contexts

Communication Patterns​

Pattern 1: User Message Flow​

User Types → Frontend → Socket.io → ChatGateway → AgentRouter 
  → Agent → Message Builder → Response
  → ConversationManager (persist) → SocketAdapter → Frontend → User

Pattern 2: Webserver → User Message Flow​

Webserver Event (Payment Success) 
  → HTTP POST /agent-api/send-message
  → AgentApiController
  → ConversationManager.sendMessage(taskId, message)
  → MessageRepo (persist)
  → SocketAdapter.emitToChannel(channelId, message)
  → Frontend → User sees "Payment successful!"

Pattern 3: Event-Driven Agent Coordination​

File Upload Event
  → ChatGateway receives event
  → EventHandler.handleEvent()
  → EventBus.emit('FILE_UPLOADED', data)
  → BGVAgent.handleEvent() [subscribed]
  → BGVAgent calls webserver API
  → Webserver processes, stores file
  → Webserver calls /agent-api/send-message
  → User receives confirmation

Data Flow​

Conversation Lifecycle​

graph TD
    A[User connects to chat] --> B[Frontend joins channel via Socket.io]
    B --> C[ChatGateway creates/retrieves conversation]
    C --> D[ConversationManager.getOrCreateConversation]
    D --> E{Conversation exists?}
    E -->|Yes| F[Load from MongoDB]
    E -->|No| G[Create new with taskId]
    F --> H[Return conversation context]
    G --> H
    H --> I[Agent processes message]
    I --> J[Generate responses]
    J --> K[ConversationManager.sendMessage]
    K --> L[Persist to MessageRepo]
    K --> M[SocketAdapter.emitToChannel]
    M --> N[Frontend displays message]

Agent Activation​

graph TD
    A[Message received] --> B[AgentRouter.routeMessage]
    B --> C{Has active agent in context?}
    C -->|Yes| D[Use agentId from context.vars]
    C -->|No| E[Check trigger keywords]
    E --> F{Keywords match?}
    F -->|Yes| G[Activate matching agent]
    F -->|No| H[Use default/fallback agent]
    D --> I[Agent.processMessage]
    G --> I
    H --> I
    I --> J[Update context with agent state]
    J --> K[Return message responses]

Key Components Deep Dive​

AgentRouter​

  • Purpose: Routes incoming messages to the correct agent
  • How: Checks context.vars.active_agent or uses keyword matching
  • Input: ChannelMessage, ConversationContext
  • Output: Agent instance

EventBus​

  • Purpose: Decoupled pub/sub communication
  • Pattern: Observer pattern
  • Use Cases: File uploads, payment callbacks, verification status updates
  • API: subscribe(eventType, handler), emit(eventType, data)

ChannelManager​

  • Purpose: Maps channels to agents and conversations
  • Channel Format: prophunt_{agentId} or prophunt_{agentId}_{userId}
  • Responsibilities: Channel validation, agent extraction, conversation ID mapping

ConversationManager (New)​

  • Purpose: Persistent conversation and message storage
  • Key Methods:
    • getOrCreateConversation(channelId, userId)
    • getConversationByTaskId(taskId)
    • sendMessage(conversationId, channelId, message)
    • linkVerificationId(conversationId, verificationId)

Next Steps​