Discovery Platform Low-Level Design

This document is the implementation companion to Discovery platform architecture. Compass owns policy and request construction. TypeSense executes primary retrieval and ranking.

Runtime Contract

Client -> Compass
  -> normalize + understand query
  -> select profile/rules/eligibility
  -> compile TypeSense request
  -> TypeSense retrieves, filters, groups, facets, ranks, pins/hides
  -> Compass validates final safety/external constraints
  -> response + signed discovery context + operational evidence

Compass never reimplements primary search ranking in application code. It may apply a narrow final rerank only for data TypeSense cannot safely know at query time, such as pincode delivery or future seller-offer selection.

Discovery Product Document

Index one canonical product family, not one document per SKU/size variant.

type DiscoveryProduct = {
  id: string;
  sourceProductId: string;
  sourceVersion: string;
  productFamilyId: string;
  title: string;
  brandId: string;
  brandName: string;
  categoryIds: string[];
  categoryNames: string[];
  concernIds: string[];
  concernNames: string[];
  ingredientIds: string[];
  ingredientNames: string[];
  productType: string;
  routineStep?: string;
  formats: string[];
  skinHairTypes: string[];
  spf?: number;
  ingredientStrengths: Array<{ ingredientId: string; percentage?: number }>;
  searchableDescription: string;

  listable: boolean;
  purchasable: boolean;
  inStock: boolean;
  rxClassification: "none" | "prescription" | "consult_required";
  priceMinimum: number;
  rating?: number;
  searchPopularityScore?: number;

  displayVariants: Array<{
    variantId: string;
    label: string;
    price: number;
    inStock: boolean;
    attributes: Record<string, string | number | boolean>;
  }>;
  defaultDisplayVariantId: string;
  imageUrl: string;
  productUrl: string;
  updatedAt: string;
};

Index title, brand, category, concern, ingredient, product type, format, controlled description, facets, numeric values, and ranking fields. Leave display-only data unindexed. Price, stock, listability, and Rx state are separate fields.

Query Understanding

Pipeline

raw query
  -> Unicode/whitespace/case normalization
  -> protected-term recognition
  -> approved synonym and Hinglish alias matching
  -> numeric/attribute extraction
  -> intent classification
  -> query plan
  -> TypeSense request compilation

Use deterministic controlled dictionaries and parsers first. Do not begin with an LLM classifier.

vit c                   -> approved alias vitamin_c
SPF 50                  -> spf >= 50
under 500               -> priceMinimum <= 500
for oily skin           -> skinHairTypes contains oily
muhase                  -> concern acne
jhaiyan                 -> concern pigmentation

Protected brands, product families, and molecules are recognized before typo/rewrite behavior and must never be rewritten into generic words.

Intent signals

Intent	Evidence
Product/family	Exact or near-exact title/family match
Brand	Brand dictionary/protected-term match
Category	Category/product-type dictionary match
Concern	Concern dictionary or approved alias
Ingredient	Ingredient dictionary or approved alias
Combination	Multiple canonical entities or structured attributes
Natural language	No strong structured match and descriptive query form

Ambiguous queries may retain multiple candidates. Log confidence and evidence in the Compass explain record.

Numeric extraction

Use typed parser rules, not text search, for explicit values.

Input	Query-plan expression
`spf 50`, `spf 50+`, `minimum spf 50`	`spf >= 50`
`spf above 50`, `spf over 50`	`spf > 50`
`spf under 50`	`spf < 50`
`under 700`, `below 700`	`priceMinimum <= 700` or `< 700` by phrase
`between 500 and 1000`	`500 <= priceMinimum <= 1000`
`10% niacinamide`	ingredient `niacinamide`, strength `10`
`around 700`	ranking preference, not hard filter

Only high-confidence explicit values become hard filters. Ambiguous values, such as light sunscreen, become controlled ranking preferences or later hybrid-search signals.

Query-plan type

type QueryPlan = {
  rawQuery: string;
  normalizedQuery: string;
  intent: { primary: string; confidence: number; evidence: string[] };
  entities: {
    productFamilyIds?: string[];
    brandIds?: string[];
    categoryIds?: string[];
    concernIds?: string[];
    ingredientIds?: string[];
    productTypeIds?: string[];
  };
  filters: Array<{ field: string; operator: string; value: unknown; confidence: number }>;
  rankingPreferences: Array<{ field: string; values: unknown[]; weight: number }>;
  profile: string;
  retrievalMode: "lexical" | "hybrid";
};

For spf above 50 sunscreen for oily skin under 700, Compass creates:

{
  "intent": { "primary": "category", "confidence": 0.96 },
  "entities": { "categoryIds": ["sunscreen"] },
  "filters": [
    { "field": "spf", "operator": ">", "value": 50, "confidence": 0.99 },
    { "field": "skinHairTypes", "operator": "contains", "value": "oily", "confidence": 0.98 },
    { "field": "priceMinimum", "operator": "<=", "value": 700, "confidence": 0.99 }
  ],
  "profile": "sunscreen-search-v1",
  "retrievalMode": "lexical"
}

TypeSense Request Compilation and Ranking

Compass loads the ranking profile and matching active rules, then compiles TypeSense parameters. TypeSense performs the actual relevance score, filtering, grouping, sorting, curation, and pagination.

q=sunscreen
query_by=title,brand_name,category_names,concern_names,ingredient_names,product_type,searchable_description
query_by_weights=10,9,7,7,7,6,2
filter_by=listable:=true && purchasable:=true && spf:>50 && skin_hair_types:=[oily] && price_min:<=700
facet_by=brand_name,formats,skin_hair_types,spf,price_min
group_by=product_family_id
sort_by=_text_match:desc,rating:desc,search_popularity_score:desc
pinned_hits=product_123:1
hidden_hits=product_999

Ranking precedence

Eligibility and safety filters
TypeSense lexical/vector relevance
Bounded behavioral and declared business signals
Merchandising boost/bury adjustment
Pins
Compass final defensive validation

Compass profiles are governed configuration. TypeSense executes them. A profile defines searchable fields/weights, allowed sorts, out-of-stock policy, ranking signals, and lexical/hybrid mode. Use native TypeSense controls first:

Requirement	Preferred execution
Exact pin	Override or `pinned_hits`
Exact hide	Override or `hidden_hits`
Synonym	TypeSense synonym synchronized from Compass approval
Field relevance	`query_by`, weights, TypeSense ranking
Structured filter	`filter_by`
Facets	`facet_by`
Group product families	`group_by`
Simple boost/bury	TypeSense ranking/evaluation parameter
Complex external-context boost/bury	Bounded Compass rerank after over-fetch

Eligibility and Final Validation

Push broad filters into TypeSense, then revalidate in Compass.

function isEligible(product: DiscoveryProduct, context: DiscoveryContext): EligibilityDecision {
  if (!product.listable) return { eligible: false, reason: "not_listable" };
  if (!product.purchasable) return { eligible: false, reason: "not_purchasable" };
  if (context.widget && product.rxClassification !== "none") {
    return { eligible: false, reason: "rx_excluded_from_widget" };
  }
  if (context.promotion && product.rxClassification !== "none") {
    return { eligible: false, reason: "rx_excluded_from_promotion" };
  }
  if (context.excludeOutOfStock && !product.inStock) {
    return { eligible: false, reason: "out_of_stock" };
  }
  return { eligible: true };
}

No pin, override, experiment, campaign, or TypeSense parameter can resurrect an ineligible item.

Core Surface Designs

The following sections are the implementation contracts for the four core discovery surfaces. They use one canonical product collection and one shared eligibility/ranking policy; they do not create separate product indexes per page type.

Search

Search API contract

POST /v1/discovery/search

{
  "query": "spf above 50 sunscreen for oily skin under 700",
  "surface": "search_results",
  "platform": "web",
  "filters": {
    "brandIds": ["brand_example"],
    "formats": ["gel"]
  },
  "sort": "featured",
  "page": 1,
  "pageSize": 24,
  "anonymousId": "anon_...",
  "sessionId": "ses_...",
  "userId": null,
  "location": null
}

Compass validates page bounds, allowed filter fields/values, sort, platform, session identity, and request size before query understanding begins. The client never sends TypeSense query parameters directly.

Search execution sequence

Generate request_id and search_id.
Load active immutable configuration snapshot from Redis:
   protected terms, aliases, ranking profiles, active rules, redirects, flags.
Normalize query and build a QueryPlan.
Check redirect and medical/Rx policy before product retrieval.
Select search profile, required fields, filters, facets, sort, and rules.
Compile one TypeSense search request.
TypeSense retrieves/ranks/groups/facets/paginates products.
Compass validates returned product eligibility and external constraints.
If too few eligible visible results remain, over-fetch the next candidate window only when required.
Apply fallback ladder when the result quality threshold is not met.
Select display variants, badges, context tokens, applied filter chips, and response metadata.
Persist explain evidence; emit PostHog search exposure; let TypeSense auto-capture native search analytics.
Return response.

search_id identifies the exact returned list. The explain record stores the raw query, normalized query, QueryPlan, TypeSense request, active rule/profile/configuration versions, candidate exclusions, result positions, fallback step, provider, and latency.

Search profiles

Profiles are stored in Compass and compiled to TypeSense request parameters. They are not code branches.

{
  "name": "search-default",
  "version": 1,
  "retrievalMode": "lexical",
  "queryBy": [
    "title",
    "brandName",
    "categoryNames",
    "concernNames",
    "ingredientNames",
    "productType",
    "searchableDescription"
  ],
  "queryByWeights": [10, 9, 7, 7, 7, 6, 2],
  "defaultSort": "featured",
  "allowedSorts": ["featured", "price_asc", "price_desc", "newest", "rating"],
  "outOfStockPolicy": "exclude",
  "behavioralInfluenceCap": 0,
  "semanticPolicy": "off"
}

Examples of profile selection:

Query/surface	Profile	Notes
Exact product/family	`product-exact`	Title/family/brand lexical dominance; hybrid off.
Brand	`brand-faithful`	Exact brand match/filter; brand PLP redirect permitted.
Generic search	`search-default`	General lexical relevance and allowed facets.
Concern	`concern-discovery`	Concern/category/ingredient emphasis.
Natural-language need	`search-hybrid` later	Only for approved query groups after offline/shadow validation.

Filters, sorting, grouping, and pagination

Compass always adds mandatory filters, then adds explicit user filters and high-confidence extracted filters.

Mandatory:
listable:=true && purchasable:=true

Surface policy:
inStock:=true when the surface excludes out of stock
rxClassification:=none for promotion/recommendation contexts

Query-plan filters:
spf:>50 && skinHairTypes:=[oily] && priceMinimum:<=700

User filters:
brandId:=[brand_example] && formats:=[gel]

Product-family grouping is mandatory for search and browse. The product document is the canonical family; displayVariants provides the price/variant shown on the card. Pagination always occurs after TypeSense grouping. A filter or sort change resets to page one server-side. Sort semantics:

Sort	TypeSense execution
`featured`	Active Compass profile plus valid business/rule adjustments and pins.
`price_asc` / `price_desc`	Product family selected display price with eligibility policy.
`newest`	`launchedAtTimestamp`.
`rating`	Rating plus review-count threshold guardrail where configured.

Search fallback ladder

Fallback is explicit and measured. It is not a hidden retry loop.

Primary QueryPlan
  -> typo-safe lexical plan
  -> relax low-confidence ranking preferences/modifiers
  -> hybrid plan only when enabled and medically safe
  -> closest governed category/concern destination with honest copy
  -> explicit zero-result state

Medical/Rx and deliberately out-of-scope terms bypass generic semantic alternatives and follow consultation/clinical or honest out-of-scope policy. Each response carries fallback.step; PostHog records it. TypeSense nohits_queries tracks raw engine no-hit demand, which is distinct from a fallback-rescued user result.

Search failure behavior

Failure	Behavior
TypeSense timeout/5xx during migration	Serve Netcore when `typesense_with_netcore_fallback` is active; record fallback.
TypeSense timeout after migration	Safe cached/category fallback where eligibility remains valid; never a blank screen.
Redis config cache unavailable	Read last valid/versioned configuration from PostgreSQL at protected rate.
Query parser failure	Run a conservative raw lexical search with mandatory safety filters; record parser error.
Invalid/unknown filter	Reject with client validation error; do not pass arbitrary filter syntax to TypeSense.

Search measurement

Required PostHog properties for search_executed include search_id, raw/normalized query under access policy, intent, extracted entities/filters, profile/version, configuration version, provider, results and positions, result count, fallback, latency, platform, and surface. Track zero result, fallback rescue, reformulation, search-to-PDP, search-to-cart, search-to-order, latency, rule exposure, and index freshness. Compare these against Netcore during migration.

Autosuggest

Design principle

Autosuggest is a grouped router, not a smaller flat search-results page. TypeSense identifies matching candidates and maintains native popular-query data. Compass determines group, destination, privacy/safety, curation, and final suggestion quality.

Collections

Use one main product collection and small entity collections. Do not create a separate product collection for every suggestion type.

discovery_products_v1
discovery_brands_v1
discovery_categories_v1
discovery_concerns_v1
discovery_ingredients_v1
analytics_popular_queries_v1
analytics_nohits_queries_v1

analytics_popular_queries_v1 is a normal TypeSense destination collection populated by its popular_queries native analytics rule. It is the popular-query source; no separate leaderboard service is required.

Suggest API contract

POST /v1/discovery/suggest

{
  "prefix": "sun",
  "surface": "search_box",
  "platform": "web",
  "anonymousId": "anon_...",
  "sessionId": "ses_...",
  "limit": 8
}

The client debounces 150-250ms, cancels an older request when a newer prefix exists, and does not call suggest for a stale input value. Compass uses a stricter latency budget than full search.

Suggest execution sequence

Validate prefix length and request context.
Normalize/protect terms and match approved aliases, including Hinglish.
For a non-empty prefix, issue TypeSense multi_search over products, entities, and popular queries.
Attach candidate type/source/rank and apply eligibility to product candidates.
Apply Compass blocked, pinned, curated, privacy, and quality policies.
Deduplicate labels/destinations and choose a final group order.
Return grouped suggestions with stable suggestion IDs and destinations.

Group order is deterministic:

Exact product family
Exact brand
Exact category, concern, ingredient
High-quality product candidates
Approved popular queries
Curated campaign shortcuts

An exact Acne UV product family must outrank a broad Acne concern. A popular query never bypasses safety or quality gates.

Suggest response contract

{
  "requestId": "req_...",
  "prefix": "sun",
  "groups": [
    {
      "type": "category",
      "items": [{
        "suggestionId": "sug_...",
        "label": "Sunscreen",
        "destination": { "type": "plp", "slug": "sunscreen" },
        "rank": 1,
        "source": "category_entity"
      }]
    },
    {
      "type": "product",
      "items": [{
        "suggestionId": "sug_...",
        "productId": "product_123",
        "label": "Sunscreen SPF 50 Gel",
        "price": 599,
        "imageUrl": "...",
        "destination": { "type": "pdp", "productId": "product_123" },
        "rank": 1,
        "source": "product_prefix"
      }]
    },
    {
      "type": "query",
      "items": [{
        "suggestionId": "sug_...",
        "label": "Sunscreen for oily skin",
        "destination": { "type": "search", "query": "sunscreen for oily skin" },
        "rank": 1,
        "source": "typesense_popular_query"
      }]
    }
  ]
}

Popular query quality gate

Before a TypeSense popular query is displayed, Compass checks:

It is not a prescription, medical, sensitive, abusive, or blocked phrase.
It has an acceptable recent successful-result rate and availability profile.
It is not a near duplicate of an existing entity/product suggestion.
It is not expired/blocked by a merchandising or compliance rule.
It has enough recent traffic according to the configured threshold.

TypeSense handles popularity aggregation and prefix matching; Compass decides whether a popular query is eligible to surface.

Empty-prefix suggestions

For an empty prefix, do not run normal entity multi-search. Return, in policy order:

Privacy-safe recent searches from session/client state
Approved trending TypeSense popular queries
Curated seasonal/campaign shortcuts
Optional category/concern shortcuts

Prescription and sensitive health searches never reappear in a shared/recent surface without explicit privacy approval.

Suggest analytics

The client sends visible suggestion impressions only after the dropdown is visible. Suggestion clicks include suggestion_id, group/type, rank, source, prefix, destination, session, and resulting search/page context. suggestion_shown and suggestion_clicked go to PostHog; native TypeSense analytics continues to aggregate actual search submissions rather than every keystroke.

Browse and PLP

Page definition

Browse pages are query templates over discovery_products_v1, not separate product indices.

type PageDefinition = {
  id: string;
  slug: string;
  pageType: "category" | "brand" | "concern" | "ingredient" | "campaign" | "combination";
  title: string;
  description?: string;
  inclusionFilter: StructuredProductFilter;
  rankingProfileId: string;
  filterConfigurationId: string;
  allowedSorts: string[];
  contentSlots: ContentSlotDefinition[];
  seo: { canonicalUrl: string; indexPolicy: "index" | "noindex"; redirectsFrom: string[] };
};

Examples:

/category/sunscreen
  inclusion: categoryIds contains sunscreen
  profile: category-sunscreen
  facets: brand, SPF, format, skin type, price

/brand/cetaphil
  inclusion: brandId equals cetaphil
  profile: brand-faithful

/concerns/acne
  inclusion: concernIds contains acne
  profile: concern-discovery

Browse request flow

Client requests page slug plus user filters/sort/page.
Compass/Tetris resolves PageDefinition and active page rules.
Compass validates requested filters/sort against FilterConfiguration.
Compass compiles q=* or a page-scoped query with:
   page inclusion filter + mandatory eligibility + user filters + profile sort + native pins/hides.
TypeSense retrieves, groups, facets, sorts, and paginates.
Compass applies final eligibility/external constraints and emits page evidence.
Tetris adds CMS slots, banners, guides, consultation module, and badges.

Filter configuration

type FilterConfiguration = {
  id: string;
  pageType?: string;
  pageId?: string;
  facets: Array<{
    field: string;
    label: string;
    order: number;
    searchable: boolean;
    selectionMode: "multi_or" | "single";
    pinnedValues?: string[];
  }>;
  quickFilters: Array<{
    label: string;
    filter: StructuredProductFilter;
    order: number;
    startsAt?: string;
    endsAt?: string;
  }>;
  allowedSorts: string[];
};

Filter semantics are fixed:

multiple values inside one facet: OR
values across separate facets: AND
filter/sort change: reset to page 1
applied filters: returned as removable chips
high-cardinality facet: TypeSense prefix search over entity collection or facet-value endpoint

Compass rejects unsupported filters rather than allowing arbitrary filter_by expressions from clients. Empty-filter states return clear removal/relaxation choices; they never silently change user filters.

Browse merchandising and content

Page-level rules use the same control plane as search:

Pins/hides compile to TypeSense overrides or request-time controls.
Simple boosts/buries compile to profile/evaluation parameters.
Content slots are resolved by Tetris/CMS after product retrieval.
Card badges derive from controlled product flags and Compass rules; badge priority/max count is configuration.

Do not put banners or CMS content in TypeSense documents. TypeSense returns product data; Tetris owns content composition.

Browse SEO and events

Stable page IDs and canonical URLs are independent of display names. Renames preserve redirects. Filtered URLs receive explicit index/noindex policy. PostHog plp_viewed records page ID/type, products/positions, profile/config version, active filters, sort, and content-slot IDs. Client events record visible cards, filter/sort changes, content interactions, and PDP clicks.

Recommendations

Design boundary

Recommendations use a pipeline, not generic “similar products” search. TypeSense can retrieve attribute-compatible candidates, but Compass applies the strategy, routine logic, safety, exclusions, overrides, fallback, and measurement.

Widget request
  -> Compass loads strategy for widget + surface
  -> candidate sources
  -> universal eligibility/Rx filters
  -> widget/routine constraints
  -> TypeSense candidate retrieval/ranking where applicable
  -> Compass pins/hides/fallback
  -> Tetris render + event context

POST /v1/discovery/widgets/{widgetKey}

{
  "widgetKey": "best_used_with",
  "surface": "pdp",
  "anchor": { "productId": "product_123", "variantId": "variant_123" },
  "sessionId": "ses_...",
  "userId": null,
  "limit": 6
}

Strategy configuration

type WidgetStrategy = {
  id: string;
  widgetKey: string;
  surface: string;
  candidateSources: Array<"curated" | "relationships" | "co_purchase" | "typesense_similarity" | "trending">;
  fallbackOrder: string[];
  rankingProfileId?: string;
  hardExclusions: {
    excludeRx: boolean;
    excludeOutOfStock: boolean;
    excludeAnchor: boolean;
    excludedCategories?: string[];
  };
  routinePolicy?: "none" | "complementary_steps" | "no_conflicts";
  version: number;
};

Candidate source order should begin with deterministic sources:

Curated lists
Catalogue relationship data
Attribute-based TypeSense candidates
Co-purchase data after attribution quality is proven
Model candidates only after offline quality review
Category/concern trending fallback

An LLM is never the primary product recommender.

TypeSense recommendation retrieval

For attribute-based similarity, Compass builds a constrained TypeSense query from the anchor product:

Anchor: niacinamide serum for acne

Candidate query:
filter_by=
  listable:=true && purchasable:=true && inStock:=true &&
  id:!=anchor_product &&
  concernIds:=[acne]

query_by=concernNames,ingredientNames,productType,routineStep,brandName
group_by=productFamilyId

For best_used_with, the query must prefer a complementary routine step and exclude duplicate actives. For similar, it can retain the same product type/concern. The strategy decides this; a generic vector-nearest-neighbor query is insufficient.

Routine and safety policy

Compass stores controlled relationship tables:

product_relationships
  anchor_product_id, related_product_id, relationship_type, confidence, source

routine_step_rules
  anchor_step, allowed_complement_steps, prohibited_same_steps

ingredient_conflicts
  ingredient_a, ingredient_b, severity, rationale, applies_to

safety_cautions
  attribute_or_ingredient, caution_type, policy

Before a widget can render, Compass excludes:

Anchor product itself.
Rx products from all promotional widgets.
Out-of-stock or unlistable products.
Forbidden category/widget combinations.
Same routine step where complementarity is required.
Duplicate active ingredients where redundancy is forbidden.
Known ingredient conflicts and declared safety cautions.

A shorter widget is preferable to weak padding. Every selected item records which source/fallback supplied it.

Recommendation merchandising, fallback, and events

Merchandisers can pin, hide, cap, floor, or fully replace a widget with a curated list through the same Compass rule model. Widget rules are scoped by widget type, surface, anchor product/family/category, and schedule.

model/relationship candidates
  -> curated pin/hide/replace
  -> candidate source fallback order
  -> short or empty safe widget if no quality result exists

Compass/Tetris emits widget payload context: widget ID, strategy/version, anchor, slots, selected products, source/fallback, profile/configuration version. The client sends a visible widget impression only when rendered in viewport, then click/add-to-cart context. PostHog measures impression-to-click, click-to-cart, attributed revenue, fallback serve rate, empty rate, and session-level effect.

End-to-End Use Cases

Exact product

Acne UV Gel
  -> Compass: protected family, product intent, exact lexical profile
  -> TypeSense: title/family/brand weighted retrieval, grouping, pin/hide
  -> Compass: display variant, final eligibility, context token

Vector search is disabled or strongly downweighted.

Brand

Cetaphil
  -> Compass: brand dictionary match
  -> redirect to brand PLP if configured, otherwise brand lexical profile
  -> TypeSense: brand-weighted query or exact brand filter
  -> Compass: brand header, active rules, eligibility

Category, ingredient, concern

retinol serum
  -> Compass: ingredient=retinol, productType=serum
  -> TypeSense: structured lexical query, facets, profile
  -> Compass: claims/Rx policy and response shaping

dark spots
  -> Compass: concern=pigmentation
  -> TypeSense: concern/category/title retrieval
  -> Compass: concern PLP entry point and safety policy

Hinglish

muhase ki cream
  -> Compass aliases: muhase -> acne
  -> optional product-type preference: treatment/cream
  -> TypeSense: structured lexical search

oily skin ke liye sunscreen
  -> Compass: sunscreen + oily skin type
  -> TypeSense: sunscreen retrieval + skin-type filter

Hinglish aliases are Compass-controlled rows with locale, canonical entity, source, confidence, version, and approval state. They are not solely vector-model guesses.

Typo and structured search

sunscreem spf 50
  -> Compass: protected terms and spf >= 50 extraction
  -> TypeSense: native typo-tolerant sunscreen retrieval + SPF filter

spf above 50 sunscreen for oily skin under 700
  -> Compass: sunscreen, SPF > 50, oily, price <= 700 QueryPlan
  -> TypeSense: fielded lexical query + filters/facets/ranking
  -> Client: removable filter chips

Autosuggest

prefix "sun"
  -> client debounce 150-250 ms
  -> Compass normalization/protection/alias policy
  -> TypeSense product, brand, category, concern, ingredient, popular-query candidates
  -> Compass pinned/blocked/quality rules
  -> grouped destination-aware suggestions

Browse/PLP

/concerns/acne
  -> Compass/Tetris page definition
  -> TypeSense q=* + concern inclusion + eligibility + facets + profile
  -> Compass/Tetris content, badges, consult modules

Semantic/hybrid search

cream for dark spots
  -> Compass deterministic parsing first
  -> natural-language/weak-lexical classification
  -> query embedding + hybrid TypeSense profile
  -> TypeSense combines lexical relevance and vector similarity
  -> Compass applies exact-match protection, rules, and safety

Use hybrid retrieval only after lexical, Hinglish, fixtures, and baseline metrics are proven. Exact product/brand/ingredient and approved alias queries remain lexical dominant. Medical/Rx queries do not become semantic merchandising.

Redirect, medical, and fallback

offers -> Compass redirect -> sale page

tretinoin -> Compass Rx/consult policy -> permitted direct discovery or consultation flow

blood pressure tablet -> Compass medical/out-of-scope policy -> consultation route

normal poor result -> typo-safe correction -> relax low-confidence modifiers
  -> hybrid fallback when enabled -> closest honest category/concern response

Every redirect, fallback, and consultation decision is recorded in Compass explain evidence and PostHog.

Recommendations

PDP niacinamide serum -> best-used-with widget
  -> Compass strategy/candidate source
  -> TypeSense controlled candidate retrieval where applicable
  -> Compass excludes Rx, stock failures, anchor product, duplicate steps, ingredient conflicts
  -> Compass widget pins/fallback -> Tetris render

Merchandising Compilation

Compass PostgreSQL is the rule source of truth. TypeSense is an execution target.

Panel -> Compass draft -> validation -> preview -> approval
  -> immutable configuration version
  -> TypeSense override/synonym sync or request-time parameters
  -> Compass final validation and explain record

Core records:

merchandising_rules
typesense_rule_sync
rule_audits
ranking_profiles
synonym_sets
protected_terms
redirect_rules
campaigns

typesense_rule_sync records TypeSense resource type/ID, source rule version, pending|synced|failed status, time, and error. Disabling a rule immediately removes it from Compass active configuration and queues TypeSense deletion. For a pin:

User searches sunscreen
  -> Compass loads matching config/rules
  -> sends eligibility filter + native pin/override to TypeSense
  -> TypeSense ranks and places eligible pin
  -> Compass validates, records rule/resource/version, returns result

Event Contract and Routing

Portable event envelope:

{
  "event_id": "uuid",
  "event_name": "search_result_clicked",
  "schema_version": 1,
  "occurred_at": "timestamp",
  "received_at": "server timestamp",
  "producer": "web_sdk | ios_sdk | android_sdk | compass | vector | medusa",
  "anonymous_id": "optional",
  "session_id": "required where applicable",
  "user_id": "optional",
  "request_id": "optional",
  "discovery_context": { "search_id": "optional", "surface": "search_results" },
  "properties": {}
}

Event	TypeSense	PostHog	Compass PostgreSQL
Search	Auto-capture popular/no-hit; disabled for shadow/tests	Server `search_executed`	Explain/profile/rule/provider evidence
Verified click/visit	Counter/log if configured	Validated UI interaction	No raw clickstream
Filter/sort/suggestion/impression	Usually no	Validated UI interaction	No raw clickstream
Cart/order/refund	Optional verified counter conversion	Authoritative server event	Attribution/config evidence

Compass returns an opaque signed discovery_context_token per result. Clients pass it unchanged to clicks and add-to-cart; Vector/Medusa validates it and persists primary discovery attribution on the cart line. The order event uses that persisted line attribution.

Provider Migration Runtime

Compass provider router
  netcore
  shadow
  typesense
  typesense_with_netcore_fallback

Assignment is server-side and sticky:

assignment_id = user_id, else anonymous_id, else session_id
bucket = hash("discovery-provider-v1" + assignment_id) % 100

Shadow returns Netcore, calls TypeSense asynchronously, disables TypeSense analytics, and records normalized comparison data. Public TypeSense traffic falls back to Netcore on invalid response, timeout, index freshness breach, or safety failure.

Tests and Operational Evidence

Golden cases include exact products/brands, typos, protected terms, Hinglish aliases, structured filters, redirects, zero-result recovery, Rx handling, pins/hides, and recommendation exclusions. For every search, retain a short-lived explain record with raw/normalized query, query plan, TypeSense parameters, filters, active profile/configuration version, applied rules, excluded candidates/reasons, score contributions where available, result positions, fallback, provider, and latency.

​Discovery Platform Low-Level Design

​Runtime Contract

​Discovery Product Document

​Query Understanding

​Pipeline

​Intent signals

​Numeric extraction

​Query-plan type

​TypeSense Request Compilation and Ranking

​Ranking precedence

​Eligibility and Final Validation

​Core Surface Designs

​Search

​Search API contract

​Search execution sequence

​Search profiles

​Filters, sorting, grouping, and pagination

​Search fallback ladder

​Search failure behavior

​Search measurement

​Autosuggest

​Design principle

​Collections

​Suggest API contract

​Suggest execution sequence

​Suggest response contract

​Popular query quality gate

​Empty-prefix suggestions

​Suggest analytics

​Browse and PLP

​Page definition

​Browse request flow

​Filter configuration

​Browse merchandising and content

​Browse SEO and events

​Recommendations

​Design boundary

​Widget request contract

​Strategy configuration

​TypeSense recommendation retrieval

​Routine and safety policy

​Recommendation merchandising, fallback, and events

​End-to-End Use Cases

​Exact product

​Brand

​Category, ingredient, concern

​Hinglish

​Typo and structured search

​Autosuggest

​Browse/PLP

​Semantic/hybrid search

​Redirect, medical, and fallback

​Recommendations

​Merchandising Compilation

​Event Contract and Routing

​Provider Migration Runtime

​Tests and Operational Evidence

Discovery Platform Low-Level Design

Runtime Contract

Discovery Product Document

Query Understanding

Pipeline

Intent signals

Numeric extraction

Query-plan type

TypeSense Request Compilation and Ranking

Ranking precedence

Eligibility and Final Validation

Core Surface Designs

Search

Search API contract

Search execution sequence

Search profiles

Filters, sorting, grouping, and pagination

Search fallback ladder

Search failure behavior

Search measurement

Autosuggest

Design principle

Collections

Suggest API contract

Suggest execution sequence

Suggest response contract

Popular query quality gate

Empty-prefix suggestions

Suggest analytics

Browse and PLP

Page definition

Browse request flow

Filter configuration

Browse merchandising and content

Browse SEO and events

Recommendations

Design boundary

Widget request contract

Strategy configuration

TypeSense recommendation retrieval

Routine and safety policy

Recommendation merchandising, fallback, and events

End-to-End Use Cases

Exact product

Brand

Category, ingredient, concern

Hinglish

Typo and structured search

Autosuggest

Browse/PLP

Semantic/hybrid search

Redirect, medical, and fallback

Recommendations

Merchandising Compilation

Event Contract and Routing

Provider Migration Runtime

Tests and Operational Evidence