docs: add consolidated dev URL reference and migrate /shop to /storefront
Some checks failed
Some checks failed
- Add Development URL Quick Reference section to url-routing overview with all login URLs, entry points, and full examples - Replace /shop/ path segments with /storefront/ across 50 docs files - Update file references: shop_pages.py → storefront_pages.py, templates/shop/ → templates/storefront/, api/v1/shop/ → api/v1/storefront/ - Preserve domain references (orion.shop) and /store/ staff dashboard paths - Archive docs left unchanged (historical) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -1,22 +1,22 @@
|
||||
# Shop Navigation Flow
|
||||
# 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 /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
|
||||
/ (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
|
||||
@@ -26,13 +26,13 @@ Complete guide to navigation structure and URL hierarchy with landing pages.
|
||||
**URL Structure:**
|
||||
```
|
||||
customdomain.com/ → Landing Page (marketing/brand)
|
||||
customdomain.com/shop/ → E-commerce Shop
|
||||
customdomain.com/shop/products → Product Catalog
|
||||
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" → **/shop/** (product catalog)
|
||||
2. Clicks "Shop Now" → **/storefront/** (product catalog)
|
||||
3. Clicks "Home" in breadcrumb → **/** (back to landing page)
|
||||
4. Clicks logo → **/** (back to landing page)
|
||||
|
||||
@@ -47,46 +47,46 @@ Home > Products
|
||||
|
||||
**URL Structure:**
|
||||
```
|
||||
customdomain.com/ → Redirects to /shop/
|
||||
customdomain.com/shop/ → E-commerce Shop
|
||||
customdomain.com/shop/products → Product Catalog
|
||||
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 /shop/**
|
||||
2. User browses shop
|
||||
3. Clicks "Home" in breadcrumb → **/** (redirects to /shop/)
|
||||
4. Clicks logo → **/** (redirects to /shop/)
|
||||
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
|
||||
↓
|
||||
/ → /shop/ (redirects)
|
||||
/ → /storefront/ (redirects)
|
||||
```
|
||||
|
||||
## Link References
|
||||
|
||||
### Base URL Calculation
|
||||
|
||||
The `base_url` variable is calculated in `shop_pages.py:get_shop_context()`:
|
||||
The `base_url` variable is calculated in `storefront_pages.py:get_storefront_context()`:
|
||||
|
||||
```python
|
||||
# For domain/subdomain access
|
||||
base_url = "/"
|
||||
# Result: /shop/products, /shop/cart, etc.
|
||||
# Result: /storefront/products, /storefront/cart, etc.
|
||||
|
||||
# For path-based access
|
||||
base_url = "/stores/orion/"
|
||||
# Result: /stores/orion/shop/products, /stores/orion/shop/cart, etc.
|
||||
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 shop) #}
|
||||
<a href="{{ base_url }}shop/">{{ store.name }}</a>
|
||||
{# Points to store root (landing page or storefront) #}
|
||||
<a href="{{ base_url }}storefront/">{{ store.name }}</a>
|
||||
```
|
||||
|
||||
**Breadcrumb Home Link:**
|
||||
@@ -95,20 +95,20 @@ base_url = "/stores/orion/"
|
||||
<a href="{{ base_url }}">Home</a>
|
||||
```
|
||||
|
||||
**Shop Links:**
|
||||
**Storefront Links:**
|
||||
```jinja2
|
||||
{# 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>
|
||||
{# 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 /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>
|
||||
{# 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
|
||||
@@ -116,46 +116,46 @@ base_url = "/stores/orion/"
|
||||
### 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)
|
||||
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 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)
|
||||
├── / (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 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)
|
||||
├── / (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
|
||||
@@ -164,26 +164,26 @@ https://customdomain.com/
|
||||
|
||||
1. Visit `customdomain.com/` → **Landing Page**
|
||||
- Sees brand story, features, CTA
|
||||
2. Clicks "Shop Now" → `/shop/` → **Product Catalog**
|
||||
2. Clicks "Shop Now" → `/storefront/` → **Product Catalog**
|
||||
- Browses products
|
||||
3. Clicks product → `/shop/products/4` → **Product Detail**
|
||||
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 Shop)
|
||||
### Journey 2: Returning Customer (Direct to Storefront)
|
||||
|
||||
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**
|
||||
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/shop/account/login` → **Login**
|
||||
2. After login → `/shop/account/dashboard` → **Dashboard**
|
||||
3. View orders → `/shop/account/orders` → **Order History**
|
||||
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
|
||||
@@ -192,32 +192,32 @@ https://customdomain.com/
|
||||
|
||||
```jinja2
|
||||
{# Logo - always points to store root #}
|
||||
<a href="{{ base_url }}shop/">
|
||||
<a href="{{ base_url }}storefront/">
|
||||
<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>
|
||||
<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 }}shop/cart">Cart</a>
|
||||
<a href="{{ base_url }}shop/account">Account</a>
|
||||
<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 }}shop/products">Products</a>
|
||||
<a href="{{ base_url }}storefront/products">Products</a>
|
||||
|
||||
{# CMS Pages (dynamic) #}
|
||||
{% for page in footer_pages %}
|
||||
<a href="{{ base_url }}shop/{{ page.slug }}">{{ page.title }}</a>
|
||||
<a href="{{ base_url }}storefront/{{ page.slug }}">{{ page.title }}</a>
|
||||
{% endfor %}
|
||||
```
|
||||
|
||||
@@ -233,39 +233,39 @@ https://customdomain.com/
|
||||
### ✅ 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
|
||||
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. **Shop Links**: All shop-related links include `/shop/` prefix
|
||||
5. **CMS Under Shop**: Keep CMS pages under `/shop/` for consistency
|
||||
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 /shop/**: Don't link directly to `/products`, use `/shop/products`
|
||||
3. **Mix Landing & Shop**: Keep landing page separate from shop catalog
|
||||
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 `/shop/`:
|
||||
All links pointed to `/storefront/`:
|
||||
```jinja2
|
||||
<a href="{{ base_url }}shop/">Home</a> {# Logo #}
|
||||
<a href="{{ base_url }}shop/">Home</a> {# Breadcrumb #}
|
||||
<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 }}shop/">Home</a> {# Logo - still goes to shop #}
|
||||
<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
|
||||
- Shop catalog at `/shop/` for e-commerce
|
||||
- Storefront catalog at `/storefront/` for e-commerce
|
||||
- Clean navigation between the two
|
||||
|
||||
## Technical Implementation
|
||||
@@ -273,27 +273,27 @@ This allows:
|
||||
### Route Handlers (main.py)
|
||||
|
||||
```python
|
||||
# Store root - serves landing page or redirects to shop
|
||||
# Store root - serves landing page or redirects to storefront
|
||||
@app.get("/")
|
||||
@app.get("/stores/{store_code}/")
|
||||
@app.get("/storefront/{store_code}/")
|
||||
async def root(request: Request):
|
||||
if has_landing_page():
|
||||
return render_landing_page()
|
||||
else:
|
||||
return redirect_to_shop()
|
||||
return redirect_to_storefront()
|
||||
|
||||
# Shop routes
|
||||
@app.include_router(shop_pages.router, prefix="/shop")
|
||||
@app.include_router(shop_pages.router, prefix="/stores/{store_code}/shop")
|
||||
# Storefront routes
|
||||
@app.include_router(storefront_pages.router, prefix="/storefront")
|
||||
@app.include_router(storefront_pages.router, prefix="/storefront/{store_code}")
|
||||
```
|
||||
|
||||
### Context Calculation (shop_pages.py)
|
||||
### Context Calculation (storefront_pages.py)
|
||||
|
||||
```python
|
||||
def get_shop_context(request: Request):
|
||||
def get_storefront_context(request: Request):
|
||||
base_url = "/"
|
||||
if access_method == "path":
|
||||
base_url = f"/stores/{store.subdomain}/"
|
||||
base_url = f"/storefront/{store.subdomain}/"
|
||||
|
||||
return {
|
||||
"base_url": base_url,
|
||||
@@ -308,11 +308,11 @@ def get_shop_context(request: Request):
|
||||
The navigation system creates a **two-tier structure**:
|
||||
|
||||
1. **Landing Page** (`/`) - Marketing, branding, store story
|
||||
2. **Shop** (`/shop/`) - E-commerce, products, cart, checkout
|
||||
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 shop
|
||||
- Or skip the landing page and go straight to the storefront
|
||||
|
||||
All while maintaining clean, consistent navigation throughout the experience.
|
||||
|
||||
Reference in New Issue
Block a user