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()`:

```python
# 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):**
```jinja2
{# Points to store root (landing page or storefront) #}
<a href="{{ base_url }}storefront/">{{ store.name }}</a>
```

**Breadcrumb Home Link:**
```jinja2
{# Points to store root (landing page) #}
<a href="{{ base_url }}">Home</a>
```

**Storefront Links:**
```jinja2
{# 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:**
```jinja2
{# 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)

```jinja2
{# 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)

```jinja2
{# 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)

```jinja2
{# 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/`:
```jinja2
<a href="{{ base_url }}storefront/">Home</a>  {# Logo #}
<a href="{{ base_url }}storefront/">Home</a>  {# Breadcrumb #}
```

### After Landing Pages

Separation of concerns:
```jinja2
<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)

```python
# 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)

```python
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.