Tier-0 Recommendation Rules

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/tier-0-recommendation-rules/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Rule-based product recommendations (same category, co-purchase history, bestsellers) that are free and require no ML expertise. Shown on product detail pages and cart pages as ‘Frequently Bought Together’ or ‘Similar Products’. Advanced ML-driven recommendations stay paid; rule-based stays free to ensure every merchant can offer basic recommendations.

The problem

When a customer views a camera, I want to suggest lenses automatically. I don’t have ML; I just want to show ‘people who bought this camera also bought these lenses’ or ‘similar products in same category’. I can’t afford advanced analytics; I need simple rules.

What it does

• Recommendation rule types: same category (show related products), co-purchase (show often-bought-together), bestsellers (top 5 sellers in category), price range (similar price ±20%)
• Rule builder: ‘if product_id=CAMERA then show top 5 products co-purchased with CAMERA’ (based on order history)
• Recommendation blocks: ‘Frequently Bought Together’ (3–5 products), ‘Similar Products’ (3–5 products), ‘New Arrivals in Category’ (3–5 products)
• Placement: product detail page (below images), cart page (before checkout), category pages (sidebar)
• Exclusions: merchant can exclude specific products from recommendations (e.g., don’t recommend if out of stock)
• Recency: co-purchase recommendations use last 90 days of order history (or configurable window)
• Analytics: track recommendation clicks (click-through rate), add-to-cart from recommendations (conversion)
• A/B testing (basic): merchant can run two rules side-by-side on 50/50 customers, see which converts better
• Personalization (basic): if customer viewed product X, show recommendations based on product X (session-based, no user ID needed)
• Performance: recommendations load in <500ms (pre-computed, not real-time)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• ML-driven collaborative filtering — that is paid ML recommendation module. Tier-0 is rule-based only.
• Cross-shop recommendations — recommendations use only this shop’s data, not marketplace data.
• Real-time personalization — personalization is session-based or time-window-based, not real-time ML.
• Recommendation serving at scale (CDN edge) — recommendations are served from origin; CDN caching is optional.
• Bandit optimization (ML learns best rule) — that is paid optimization. Rules are merchant-defined.

Data model

New RECOMMENDATION_RULE table (rule_id, name, type (same_category|co_purchase|bestseller|price_range), source_product_id, target_count, filters JSON, exclusions JSON, created_at). New RECOMMENDATION_CLICK_LOG table (log_id, rule_id, source_product_id, recommended_product_id, clicked, added_to_cart, clicked_at). Migration required: none (new tables).

API

• POST /admin/recommendations/rules (create rule)
• GET /admin/recommendations/rules (list rules)
• PATCH /admin/recommendations/rules/:id (update rule)
• DELETE /admin/recommendations/rules/:id (delete rule)
• GET /products/:id/recommendations (return 3–5 recommended products based on active rules)
• GET /admin/recommendations/analytics (click-through rate, conversion rate per rule)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Recommendation Rules page with table of active rules. Create rule button. Rule builder: type picker (same category, co-purchase, bestseller, price range), source product/category, target count (how many to show), filters (if in stock, if price > €50). Analytics dashboard: click-through rate (10% mean), conversion rate (2% mean) per rule, top-performing rules by revenue impact.

The seam — why this is core

Core owns rule-based recommendation engine and computation. Core does not own ML models (that is paid recommendation module) or real-time personalization (that is paid personalization module). Core provides tier-0 (free) functionality; paid modules add advanced features.

Rule-based recommendations (same category, co-purchase, bestsellers) stay free. Advanced ML goes paid. Delivers merchandising value immediately.

Dependencies

• Product model (core, existing)
• Order history (core, for co-purchase analysis)
• Inventory management (for in-stock filtering)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Co-purchase rule created: ‘if product=DSLR Camera, show top 5 products co-purchased with it’. Rule computes on save using last 90 days of orders.
• Product detail page shows ‘Frequently Bought Together’ section with 5 recommended lenses/tripods
• Recommendation only shows if product is in stock (if filter applied); out-of-stock products excluded
• Same-category rule: ‘if product in category=Sunglasses, show 3 other sunglasses’ works and shows similar products
• Bestseller rule: ‘show top 5 bestsellers in category=Sunglasses’ shows 5 best-selling sunglasses
• Recommendation click is logged: clicking recommended product adds log entry with rule_id, source_product_id, recommended_product_id, clicked=true
• Recommendation analytics: ‘500 clicks on Camera → Lens recommendations this month, 25 added to cart (5% conversion rate)’
• A/B test: rule variant A shows ‘Frequently Bought’ vs. variant B shows ‘Top Sellers’; customers see variant based on session hash; conversion rate compared after 100 clicks each

Risks

If co-purchase data is empty (new shop), recommendations are blank. Mitigate: fall back to bestseller or same-category rule if co-purchase has <5 options. If recommendation clicks are logged but not attributed to revenue, analytics is incomplete. Mitigate: log conversion (add-to-cart, order) per recommendation, not just clicks. If A/B test is not randomized, data is biased (e.g., always show rule A to returning customers). Mitigate: use session hash for consistent variant assignment, document randomization method.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.