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

Storefront Navigation Flow

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

URL Hierarchy

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

Navigation Patterns

Pattern 1: With Landing Page (Recommended)

URL Structure:

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

Navigation Flow:

1. User visits store domain → Landing Page
2. Clicks "Shop Now" → /storefront/ (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 /storefront/
customdomain.com/storefront/         → E-commerce Storefront
customdomain.com/storefront/products → Product Catalog

Navigation Flow:

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

Breadcrumb Example (on Products page):

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

Link References

Base URL Calculation

The base_url variable is calculated in storefront_pages.py:get_storefront_context():

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

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

Template Links

Logo / Home Link (Header):

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

Breadcrumb Home Link:

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

Storefront Links:

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

CMS Page Links:

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

Complete URL Examples

Path-Based Access (Development)

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

Subdomain Access (Production)

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

Custom Domain Access (Production)

https://customdomain.com/
├── / (root)                              → Landing Page OR redirect to storefront
├── /storefront/                                → Storefront Homepage
├── /storefront/products                        → Product Catalog
├── /storefront/products/4                      → Product Detail
├── /storefront/cart                            → Shopping Cart
├── /storefront/checkout                        → Checkout
├── /storefront/account/login                   → Customer Login
├── /storefront/about                           → About Page (CMS)
└── /storefront/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" → /storefront/ → Product Catalog
   • Browses products
3. Clicks product → /storefront/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 Storefront)

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

Journey 3: Customer Account Management

1. Visit customdomain.com/storefront/account/login → Login
2. After login → /storefront/account/dashboard → Dashboard
3. View orders → /storefront/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 }}storefront/">
    <img src="{{ theme.branding.logo }}" alt="{{ store.name }}">
</a>

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

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

Footer Navigation (base.html)

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

{# CMS Pages (dynamic) #}
{% for page in footer_pages %}
<a href="{{ base_url }}storefront/{{ 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 storefront and back
3. Consistent "Home": Logo and "Home" breadcrumb both point to / (landing)
4. Storefront Links: All storefront-related links include /storefront/ prefix
5. CMS Under Storefront: Keep CMS pages under /storefront/ for consistency

❌ DON'T:

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

Migration Notes

Before Landing Pages

All links pointed to /storefront/:

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

After Landing Pages

Separation of concerns:

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

This allows:

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

Technical Implementation

Route Handlers (main.py)

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

# Storefront routes
@app.include_router(storefront_pages.router, prefix="/storefront")
@app.include_router(storefront_pages.router, prefix="/storefront/{store_code}")

Context Calculation (storefront_pages.py)

def get_storefront_context(request: Request):
    base_url = "/"
    if access_method == "path":
        base_url = f"/storefront/{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. Storefront (/storefront/) - 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 storefront

All while maintaining clean, consistent navigation throughout the experience.