Standalone Guides

Recommendations deep-dive for data analysts and PMs who configure scenarios. Dev / VPN proxy / localhost only.

Recomnext Recommendations - Guide for Data Analysts & Growth / PMs

Audience: Data analysts (SQL + Admin UI) and PMs / growth who configure scenarios.
Scope: Recommendations only (Search v2 is out of scope).
Date: 2026-07-23
Examples: Live aggregates from tenant driffle-dev (dev ClickHouse) where noted.

Web (dev only): served at /resources/standalone-guides on localhost, dev.recomnext.com, and landing.proxy.vpn.recomnext.com (hidden on production marketing hosts). Canonical git copies also live in docs/standalone-docs/.

This pack explains how Recomnext generates recommendations, how events and weights work, how scenarios / filters / boosters / constraints reshape results, and how to interpret analytics correctly.

How to use this pack

If you need…	Start here
Big picture & data stores	01 - Overview & architecture
Shared vocabulary	02 - Glossary
Events, weights, CTR	03 - Events, weights & analytics
What happens on each request	04 - Request pipeline & scenarios
Logic × algorithm deep dives	05 - Logic types & algorithms
ELSA / ReALM / beeFormer	06 - ML models & training
Numbers & formulas	07 - Worked examples
Day-to-day ops	08 - Analyst & PM playbook
Why CTR can exceed 100%	09 - Case study: Driffle attribution
SQL / API cheat sheets	10 - Appendices

One-page mental model

Placements call a scenario (or a logic type).
The scenario picks a logic + algorithm, plus filters / boosters / constraints.
The algorithm builds a candidate list from ClickHouse, Mongo, Qdrant, and/or ML factors.
Post-processing applies nextQL filters → boosters → diversity / freshness / long-tail → optional purchase cap → min/max fill.
Separately, the site sends impressions (items shown) and interactions (view / cart / purchase / rating). Analytics joins them by scenario_slug.

Logic × algorithm map (recommendations)

Logic (placement intent)	Default algorithm	Other selectable algorithms
`user-to-item`	`weighted-history`	`elsa-cf`, `realm-sequential`
`item-to-item`	`co-occurrence`	`elsa-cf`
`items-to-items` (e.g. cart)	`multi-seed-co-occurrence`	`multi-seed-hybrid`
`similar-products` (e.g. PDP)	`vector-similarity`	`beeformer-multimodal`
`recently-viewed`	`recency`	-

Search logics (hybrid-search, etc.) exist in the registry but are not covered in this pack.

Critical analytics caveat (read early)

In Admin scenario analytics, “clicks” are interactions with type = 'view' and a matching scenario_slug - not a dedicated click event, and not necessarily “user clicked a card in the rail.”

CTR is:

CTR% = 100 × count(interactions WHERE type='view' AND scenario_slug=X)
             / count(impressions WHERE scenario_slug=X)

Numerator and denominator are independent event streams. Wrong integration can push CTR above 100%. See 09 - Driffle case study.