Skip to content

0034 — Product families: same-design colour options, and a mixed default feed (Nov 2026)

Status: accepted for implementation (2026-11-18). Migration 149. Opt-in per product; every existing product is unchanged and nothing is grouped by the migration.

Problem

One design (a jogger pant) is sold in several colours, and each colour is already its own product: its own id, price, images, sizes, stock, tax setting and availability. A customer had no way to move between the colours of the same design except by going back to the list, and the default All products feed showed a long run of one design before anything else.

Decisions

  1. A dedicated family relationship, not the category. New table product_families (id, name) and two NEW NULLABLE columns on shop_items: family_id (FK) and color_label. Category and name are never used to group products: two jogger pants in the same category are unrelated unless an admin put them in one family.
  2. Nothing is grouped automatically. The migration creates the table empty and adds columns that are NULL for every product. There is no backfill and no name matching. A product joins a family only when an admin assigns it (Admin → Product → Colour family), so the grouping is always an explicit, verified owner decision.
  3. The invariant is enforced twice (API and database CHECK): a product is in no family (both columns NULL) or in exactly one family with a colour label of 1–30 characters. A colour label is unique within a family, case-insensitively (a partial unique index), so the picker is never ambiguous. Family names are unique case-insensitively, so a typo cannot create a second "Jogger Pant".
  4. Colours stay independent products. The link is read by nothing in checkout: orders, carts, payments, invoices and inventory never look at family_id or color_label. Editing one colour never touches another.
  5. Write semantics mirror the image gallery. On a product Create/Update the two fields travel together. Both omitted: the link is left exactly as it is (a legacy client cannot un-group a product). A blank family_id: the product leaves its family and the label is cleared. family_id plus color_label: it joins. A lone label is refused. A taken colour is a 409 FAMILY_COLOR_TAKEN; an unknown family is a 400 FAMILY_INVALID.
  6. API. The public product list and detail already return every field of the product; family_id and color_label are added with omitempty, so an ungrouped product's JSON is byte-for-byte what it was. Admin only: GET /admin/product-families (families with their members) and POST /admin/product-families {name} (creates, or returns the existing family with that name: 201 new, 200 existing). Creating a family links nothing.
  7. App: "Available Colors". The app already holds the whole catalogue, so the options are the products with the same family_id that are in the list (inactive products and switched-off categories are absent, so an unavailable colour is never offered). A sold-out colour is shown, dimmed and labelled. A family with one colour, or an ungrouped product, shows no section. Tapping a colour changes the route id in place (router.setParams), so it is the same screen with normal Back and a valid deep link per colour; gallery, name, price, MRP, discount, stock, sizes, details, Add to cart and Buy now all derive from the product with that id. A selected size is kept only if the new colour still sells it (enabled, in stock); otherwise it is reset.
  8. App: mixed default feed. The server order is unchanged. In the default "relevance" order with no search text and no special collection, the app reorders the already-filtered list so one design is not shown many times in a row: products are bucketed by design type (the last word of the name that is not a colour or size), each bucket is spread evenly across the list, one-off products are pooled and spread the same way, and colours of one family are spread inside their type. It is deterministic (no randomness), a pure permutation (nothing hidden or duplicated), and prefix-stable. An explicit sort (price low to high, high to low), search results and the new/best/recommended/discounted collections keep their own order. The design type is a display heuristic only; it never groups products for colour selection.

What was deliberately not done

  • No automatic or bulk grouping, and no suggested groups from names: the owner assigns each family. After deploy every product is ungrouped.
  • No change to inventory, orders, payments, invoices or customer data.
  • No server-side shuffle and no server paging: the catalogue endpoint returns the full list as before.

Rollback

rollback_149.sql drops the two columns, their constraint and indexes, and the table. It removes only the grouping links; export them first if they should be kept (the script says how). Older app builds ignore the extra fields.