Developer Docs

The Mallnline Algorithm is the driving force behind personalized discovery across the platform. Instead of a chronological feed or static storefront index, the algorithm curates products, services, and content based on a combination of global trending signals and personalized social graph connections.

This engine powers the Lobby discovery tab, intelligent auto-complete, and contextual item ranking across all vertical Malets.

Architecture Overview

The system bridges three primary services to deliver a low-latency, personalized experience:

  1. intelligence (Rust): The offline computation engine that aggregates signals (Murchases, views, Wishlist adds) into a unified trendingScore.
  2. nodes (NestJS): The social graph provider, maintaining the unidirectional Follow relationships between Visitors and Malets.
  3. search (NestJS / Meilisearch): The real-time indexing and retrieval engine that applies custom ranking rules and executes forYouFeed queries.

Signal Computation

The intelligence Rust service runs a scheduled background batch job to calculate a deterministic trendingScore for all indexable items.

By default, this job runs on a 4-hour cycle. The frequency is fully configurable per-environment via the TRENDING_CRON_SCHEDULE environment variable in the intelligence service (default: 0 0 */4 * * *). Set it in the service's .env file — no code changes required.

Variable Default Where to set
TRENDING_CRON_SCHEDULE 0 0 */4 * * * (every 4 hours) apps/intelligence/.env
MEILISEARCH_HOST http://localhost:7700 apps/intelligence/.env
MEILISEARCH_API_KEY masterKey apps/intelligence/.env

The current formula weights high-intent actions heavier than passive ones:

Trending Score = (Purchases × 3) + (Wishlist Adds × 2) + (Views × 1)

Once computed, the service batches updates and pushes them directly to the Meilisearch REST API via the items index. It then emits a trending_scores_updated TCP event, signaling the NestJS search subgraph to synchronize any dependent caching or state. This follows the same event-driven sync pattern used for item_upserted and item_deleted events.

Personalization Engine

The search subgraph exposes the forYouFeed GraphQL query, which acts as the primary entry point for personalized discovery.

The algorithm operates in two primary modes defined by the SearchMode enum:

  • SearchMode.PERSONALIZED: Activated when an authenticated Visitor provides a list of followed maletIds (sourced from the Follow system). The engine heavily boosts or filters results to prioritize content from Malets the Visitor explicitly follows, ordered secondarily by trendingScore and indexedAt to keep the feed fresh.
  • SearchMode.TRENDING: The fallback mode for anonymous Visitors or authenticated Visitors who do not follow any Malets. This mode ranks the entire platform catalog globally, strictly by trendingScore:desc.

Meilisearch Custom Ranking

To support this without massive runtime performance hits, Meilisearch's custom ranking rules are configured to use trendingScore as a primary tiebreaker:

// search/src/meilisearch/meilisearch.service.ts
const rankingRules = [
  'words',
  'typo',
  'proximity',
  'attribute',
  'sort',
  'exactness',
  'trendingScore:desc', // Injected platform-wide ranking signal
  'indexedAt:desc'
];

The Lobby Integration

The frontend SvelteKit application utilizes the forYouFeed query inside the main /lobby route. The ForYouFeed.svelte component renders a dynamic, horizontally scrolling carousel of cards.

Cards in this feed are visually enhanced with dynamic badging — displaying the item's precise trending score (e.g., "🔥 42") and the Malet's handle (e.g., m|luminara). This visual feedback reinforces the "Virtual Mall" culture, allowing Visitors to immediately understand why an item is being recommended to them.

Cross-Service Data Flow

┌──────────────┐     trending_scores_updated     ┌──────────────┐
│  intelligence │ ─────────── TCP ──────────────▸ │    search     │
│  (Rust cron)  │                                 │  (NestJS)     │
└──────┬───────┘                                 └──────┬───────┘
       │ HTTP PUT /indexes/items/documents               │ forYouFeed query
       ▼                                                 ▼
┌──────────────┐                                 ┌──────────────┐
│  Meilisearch  │ ◂─── search query ────────────  │   Frontend    │
│  (items index)│                                 │  (SvelteKit)  │
└──────────────┘                                 └──────┬───────┘
                                                        │ followStore.getFollowedIds()
                                                        ▼
                                                 ┌──────────────┐
                                                 │    nodes      │
                                                 │  (Follow API) │
                                                 └──────────────┘