MTS AI Commerce Assistant

AI Sales & Product Recommendation Engine for Adobe Commerce / Magento 2.

MTS AI Commerce Assistant is a modular, scalable Magento 2 extension that delivers personalized product recommendations using machine learning, vector embeddings, and behavioral analytics. It supports OpenAI as the primary AI provider with graceful fallback to rule-based algorithms.

Technology Stack

System Architecture

High-Level Architecture Diagram

Layer Responsibilities

Module Structure

Database Schema

6 custom tables with foreign key constraints and indexed columns for query performance.

Entity Relationship Diagram

Table: magetech_ai_recommendation

Core recommendation entity. Stores AI-generated and rule-based recommendation pairs.

Table: magetech_ai_vector_embedding

Stores product vector embeddings for semantic similarity search via cosine distance.

Table: magetech_ai_tracking_event

Raw behavioral tracking events. High-volume write table for user interaction signals.

Remaining Tables

API Contracts

All service contracts follow Magento 2 conventions. Interfaces are in Api/, data interfaces in Api/Data/.

Data Transfer Object Interfaces

All extend Magento\Framework\Api\ExtensibleDataInterface for custom attribute support.

Repository Interfaces

Service Interfaces

Dependency Injection

Interface Preferences (Global)

<preference for="Api\RecommendationRepositoryInterface"
              type="Model\RecommendationRepository"/>
<preference for="Api\PromptTemplateRepositoryInterface"
              type="Model\PromptTemplateRepository"/>
<preference for="Api\RecommendationAnalyticsRepositoryInterface"
              type="Model\RecommendationAnalyticsRepository"/>
<preference for="Api\VectorEmbeddingRepositoryInterface"
              type="Model\VectorEmbeddingRepository"/>
<preference for="Api\RecommendationServiceInterface"
              type="Model\RecommendationService"/>
<preference for="Api\AiProcessorInterface"
              type="Model\Engine\AiProcessor"/>

Virtual Types

<virtualType name="MageTechAIRecommendationLogger"
             type="Magento\Framework\Logger\Monolog">
    <arguments>
        <argument name="name" xsi:type="string">magetech_ai_recommendation</argument>
        <argument name="handlers" xsi:type="array">
            <item name="system" xsi:type="object">
                Magento\Framework\Logger\Handler\System
            </item>
        </argument>
    </arguments>
</virtualType>

Frontend Plugins

Recommendation Engines

7 engines behind the Strategy pattern, selected at runtime via EngineFactory.

Engine Hierarchy

Engine Details

AI Processor

Central AI service that interfaces with OpenAI API for embeddings and completions.

Capabilities

Fallback Behavior

When OpenAI API is unavailable or times out (configurable timeout, default 30s), the processor falls back to rule-based engines. The fallback_to_rules config toggle controls this behavior.

Vector Embeddings

Generation Pipeline

Cosine Similarity Formula

cosine_similarity(A, B) = dot(A, B) / (magnitude(A) * magnitude(B))

where:
  dot(A, B)    = Σ(Ai * Bi)         for i = 0 to 1535
  magnitude(A) = sqrt(Σ(Ai²))       for i = 0 to 1535

Design Patterns

Event System (Observers)

6 observers hooked to Magento core events for behavioral tracking and async processing.

All observers wrap logic in try-catch to prevent frontend disruption on errors.

Plugins (Interceptors)

4 after-plugins on Magento core classes, registered in etc/frontend/di.xml.

All plugins are scaffolded stubs — they pass through $result unchanged but inject RecommendationServiceInterface for future use.

Message Queues

Asynchronous processing via AMQP (RabbitMQ) with 3 topics, publishers, consumers, and message DTOs.

Queue Topology

Message DTOs

Cron Jobs

5 scheduled tasks for maintenance, embedding generation, and cache warming.

Cache System

Cache Layers

Cache Flush

• Admin controller: Controller\Adminhtml\Cache\Flush
• Service method: RecommendationService::flushCache()
• Cron: RefreshRecommendations clears cache every 4 hours
• Config toggle: magetech/airecommendation/cache/enabled

GraphQL API

Schema defined in view/graphql/schema.graphqls with 5 resolvers.

Queries

Mutations

Response Types

type ProductRecommendationsOutput {
    success: Boolean!
    message: String
    items: [RecommendedProduct]
}

type RecommendedProduct {
    product_id: Int
    sku: String
    name: String
    url: String
    image_url: String
    price: Float
    special_price: Float
}

REST API

Request/Response Examples

// GET /V1/magetech/recommendations/homepage?limit=6
{
    "success": true,
    "recommendations": [
        {
            "entity_id": 123,
            "product_id": 456,
            "recommended_product_id": 789,
            "engine_type": "similar_products",
            "score": 0.8542,
            "product": { "sku": "ABC-123", "name": "..." }
        }
    ]
}

// POST /V1/magetech/tracking
// Request body:
{
    "event_type": "click",
    "product_id": 789,
    "recommendation_id": 123,
    "placement": "homepage"
}
// Response: true

Frontend Architecture

Theme Compatibility

Layout XML Mapping

JavaScript Modules

CSS Architecture

Single stylesheet: view/frontend/web/css/mage-tech-ai-recommendation.css

• CSS Grid layout: grid-template-columns: repeat(auto-fill, minmax(200px, 1fr))
• Carousel with horizontal scroll and overflow hidden
• Product card hover effects with transform scale
• Responsive breakpoint at 768px
• Hyva-specific border radius and shadow overrides

Admin Panel

Admin Controllers (12)

ACL Hierarchy

MageTech_AIRecommendation::admin
├── MageTech_AIRecommendation::config
├── MageTech_AIRecommendation::recommendation
│   ├── ::recommendation_view
│   ├── ::recommendation_new
│   ├── ::recommendation_edit
│   └── ::recommendation_delete
├── MageTech_AIRecommendation::prompt_template
│   ├── ::prompt_template_view
│   ├── ::prompt_template_new
│   ├── ::prompt_template_edit
│   └── ::prompt_template_delete
├── MageTech_AIRecommendation::analytics
│   ├── ::analytics_dashboard
│   ├── ::analytics_ctr
│   └── ::analytics_conversion
└── MageTech_AIRecommendation::cache_management

Configuration Reference

Admin path: Stores > Configuration > MageTech > AI Recommendations

Default Values

Security

• API Key Storage: OpenAI API key stored as obscured field in Magento config (encrypted at rest)
• ACL: Full admin ACL hierarchy with granular permissions per entity type
• Input Validation: All API endpoints validate input types and ranges
• SQL Injection: Prevented via Magento ORM (prepared statements)
• XSS: All output escaped via PHTML $escaper->escapeHtml()
• CSRF: Admin forms use Magento CSRF tokens
• Rate Limiting: OpenAI API calls respect configurable timeout (default 30s)
• Fallback: Graceful degradation to rule-based algorithms when API unavailable
• Observer Error Handling: All observers catch exceptions silently to prevent frontend disruption

Performance Considerations

Database Indexes

-- High-performance indexes for query optimization
CREATE INDEX idx_tracking_customer ON magetech_ai_tracking_event (customer_id);
CREATE INDEX idx_tracking_type ON magetech_ai_tracking_event (event_type);
CREATE INDEX idx_tracking_product ON magetech_ai_tracking_event (product_id);
CREATE INDEX idx_tracking_time ON magetech_ai_tracking_event (event_time);
CREATE INDEX idx_recommendation_engine ON magetech_ai_recommendation (engine_type);
CREATE INDEX idx_recommendation_placement ON magetech_ai_recommendation (placement);
CREATE UNIQUE INDEX idx_embedding_product ON magetech_ai_vector_embedding (product_id);
CREATE UNIQUE INDEX idx_preference_customer ON magetech_ai_customer_preference (customer_id);