Breadcrumb Navigation

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/breadcrumb-navigation/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Breadcrumb Navigation is a core feature that auto-generates breadcrumb trails for product pages (e.g., Home > Men > Shirts > Red). It helps customers navigate back to parent categories and improves SEO.

The problem

Customers get lost in deep category trees and can’t navigate back; bounce rates increase.

What it does

• Auto-generate breadcrumb trail from category hierarchy on product and category pages
• Render clickable breadcrumb links to navigate up tree
• Support schema.org BreadcrumbList markup generation
• Customizable breadcrumb separator (/, >, |, etc.)
• Admin setting: enable/disable breadcrumbs globally
• Fallback: if breadcrumb missing, show ‘Home > Products’

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.

• Does NOT support custom breadcrumb labels (reason: use category name)
• Does NOT support breadcrumb styling (reason: frontend theme responsibility)
• Does NOT track breadcrumb clicks (reason: analytics feature)

Data model

No new tables (breadcrumbs derived from category.parent_id hierarchy).

API

• GET /api/products/:id/breadcrumbs
• GET /api/categories/:id/breadcrumbs
• GET /api/breadcrumbs/schema

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

Admin

Settings: separator character, enable/disable breadcrumbs; preview showing how breadcrumbs render for sample product.

The seam — why this is core

Core owns: breadcrumb generation, rendering, schema.org markup.

Core owns the interface + honest breadcrumb renderer; navigation is storefront infrastructure, not a per-country obligation or credential.

Dependencies

• Assumes category hierarchy exists (category.parent_id)
• Assumes product-to-category relationship exists

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.

• Product in Men > Shirts > Red shows ‘Home > Men > Shirts > Red’
• Breadcrumb links clickable and navigate to category pages
• Breadcrumb schema.org markup valid and includes all items
• Separator character changeable from ’/’ to ’>’, ’|’, etc.
• Breadcrumbs render correctly for nested categories (5+ levels)
• Fallback breadcrumb is ‘Home > Products’ if hierarchy missing
• All storage drivers generate identical breadcrumbs

Risks

Circular category: if category A has parent A, infinite loop. Missing category: if product references deleted category, breadcrumb incomplete. Deep nesting: 20+ levels unwieldy on mobile.

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.