Sembot — Documentation

English

Polski

English

Polski

Appearance

MarketerAI Module Architecture - Overview ​

Table of Contents ​

  1. Module Overview
  2. Documentation Structure
  3. High-Level Architecture
  4. Main Components
  5. Technologies

Module Overview ​

MarketerAI is an advanced conversational module based on LLMs (Large Language Models) that enables users to interact with the system through natural language. The module provides:

  • Intelligent conversation with AI agents
  • Action execution through functions (tools)
  • Hierarchical agent structure (agent → subagent)
  • Real-time response streaming
  • Action confirmation requiring user consent
  • Multi-threaded conversation (parent threads + subthreads)
  • Knowledge base integration

Documentation Structure ​

The MarketerAI module documentation is divided into the following files:

1. MarketerAI_Architecture_Overview.md (this file) ​

High-level overview of the architecture and documentation structure.

2. MarketerAI_Models.md ​

Detailed description of data models:

  • Agent
  • ChatThread
  • ChatMessage
  • ChatFunction
  • UserMessage
  • Relationships between models

3. MarketerAI_Services.md ​

Description of main services:

  • ChatService
  • OpenAiService
  • RuntimeChatFunctionsService
  • SubagentThreadService

4. MarketerAI_Repositories.md ​

Repositories managing data:

  • ChatMessageRepository
  • ChatFunctionRepository

5. MarketerAI_ChatFunctions.md ​

Function (tools) system for AI:

  • Abstract ChatFunction class
  • Function categories
  • Implementation examples
  • Validation and confirmations

6. MarketerAI_Flow.md ​

Detailed information flow:

  • From user query to AI response
  • Streaming handling
  • Subagent mechanism
  • Confirmation system

7. MarketerAI_Events.md ​

Event system and real-time communication:

  • Broadcasting events
  • WebSocket integration
  • All event types

8. MarketerAI_Job.md ​

ChatStream Job - implementation details:

  • Queue handling
  • Execution scenarios
  • Error handling

High-Level Architecture ​

Main Components ​

1. Controllers ​

  • SembotChatController - main API endpoint for conversations

2. Jobs (Asynchronous Tasks) ​

  • ChatStream - main job handling conversation streaming

3. Services ​

  • ChatService - conversation logic orchestration
  • OpenAiService - communication with AI provider APIs
  • RuntimeChatFunctionsService - runtime function management
  • SubagentThreadService - subagent management

4. Repositories ​

  • ChatMessageRepository - message operations
  • ChatFunctionRepository - function management

5. Models ​

  • Agent - AI agent definition
  • ChatThread - conversation thread
  • ChatMessage - single message
  • ChatFunction - function/tool definition

6. Functions (ChatFunctions) ​

  • Abstract ChatFunction class
  • Domain-specific implementations (GoogleAds, Products, Analytics, etc.)

7. Events ​

  • Broadcasting system for real-time communication with the frontend
  • 17 different event types

Technologies ​

Backend ​

  • Laravel 10+ - application framework
  • PHP 8.2+ - programming language
  • MySQL - database (with recursive CTE)
  • Redis - queue & cache
  • Laravel Queue - asynchronous processing
  • Laravel Broadcasting - WebSocket events

AI/LLM Integration ​

  • OpenAI API (GPT-4o, GPT-4o-mini, o1, o3-mini, GPT-5)
  • Groq API - alternative provider
  • OpenRouter API - model aggregator

WebSocket ​

  • Laravel Echo - client-side
  • Pusher/Laravel Reverb - broadcasting backend

Monitoring ​

  • OpenTelemetry - distributed tracing
  • Laravel Telescope - debugging

Key Design Patterns ​

1. Repository Pattern ​

Separation of data access logic from business logic.

2. Service Layer Pattern ​

Centralization of business logic in dedicated services.

3. Strategy Pattern ​

Different strategies for different AI providers (OpenAI, Groq, OpenRouter).

4. Observer Pattern ​

Laravel event system for broadcasting.

5. Chain of Responsibility ​

Flow through agent → subagent → functions.

6. Factory Pattern ​

Dynamic instantiation of ChatFunction instances.

7. Template Method Pattern ​

Abstract ChatFunction class with handle() method.

Flow Diagram - Simplified ​

Key Features ​

1. Response Streaming ​

AI responses are streamed chunk by chunk to the user via WebSocket.

2. Agent Hierarchy ​

An agent can delegate tasks to subagents (specialized agents).

3. Confirmation System ​

Sensitive actions (e.g., data modifications) require user confirmation.

4. Multi-threading ​

Subagents create sub-threads, allowing context isolation.

5. Runtime Functions ​

Some functions (e.g., searchKnowledgeBase) are available to all agents without database configuration.

6. Argument Validation ​

Each function has its own validation rules (Laravel Validation).

7. Knowledge Base ​

Integration with the knowledge base system via Qdrant (vector search).

8. Multi-Provider Support ​

Support for multiple LLM providers (OpenAI, Groq, OpenRouter).

Next Steps ​

To learn implementation details, refer to the remaining documentation files:

  1. MarketerAI_Models.md - Understand the data structure
  2. MarketerAI_Services.md - Learn about the main services
  3. MarketerAI_Flow.md - See the detailed data flow
  4. MarketerAI_ChatFunctions.md - Learn how to create new functions
  5. MarketerAI_Events.md - Understand real-time communication
  6. MarketerAI_Job.md - Learn the job implementation details

Component Relationship Diagram ​

Created: 2025-11-26
Version: 1.0
Author: Automatically generated documentation