orion/docs/frontend/storefront/navigation-flow.md

Shop Navigation Flow

Complete guide to navigation structure and URL hierarchy with landing pages.

URL Hierarchy

/ (Store Root)                    → Landing Page (if exists) OR redirect to /shop/
├── /shop/                         → E-commerce Homepage (Product Catalog)
│   ├── /shop/products             → Product Catalog (same as /shop/)
│   ├── /shop/products/{id}        → Product Detail Page
│   ├── /shop/cart                 → Shopping Cart
│   ├── /shop/checkout             → Checkout Process
│   ├── /shop/account/login        → Customer Login
│   ├── /shop/account/register     → Customer Registration
│   ├── /shop/account/dashboard    → Customer Dashboard (auth required)
│   ├── /shop/about                → CMS Content Page
│   ├── /shop/contact              → CMS Content Page
│   └── /shop/{slug}               → Other CMS Pages

Navigation Patterns

Pattern 1: With Landing Page (Recommended)

URL Structure:

customdomain.com/              → Landing Page (marketing/brand)
customdomain.com/shop/         → E-commerce Shop
customdomain.com/shop/products → Product Catalog

Navigation Flow:

1. User visits store domain → Landing Page
2. Clicks "Shop Now" → /shop/ (product catalog)
3. Clicks "Home" in breadcrumb → / (back to landing page)
4. Clicks logo → / (back to landing page)

Breadcrumb Example (on Products page):

Home > Products
 ↓
 / (Landing Page)

Pattern 2: Without Landing Page (Auto-Redirect)

URL Structure:

customdomain.com/              → Redirects to /shop/
customdomain.com/shop/         → E-commerce Shop
customdomain.com/shop/products → Product Catalog

Navigation Flow:

1. User visits store domain → Redirects to /shop/
2. User browses shop
3. Clicks "Home" in breadcrumb → / (redirects to /shop/)
4. Clicks logo → / (redirects to /shop/)

Breadcrumb Example (on Products page):

Home > Products
 ↓
 / → /shop/ (redirects)

Link References

Base URL Calculation

The base_url variable is calculated in shop_pages.py:get_shop_context():

# For domain/subdomain access
base_url = "/"
# Result: /shop/products, /shop/cart, etc.

# For path-based access
base_url = "/stores/orion/"
# Result: /stores/orion/shop/products, /stores/orion/shop/cart, etc.

Template Links

Logo / Home Link (Header):

{# Points to store root (landing page or shop) #}
<a href="{{ base_url }}shop/">{{ store.name }}</a>

Breadcrumb Home Link:

{# Points to store root (landing page) #}
<a href="{{ base_url }}">Home</a>

Shop Links:

{# All shop pages include /shop/ prefix #}
<a href="{{ base_url }}shop/products">Products</a>
<a href="{{ base_url }}shop/cart">Cart</a>
<a href="{{ base_url }}shop/checkout">Checkout</a>

CMS Page Links:

{# CMS pages are under /shop/ #}
<a href="{{ base_url }}shop/about">About</a>
<a href="{{ base_url }}shop/contact">Contact</a>
<a href="{{ base_url }}shop/{{ page.slug }}">{{ page.title }}</a>

Complete URL Examples

Path-Based Access (Development)

http://localhost:8000/stores/orion/
├── / (root)                              → Landing Page OR redirect to shop
├── /shop/                                → Shop Homepage
├── /shop/products                        → Product Catalog
├── /shop/products/4                      → Product Detail
├── /shop/cart                            → Shopping Cart
├── /shop/checkout                        → Checkout
├── /shop/account/login                   → Customer Login
├── /shop/about                           → About Page (CMS)
└── /shop/contact                         → Contact Page (CMS)

Subdomain Access (Production)

https://orion.platform.com/
├── / (root)                              → Landing Page OR redirect to shop
├── /shop/                                → Shop Homepage
├── /shop/products                        → Product Catalog
├── /shop/products/4                      → Product Detail
├── /shop/cart                            → Shopping Cart
├── /shop/checkout                        → Checkout
├── /shop/account/login                   → Customer Login
├── /shop/about                           → About Page (CMS)
└── /shop/contact                         → Contact Page (CMS)

Custom Domain Access (Production)

https://customdomain.com/
├── / (root)                              → Landing Page OR redirect to shop
├── /shop/                                → Shop Homepage
├── /shop/products                        → Product Catalog
├── /shop/products/4                      → Product Detail
├── /shop/cart                            → Shopping Cart
├── /shop/checkout                        → Checkout
├── /shop/account/login                   → Customer Login
├── /shop/about                           → About Page (CMS)
└── /shop/contact                         → Contact Page (CMS)

User Journeys

Journey 1: First-Time Visitor (With Landing Page)

1. Visit customdomain.com/ → Landing Page
   • Sees brand story, features, CTA
2. Clicks "Shop Now" → /shop/ → Product Catalog
   • Browses products
3. Clicks product → /shop/products/4 → Product Detail
   • Views product
4. Clicks "Home" in breadcrumb → / → Back to Landing Page
5. Clicks logo → / → Back to Landing Page

Journey 2: Returning Customer (Direct to Shop)

1. Visit customdomain.com/shop/ → Product Catalog
   • Already knows the brand, goes straight to shop
2. Adds to cart → /shop/cart → Shopping Cart
3. Checkout → /shop/checkout → Checkout
4. Clicks "Home" → / → Landing Page (brand homepage)

Journey 3: Customer Account Management

1. Visit customdomain.com/shop/account/login → Login
2. After login → /shop/account/dashboard → Dashboard
3. View orders → /shop/account/orders → Order History
4. Clicks logo → / → Back to Landing Page

Navigation Components

Header Navigation (base.html)

{# Logo - always points to store root #}
<a href="{{ base_url }}shop/">
    <img src="{{ theme.branding.logo }}" alt="{{ store.name }}">
</a>

{# Main Navigation #}
<nav>
    <a href="{{ base_url }}shop/">Home</a>
    <a href="{{ base_url }}shop/products">Products</a>
    <a href="{{ base_url }}shop/about">About</a>
    <a href="{{ base_url }}shop/contact">Contact</a>
</nav>

{# Actions #}
<a href="{{ base_url }}shop/cart">Cart</a>
<a href="{{ base_url }}shop/account">Account</a>

Footer Navigation (base.html)

{# Quick Links #}
<a href="{{ base_url }}shop/products">Products</a>

{# CMS Pages (dynamic) #}
{% for page in footer_pages %}
<a href="{{ base_url }}shop/{{ page.slug }}">{{ page.title }}</a>
{% endfor %}

Breadcrumbs (products.html, content-page.html)

{# Points to store root (landing page) #}
<a href="{{ base_url }}">Home</a> / Products

Best Practices

✅ DO:

1. Use Landing Pages: Create engaging landing pages at store root
2. Clear Navigation: Make it easy to get from landing to shop and back
3. Consistent "Home": Logo and "Home" breadcrumb both point to / (landing)
4. Shop Links: All shop-related links include /shop/ prefix
5. CMS Under Shop: Keep CMS pages under /shop/ for consistency

❌ DON'T:

1. Hardcode URLs: Always use {{ base_url }} for store-aware links
2. Skip /shop/: Don't link directly to /products, use /shop/products
3. Mix Landing & Shop: Keep landing page separate from shop catalog
4. Forget Breadcrumbs: Always provide "Home" link to go back

Migration Notes

Before Landing Pages

All links pointed to /shop/:

<a href="{{ base_url }}shop/">Home</a>  {# Logo #}
<a href="{{ base_url }}shop/">Home</a>  {# Breadcrumb #}

After Landing Pages

Separation of concerns:

<a href="{{ base_url }}shop/">Home</a>  {# Logo - still goes to shop #}
<a href="{{ base_url }}">Home</a>       {# Breadcrumb - goes to landing #}

This allows:

• Landing page at / for marketing/branding
• Shop catalog at /shop/ for e-commerce
• Clean navigation between the two

Technical Implementation

Route Handlers (main.py)

# Store root - serves landing page or redirects to shop
@app.get("/")
@app.get("/stores/{store_code}/")
async def root(request: Request):
    if has_landing_page():
        return render_landing_page()
    else:
        return redirect_to_shop()

# Shop routes
@app.include_router(shop_pages.router, prefix="/shop")
@app.include_router(shop_pages.router, prefix="/stores/{store_code}/shop")

Context Calculation (shop_pages.py)

def get_shop_context(request: Request):
    base_url = "/"
    if access_method == "path":
        base_url = f"/stores/{store.subdomain}/"

    return {
        "base_url": base_url,
        "store": store,
        "theme": theme,
        # ...
    }

Summary

The navigation system creates a two-tier structure:

1. Landing Page (/) - Marketing, branding, store story
2. Shop (/shop/) - E-commerce, products, cart, checkout

This gives stores flexibility to:

• Have a marketing homepage separate from their store
• Choose different landing page designs (minimal, modern, full)
• Or skip the landing page and go straight to the shop

All while maintaining clean, consistent navigation throughout the experience.