BlueShop Recommendation Domain — Implementation Plan (v4, semantic and measurement)

Status: PHASES 0-4 SHIPPED, DEPLOYED, AND LIVE-VALIDATED. Last updated: 2026-07-11. Research basis: 6 deep exploration reports (catalog, customer/order/cart behavior, stock/analytics/infra, storefront frontend, specs/BDD/e2e conventions, 2026 off-the-shelf recommender landscape). Phase 5 Gorse remains gated on sufficient real CTR evidence.

1. Executive summary

The recommendation bounded context is deployed as recommendation-service and serves product recommendations to the storefront at four placements: home page, cart page, order confirmation, and PDP similar products. It maintains event-fed projections from Kafka topics (order.orders, stock.stock-events, catalog.products) and computes recommendations with curated relations, count-based co-purchase, decayed popularity, client-provided seeds, and multilingual semantic similarity. One non-negotiable invariant remains: never recommend a product that is OUT_OF_STOCK or not PUBLISHED.

Build-vs-buy verdict (researched, §4): hybrid. The bounded context, domain rules, and serving API are ours regardless of engine. The scoring engine sits behind a domain port (RecommendationEngine):

• v1 (shipped): deterministic SQL/count-based strategies — zero new infra, Gherkin-provable, explainable.
• Phase 3 (deployed): semantic layer — pinned multilingual product embeddings (in-JVM ONNX inference, CPU) + pgvector cosine kNN → SIMILAR_CONTENT. It serves the cold-start customer (browsed but never ordered) and PDP similar-product placement (§5.9); live coverage is 3,860/3,860 eligible products.
• Phase 4 (deployed): no-PII RecommendationServed/RecommendationClicked CloudEvents via an RLS-protected outbox to recommendation.events, then item-grain ClickHouse facts and CTR by environment, traffic class, placement, strategy, and rank. LIVE, SYNTHETIC, and retained LEGACY traffic remain separate; dashboard 22 defaults to the LIVE baseline at /dashboards/recommendation-performance-ctr.
• Phase 5 (gated on CTR data): Gorse (Apache-2.0, active 2026, CPU-only, runs on our existing Postgres + idle Redis) for learned matrix-factorization personalization.

2. Current-state findings (what exists — verified in code)

3. Data sources → how each is exploited

Not used v1 (documented why): cart.events topic (funnel analytics grain, no removal events — cart context comes fresher from the client); customer loyalty/RFM (Phase 5 personalization features); review ratings (candidate quality boost — noted as backlog REC idea).

4. Build-vs-buy analysis (2026 state of the art, researched)

Why not Gorse first? (a) Acceptance criteria are Gherkin — deterministic heuristics are provable, a trained CF model is not. (b) The hard rules (OOS, PUBLISHED, exclusions, PII) must live in our domain layer anyway. (c) Zero extra pods now; Gorse costs ~1 CPU. (d) CF needs interaction volume we don't have yet; at demo scale it would underperform the heuristics. The port makes the swap cheap and A/B-testable when Phase-4 CTR data justifies it.

5. Algorithm & data pipeline design — the "how"

Direct answers: No trained-by-us model, ever — training is Gorse's job in Phase 5 if the CTR gate opens. No GPU (none exists). v1 is memory-based (count-based) collaborative filtering + decayed popularity + rule-based personalization — pure deterministic SQL over event-fed projections. Embeddings ARE in the plan and committed: Phase 3 adds a semantic layer (pretrained multilingual sentence-embedding model, ONNX inference in-JVM on CPU — inference only, no training) that powers SIMILAR_CONTENT and is the designed answer for the customer who has never ordered (§5.7, §5.9).

5.0 Three-layer pipeline

 Kafka (order.orders, stock.stock-events, catalog.products)
   │  streaming, idempotent (ADR-021 inbox, message_id = envelope id)
   ▼
 L1 INGESTION → immutable-ish FACTS + live projections
    order_product_facts | product_eligibility | curated_relations
   │  scheduled projector (15 min, config) + admin/BDD-triggerable recompute
   ▼
 L2 DERIVATION → precomputed SCORES (deterministic, fully rebuildable from facts)
   product_pair_affinity | product_popularity | customer_product_profile
   │  request-time, indexed lookups only, <10 ms target
   ▼
 L3 SERVING → strategy chain → eligibility filter → exclusions → RecommendationSet

Design principle: facts are the source of truth inside the context; every derived table is recomputable with RLS-safe DELETE + rebuild from facts, and facts are rebuildable from Kafka (earliest). This makes decay/damping parameters tunable without migration pain and gives a trivial disaster-recovery story (same property analytics relies on).

5.1 L1 — Ingestion (streaming consumers)

Deployment correction shipped after audit: recommendation-service initially parsed invented targetProductIds/targets fields and therefore projected zero curated relations. Backend MRs !844–!846 fixed event parsing, catalog bulk relation backfill, admin-triggered refresh, and 20-item refresh batches. Live proof: curated_relations=26,528, exactly matching catalog cross-sell + upsell counts, and seeded CART returns CURATED_RELATION first.

Order-status semantics (REC-006, corrected per remi): the storefront checkout actually creates orders at PAID (Order.createPaid), while backoffice/direct factories can create at CREATED — status enum is CREATED, PENDING_PAYMENT, PAID, PICKED, PROCESSING, SHIPPED, DELIVERED, CANCELLED. So the rule is count on first sight of any non-CANCELLED status (covers both real checkout PAID and backoffice CREATED), keyed by orderId so later status-change events for the same order don't double-count (PK ON CONFLICT DO NOTHING on order_product_facts), and remove from derivations when CANCELLED. PENDING_PAYMENT-stuck orders stay low-weight noise; acceptable v1.

5.2 L2 — CO_PURCHASE: item-item collaborative filtering (count-based)

Recomputed from non-cancelled facts:

• C(a,b) = number of distinct orders containing both a and b (pairs canonicalized a<b)
• C(a) = number of distinct orders containing a; N = total orders

Stored score (asymmetric cosine with bestseller damping):

score(a→b) = C(a,b) / ( C(a) · C(b)^α )        α = 0.5 (config)

• The C(b)^α denominator damps the "everything recommends the bestseller" failure mode of raw confidence C(a,b)/C(a).
• Noise floor: pairs kept only if C(a,b) ≥ minSupport (=2, config; =1 tolerated below bootstrapOrderCount so the demo dataset produces results — explicit config, not a hack).
• We also store raw co_order_count, confidence, lift = confidence / (C(b)/N) for explainability (reason: "Frequently bought with <seed>" + numbers in debug) and for reconciliation with ClickHouse ANL-016.
• Multi-seed aggregation (cart with k items): score(b) = Σ_seeds w_seed · score(seed→b), seeds equally weighted in CART, recency-weighted in HOME (§5.4). Normalized to 0..1 by the max in the candidate set.

Table: product_pair_affinity(product_a, product_b, co_order_count, score_a_to_b, score_b_to_a, computed_at) PK(product_a, product_b), index on each column for neighbor lookups.

5.3 L2 — POPULARITY: time-decayed best sellers

pop(p) = Σ over non-cancelled orders containing p:  exp( -λ · age_days(order) )
λ = ln 2 / 14      (14-day half-life, config)

• Exponential decay ⇒ "trending now", not "all-time bestseller"; an item that stops selling fades with a 14-day half-life.
• Recomputed by the projector (decay makes incremental maintenance pointless; full recompute over facts is milliseconds at our scale).
• Stored per product and per (product, category) so the personalization step can pull "popular within customer's favored categories".

Table: product_popularity(product_id PK, pop_score, category_id, orders_30d, units_30d, last_ordered_at, computed_at).

5.4 L2/L3 — PERSONAL_HISTORY: rule-based personalization (no model)

Server-side profile from customer_product_purchases + client seeds (recently-viewed ids):

1. Seed set = last K=10 purchased products, weight w = exp(-λ_p · days_since_purchase) (λ_p = ln2/30), plus recently-viewed seeds at a lower fixed weight (0.5, config) — a view is a weaker signal than a purchase.
2. Candidates = union of (a) affinity neighbors of every seed (§5.2), (b) top-popularity products in the customer's top-3 categories by purchase weight (§5.3 per-category).
3. Score = Σ_seeds w_seed · score(seed→cand) for (a); category-popularity normalized ×0.6 for (b) so behavioral affinity outranks demographic popularity.
4. Exclusions: REC-003 (seeds themselves), REC-004 (purchased within 30 days), then eligibility filter.

Deterministic, explainable (reason: "Because you bought <seed name>" / "Popular in <category>"), and — critically — every step is expressible as a Gherkin scenario.

5.5 L3 — Serving: strategy chains, blending, diversity

Per placement (REC-007):

Seeding gotcha (mude): the confirmation page today has no purchased product ids — PlaceOrderResponse only returns orderId/orderNumber/status, and the ReviewStep resets cart+checkout before navigating. So Phase 2 must add a durable seed source: capture the cart line-item ids before the reset and carry them into the confirmation route (router state / a short-lived signal), then pass them as CO_PURCHASE seeds. Fallback if unavailable: seed server-side from the customer's latest order_product_facts (already ingested), else PERSONAL_HISTORY → POPULARITY. Never block the confirmation page on it (REC-010). | PDP_SIMILAR (Phase 3) | SIMILAR_CONTENT → CO_PURCHASE → CURATED_RELATION → POPULARITY | current product |

5.5a Catalog-manager input is a first-class signal (explicit requirement): (1) CURATED_RELATION — the cross-sells/upsells that catalog managers author in backoffice-catalog are present in every seeded chain and outrank statistics when both propose the same slot (fixed score by sort_order, merchandiser intent wins). Today that data is heuristic seed — shipping this feature makes curating it actually pay off, which we surface to the catalog team. (2) Featured boost — products flagged is_featured by catalog managers get a configurable POPULARITY multiplier (×1.2 default) and are the preferred filler for anonymous HOME. product_eligibility snapshots is_featured from catalog re-fetches. Explainability preserved: reason: "Recommended by our team" for curated/featured picks (REC-012).

Blending = priority-fill (not weighted mixing): strategy #1's results (score-normalized 0..1) fill first; remaining slots filled by strategy #2 with scores compressed under the last #1 score; dedupe by productId keeping highest strategy. Simple, order-stable, explainable — every item's strategy field says where it came from. CURATED_RELATION items carry fixed score by sort_order — merchandiser intent beats statistics when both propose the same slot.

Diversity guard (REC-008 refinement): max 3 items per category in a strip of 8 (config) — prevents "8 pairs of socks" carts. Deterministic tiebreak: score desc, then productId asc.

Serving path: candidate lookups are indexed reads on precomputed tables + one eligibility join; target p95 < 30 ms server-side. Caffeine cache 60 s TTL keyed (placement, customerId|anon, hash(seeds), limit) — recommendations tolerate 60 s staleness except availability, which is re-filtered on every request against product_eligibility (so an OOS flip beats the cache, REC-011).

5.6 Consistency windows (explicit, testable)

5.7 Cold start & empty states

The cold-start ladder, by how much we know about the visitor:

• New product (no pairs, no sales): reachable via CURATED_RELATION (if merchandised), featured boost (if flagged), and SIMILAR_CONTENT (embedding exists from first catalog event — no interaction data needed). This closes product cold-start completely in Phase 3.
• Result < minResults (3, config): response returns what exists; the storefront hides the section entirely (REC-010) — no half-empty strips; recommendations never delay or break a page (independent httpResource).

5.8 Evaluation methodology

• Offline/CI: golden-dataset BDD scenarios (seeded orders → exact expected outputs — possible because v1 is deterministic); reconciliation test: our co_order_count vs ClickHouse analytics.basket_product_affinity on identical event sets.
• Live data-quality gate (per deploy): coverage % (eligible products reachable by ≥1 strategy), zero OOS/unpublished items sampled from real responses.
• Online (Phase 4): RecommendationServed/RecommendationClicked events (outbox → recommendation.events → analytics → ClickHouse) ⇒ CTR per placement/strategy in Metabase. This is the Phase-5 gate: Gorse gets adopted only if heuristic CTR plateaus at meaningful traffic.

5.9 Semantic layer (Phase 3, committed) — embeddings design

Problem it solves: a customer who browsed but never ordered gets nothing personal from counting-CF; a brand-new product is invisible to statistics. Both need content understanding, not interaction counts.

Model (inference only, never trained by us): a pretrained multilingual sentence-embedding model — candidate: paraphrase-multilingual-MiniLM-L12-v2 (384-d, supports de/fr/it/en, permissive license). Runs inside recommendation-service via ONNX Runtime + DJL on CPU. VERIFIED (sage): DJL 0.36.0 + ONNX Runtime 1.21.1 are Java 25 compatible; the ORT jar and DJL tokenizers both ship linux-aarch64 natives. CRITICAL: those natives are glibc, but the BlueShop backend Dockerfile is Alpine/musl → recommendation-service must use a glibc Temurin Java 25 base image (deviation from the standard backend image — called out in Phase 3.1 / infra). Use the ~118 MB quantized arm64 ONNX model (not the 470 MB full one) to fit the 1Gi pod limit — steady RSS is feasible but tight, monitor. Bake the pinned model + tokenizer bundle into the service image for v1 (no runtime internet); Harbor OCI artifact is an optional later decoupling. Embedding the full catalog (thousands of items) is seconds; no GPU, no Python service, no external API.

What gets embedded (per product, on catalog events): one composed text per product — name(4 locales) + category name + brand + description(primary locale) + salient attributes → one 384-d vector, L2-normalized. (Note per remi: full category path names live only in the internal ES search document, not in ProductResponse; v1 embedding uses the single category name from the re-fetched detail, or projects categories separately if path context proves valuable.) Re-embedded on ProductUpdated/AttributesUpdated re-fetch (same L1 flow, §5.1); embedded at first ProductCreated — which is exactly why product cold-start closes: the vector exists before the first sale.

Storage & query — pgvector preferred, ES fallback (VERIFIED by sage research 2026-07-08, brief worktrees/reco-research/sage-semantic-feasibility.md):

• Preferred: pgvector in our own recommendation schema (product_embedding(product_id PK, embedding vector(384), embedded_at), HNSW index, cosine <=>). Keeps vector load OFF the tightly-sized shared ES; kNN over thousands of rows is trivial; joins directly with product_eligibility in one query (eligibility filter inside the kNN query — elegant REC-001/002 enforcement). CONFIRMED available: CNPG image harbor.blueshop.local/ghcr/cloudnative-pg/postgresql:17 is built on the standard image family that bundles pgvector. CRITICAL CONSTRAINT: CREATE EXTENSION vector must be admin/GitOps-managed, NOT service Flyway — pgvector is not a trusted extension and recommendation-service's DB role is non-superuser. So: a GitOps/admin bootstrap enables the extension once; the service's Flyway only creates the product_embedding table (assuming the type exists). Custom Postgres image only needed if a system/standard tag or CNPG extension-image path is blocked (low/medium effort, no sidecar).
• Fallback: ES dense_vector + kNN (VERIFIED: ES 8.17.0, free Basic tier supports dense_vector + kNN/BYO vectors). Downside: shared single-node ES has only 512Mi heap — pgvector wins on isolation and eligibility joins.

SIMILAR_CONTENT scoring: for seed set S (viewed/cart/current product), candidate score = max_{s∈S} cos(v_s, v_c) (max, not mean — preserves niche interests instead of averaging them into mush), recency-weighted by seed age like §5.4. Threshold cos ≥ 0.55 (config) to avoid nonsense matches; deterministic given fixed vectors ⇒ still Gherkin-testable with a frozen test model + golden fixtures.

Why this is Phase 3 and not v1: v1 ships value immediately with zero new moving parts; the semantic layer adds a model artifact, an inference runtime, and a vector store — worth doing (committed, it completes cold-start), but not worth blocking first delivery. ES More-Like-This can be wired in days as an interim content signal if Phase 2 feedback demands it before the embedding work lands.

6. Bounded context design (DDD)

Ubiquitous language: Placement · RecommendationQuery (placement + seeds + customer + limit) · Recommendation (productId, score 0..1, reason, strategy) · RecommendationSet (ordered, deduped, filtered) · Strategy (CO_PURCHASE, POPULARITY, PERSONAL_HISTORY, CURATED_RELATION, SIMILAR_CONTENT) · Eligibility (PUBLISHED ∧ ¬OUT_OF_STOCK) · Seed · FallbackChain · Projector.

com.blueshop.recommendation/
├── api/            RecommendationController + request/response DTOs
├── application/
│   ├── service/    DefaultRecommendationApplicationService   # chain orchestration + filters + cache
│   ├── port/       RecommendationEngine                      # THE swap point (Heuristic v1 → Gorse P5)
│   └── client/     CatalogProductClient (interface)
├── domain/
│   ├── model/vo/   Placement, Recommendation, RecommendationSet, Strategy, Seed, Eligibility, AffinityScore
│   ├── service/    EligibilityPolicy (REC-001/002), ExclusionPolicy (REC-003/004),
│   │               FallbackChain (REC-007), DiversityPolicy (REC-008)
│   └── repository/ EligibilityRepository, AffinityRepository, PopularityRepository,
│                   CustomerPurchaseRepository, CuratedRelationRepository, OrderFactRepository
└── infrastructure/
    ├── persistence/  R2DBC entities + repos (schema `recommendation`, RLS service context)
    ├── event/        OrderEventConsumer, StockAvailabilityConsumer, CatalogProductConsumer,
    │                 inbox (common-lib IdempotentConsumer), [Phase 4: outbox relay]
    ├── projection/   AffinityProjector, PopularityProjector (scheduled + admin/BDD trigger endpoint)
    ├── engine/       HeuristicRecommendationEngine   [P3: +ElasticsearchMltClient] [P5: GorseRecommendationEngine]
    ├── client/       HttpCatalogProductClient (WebClient + Resilience4j)
    └── config/ security/

JMolecules annotations, @NullMarked, records for VOs/DTOs, Mono/Flux only, no .block(), ArchUnit enforcing layer boundaries (copy catalog's rules).

Flyway (schema recommendation): V1 baseline + RLS, V2 order_product_facts + customer_product_purchases, V3 product_eligibility + curated_relations, V4 product_pair_affinity + product_popularity, V5 inbox_events, (P4) V6 outbox_events. All tables service-only RLS (no customer-facing rows here; responses expose no PII — REC-009).

Serving API (gateway route /api/recommendation/**):

GET /v1/recommendations?placement=HOME|CART|ORDER_CONFIRMATION
                       &seedProductIds=<uuid,...>   (optional, ≤ 20)
                       &limit=8                     (server-capped at 12, REC-008)
Auth: permitAll; valid JWT ⇒ personalized (customerId = sub); anonymous ⇒ non-personalized (REC-005).
200: { "placement": "CART",
       "items": [ { "productId": "…", "score": 0.87,
                    "strategy": "CO_PURCHASE",
                    "reason": "Frequently bought together" } ],
       "generatedAt": "…" }
400: invalid placement / malformed seeds.  Never 5xx for empty data — empty list is a valid answer.
POST /internal/v1/recommendations/recompute   (service/admin only; catalog refresh + projector trigger for ops + BDD)

Response is ids + scores only; storefront hydration uses existing catalog bulk endpoint GET /v1/products/bulk?productIds=a,b,c (permitAll, staff-aware filtering).

7. Business rules (REC catalog — authored in docs at Phase 0)

8. Systemic impact / blast radius

New, additive:

• backend/services/recommendation-service — new Gradle module (settings.gradle.kts, CI build job build-recommendation, ci/required-backend-images.list, aggregate bddTest filter at backend/build.gradle.kts:1013-1019, PIT matrix entry per harness conventions MR !825).
• api-gateway: route /api/recommendation/** (config-only).
• Infra (GitOps, one MR): overlay overlays/dev/recommendation/ (kustomization, resources, db-credentials, kafka-credentials patches), ApplicationSet entry, Vault DB role recommendation-svc + k8s auth role, Keycloak Kafka OIDC client recommendation_service, Kafka ACLs Read/Describe on order.orders, stock.stock-events, catalog.products + group recommendation-service (+ Write recommendation.events in P4), Harbor repo, ExternalSecrets. Start replicas: 1 (analytics precedent), 100m/512Mi → 500m/1Gi.
• Frontend (storefront only): RECOMMENDATION_API_URL token; recommendations.store.ts (signalStore + httpResource; personalized resource returns undefined during SSR — Keycloak is browser-only — and activates post-init, exactly the RecentlyViewedStore pattern; anonymous HOME variant SSR-renders); one reusable <app-recommended-products> strip (reuses ProductDetailProductCardComponent); mounted in home.component.html, cart.component.html, order-confirmation.component.html; Transloco keys ×4 locales; replaces the disabled EngagementStore.recommendations stub.
• One deliberate catalog touch: bulk GET /v1/products?ids= + (separate MR) ProductLookupStore refactor to use it.
• Docs/specs/e2e: business rules page, events page + index entry, ADR-024, recommendation.spec.yaml + Makefile line, e2e specs + demo batch entry.

Explicitly untouched: stock/order/cart services (pure topic consumption, zero producer changes); catalog campaign RecommendationsController; checkout stepper UX (recommendations at cart entry + confirmation only — no mid-funnel distraction against the guarded stepper).

Risk register:

9. Testing strategy (TDD + BDD + quality gates)

10. Delivery plan — phases, MRs, dependencies

Every MR follows the full loop: implement → local green → push → CI green → deploy → live verify. Conventional commits, branch feat/recommendation-*.

Phase 0 — Specification first (completed)

Phase 1 — recommendation-service core (completed)

Phase 2 — Storefront placements (completed)

Phase 3 — Semantic layer (completed — cold-start and PDP, §5.9)

The interim Elasticsearch More-Like-This adapter was not built; pgvector shipped directly.

Phase 4 — Measurement loop (completed)

RLS outbox + recommendation.events (RecommendationServed/Clicked, no PII) → six-partition Kafka topic with 90-day retention and least-privilege ACLs → analytics consumer + ClickHouse item facts/CTR views → Metabase dashboard 22 → storefront navigation-safe click beacons. The server owns the deployment environment; normal traffic defaults to LIVE; Playwright and demo contexts emit SYNTHETIC; retained unclassified events remain LEGACY. Dashboard baseline cards filter to LIVE, so automation cannot satisfy the Gorse evidence gate. Live proof joined served items and a click by the same anonymous recommendation-set id, and the protected dashboard renders that CTR at https://bi.blueshop.local/dashboards/recommendation-performance-ctr.

Phase 5 — Engine upgrade (gated on Phase-4 CTR evidence)

GorseRecommendationEngine behind the port; gorse-in-one Helm (pinned), our Postgres + Redis; feed = same facts; A/B per placement. ADR-024 records the gate criteria: heuristic CTR plateau at meaningful traffic + catalog/order volume where MF outperforms counting.

Current gate result: closed. The current ClickHouse evidence is development/E2E traffic, not sustained customer traffic or a heuristic CTR plateau. It proves instrumentation, not that matrix factorization will outperform the deterministic baseline.

Dependency graph: 0.1 → 0.2 → (0.3) → 1.1 → 1.2 → {2.1, 2.2} → 2.3; 3, 4 independent after 2; 5 after 4.

11. E2E & demo scenarios

Permanent feature specs now shipped (storefront-recommendations.spec.ts, @type:feature @surface:storefront):

• REC-005: anonymous HOME returns visible cards and product navigation works.
• REC-015: seeded CART recommendations rank curated catalog-manager relations first.
• REC-003/REC-010: seeded recommendations exclude the seed and return only catalog PUBLISHED, non-archived, non-OUT_OF_STOCK products.
• REC-010: HOME hides the recommendation strip gracefully when the recommendation API returns 503.
• REC-016: PDP semantic results use SIMILAR_CONTENT, exclude the current product, render localized cards, navigate, and emit the click beacon.
• REC-016: an isolated authenticated zero-order customer receives HOME recommendations seeded by recently viewed products.
• REC-001/REC-002: isolated curated targets disappear after authoritative OOS and archive events while eligible fallback results remain.
• REC-007: an isolated customer completes checkout, sees different order-confirmation recommendations, emits a measured click, then receives PERSONAL_HISTORY HOME results excluding the purchase.
• REC-017: an analytics viewer opens the protected recommendation CTR dashboard and sees all four live cards.

Demo batch 9 — recommendation journey:

1. REC-007: narrated real checkout → order-confirmation strip → measured recommendation click → personalized HOME, with the purchased product absent.
2. REC-017: narrated protected BI route showing live overall CTR, CTR by placement/strategy, CTR by rank, and daily trend.
3. Dynamic REC-001/REC-002 stock/archive mutation remains a permanent acceptance scenario rather than being repeated in the narrated demo.

12. Decisions — closed by the plan (veto window, not questions)

All previously-open points are now decided with rationale. They ship as stated unless vetoed; each lists what would flip it.

The only thing awaited from the owner/team: veto or go. No open questions remain.