01 - Overview & architecture

Audience: Analysts & PMs
Related: Glossary · Pipeline

What Recomnext recommendations are

Recomnext is a Recommendations-as-a-Service layer. For a given tenant, it:

Stores a catalog of items (and optional users).
Ingests behavioral events (impressions + interactions).
Serves ranked item lists for placements (home “For You”, PDP similar, cart cross-sell, etc.) using a chosen logic and algorithm, shaped by a scenario.

You configure what a placement should do in Admin (scenarios). The site integrates via browser SDK / widgets (HMAC) or server SDKs.

Architecture (recommendations path)

What lives where

Store	Recommendation-relevant contents
MongoDB	Items (`externalId`, category, attributes, `available`), scenarios, shared rules, segmentations, tenant settings, ML user/item factors (`model_factors`)
ClickHouse	`interactions` (view/cart/purchase/rating), `impressions` (items shown in a placement)
Qdrant	Dense vectors for similar-products / hybrid vector legs (and beeFormer vectors when trained)
Kafka	Buffer between ingestion API and ClickHouse writers
Redis	Short-TTL caches (e.g. recommendation responses, some hybrid helpers)

Online vs offline

Mode	What happens	Who cares
Online (serving)	Request → resolve scenario → generate candidates → filter/boost/constrain → return items	Every placement request
Online (events)	SDK posts impressions/interactions → Kafka → ClickHouse	Funnel metrics + behavioral algos
Offline (indexing)	Catalog text → embeddings service → Qdrant upsert	`vector-similarity` quality
Offline (training)	Export CH + catalog → train ELSA/ReALM/beeFormer → write factors/vectors	ML algorithm scenarios

Behavioral algorithms (weighted-history, co-occurrence, …) read ClickHouse directly at request time (typically last 30 days). ML algorithms read precomputed factors from Mongo/Qdrant.

Request high-level sequence

Details: 04 - Request pipeline.

Event high-level sequence

Details: 03 - Events.

Tenants & environments

Each request is scoped by tenant (X-Tenant-Id / HMAC token tenant).
Catalog, scenarios, and events do not mix across tenants.
Dev examples in this pack use driffle-dev.

What this architecture implies for analysts

Changing a scenario (Admin) changes online ranking immediately for that slug - no redeploy.
Changing event instrumentation on the site changes ClickHouse tomorrow’s metrics and behavioral model inputs.
Training / reindex lag affects ELSA / ReALM / beeFormer / vector quality even if scenarios are perfect.
Analytics ≠ ranking input 1:1. CTR uses impressions + type=view with slug; weighted-history uses all interaction types for a user (with type multipliers), usually ignoring empty slug.