sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: update documentation for storefront module restructure

Browse Source 
- Rename shop-api-reference.md to storefront-api-reference.md
- Update all /api/v1/shop paths to /api/v1/storefront
- Add cart, catalog, checkout modules to module-system.md
- Update API index to reference Storefront API
- Mark Phase 7 as complete in PLAN document

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2026-01-29 23:13:56 +01:00
parent 309104292d
commit 4cddd1a258
4 changed files with 51 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/api/index.md
View File

@@ -26,8 +26,8 @@ All API endpoints are versioned using URL path versioning:
## Endpoint Categories
### Shop API (`/shop/`) - Customer-Facing
Multi-tenant shop endpoints with automatic vendor context from middleware:
### Storefront API (`/storefront/`) - Customer-Facing
Multi-tenant storefront endpoints with automatic vendor context from middleware:
- **Products**: Browse catalog, search, product details
- **Cart**: Shopping cart operations (session-based)
- **Orders**: Order placement and history (authenticated)

72
docs/api/shop-api-reference.md → docs/api/storefront-api-reference.md
View File

@@ -1,31 +1,31 @@
# Shop API Reference
# Storefront API Reference
**Last Updated:** 2025-11-23
**Last Updated:** 2026-01-29
**API Version:** v1
**Base Path:** `/api/v1/shop`
**Base Path:** `/api/v1/storefront`
---
## Overview
The Shop API provides customer-facing endpoints for browsing products, managing cart, placing orders, and customer authentication. All endpoints use **middleware-based vendor context** - no vendor ID in URLs!
The Storefront API provides customer-facing endpoints for browsing products, managing cart, placing orders, and customer authentication. All endpoints use **middleware-based vendor context** - no vendor ID in URLs!
### Key Features
✅ **Automatic Vendor Detection** - Vendor extracted from Referer header via middleware
✅ **Multi-Tenant** - Each vendor has isolated customer data
✅ **Session-Based Cart** - No authentication required for browsing/cart
✅ **Secure Authentication** - JWT tokens with HTTP-only cookies (path=/shop)
✅ **Secure Authentication** - JWT tokens with HTTP-only cookies (path=/storefront)
✅ **RESTful Design** - Standard HTTP methods and status codes
---
## How Vendor Context Works
All Shop API endpoints automatically receive vendor context from the `VendorContextMiddleware`:
All Storefront API endpoints automatically receive vendor context from the `VendorContextMiddleware`:
1. **Browser makes API call** from shop page (e.g., `/vendors/wizamart/shop/products`)
2. **Browser automatically sends Referer header**: `http://localhost:8000/vendors/wizamart/shop/products`
1. **Browser makes API call** from storefront page (e.g., `/vendors/wizamart/storefront/products`)
2. **Browser automatically sends Referer header**: `http://localhost:8000/vendors/wizamart/storefront/products`
3. **Middleware extracts vendor** from Referer path/subdomain/domain
4. **Middleware sets** `request.state.vendor = <Vendor: wizamart>`
5. **API endpoint accesses vendor**: `vendor = request.state.vendor`
@@ -33,7 +33,7 @@ All Shop API endpoints automatically receive vendor context from the `VendorCont
### Supported Vendor Detection Methods
- **Path-based**: `/vendors/wizamart/shop/products` → extracts `wizamart`
- **Path-based**: `/vendors/wizamart/storefront/products` → extracts `wizamart`
- **Subdomain**: `wizamart.platform.com` → extracts `wizamart`
- **Custom domain**: `customshop.com` → looks up vendor by domain
@@ -77,7 +77,7 @@ Cookie: customer_token=<jwt_token>
Get paginated list of products for current vendor.
**Endpoint:** `GET /api/v1/shop/products`
**Endpoint:** `GET /api/v1/storefront/products`
**Query Parameters:**
@@ -91,7 +91,7 @@ Get paginated list of products for current vendor.
**Request Example:**
```http
GET /api/v1/shop/products?skip=0&limit=20&is_featured=true
GET /api/v1/storefront/products?skip=0&limit=20&is_featured=true
Referer: http://localhost:8000/vendors/wizamart/shop/products
```
@@ -130,7 +130,7 @@ Referer: http://localhost:8000/vendors/wizamart/shop/products
Get detailed information for a specific product.
**Endpoint:** `GET /api/v1/shop/products/{product_id}`
**Endpoint:** `GET /api/v1/storefront/products/{product_id}`
**Path Parameters:**
@@ -141,7 +141,7 @@ Get detailed information for a specific product.
**Request Example:**
```http
GET /api/v1/shop/products/1
GET /api/v1/storefront/products/1
Referer: http://localhost:8000/vendors/wizamart/shop/products
```
@@ -188,7 +188,7 @@ Cart operations use session-based tracking (no authentication required).
Retrieve cart contents for a session.
**Endpoint:** `GET /api/v1/shop/cart/{session_id}`
**Endpoint:** `GET /api/v1/storefront/cart/{session_id}`
**Path Parameters:**
@@ -199,7 +199,7 @@ Retrieve cart contents for a session.
**Request Example:**
```http
GET /api/v1/shop/cart/session-abc-123
GET /api/v1/storefront/cart/session-abc-123
Referer: http://localhost:8000/vendors/wizamart/shop/cart
```
@@ -253,7 +253,7 @@ Referer: http://localhost:8000/vendors/wizamart/shop/cart
Add a product to the cart. If the product already exists in the cart, the quantity will be incremented.
**Endpoint:** `POST /api/v1/shop/cart/{session_id}/items`
**Endpoint:** `POST /api/v1/storefront/cart/{session_id}/items`
**Path Parameters:**
@@ -352,7 +352,7 @@ Add a product to the cart. If the product already exists in the cart, the quanti
Update the quantity of an existing item in the cart.
**Endpoint:** `PUT /api/v1/shop/cart/{session_id}/items/{product_id}`
**Endpoint:** `PUT /api/v1/storefront/cart/{session_id}/items/{product_id}`
**Path Parameters:**
@@ -409,7 +409,7 @@ Update the quantity of an existing item in the cart.
Remove a specific item from the cart.
**Endpoint:** `DELETE /api/v1/shop/cart/{session_id}/items/{product_id}`
**Endpoint:** `DELETE /api/v1/storefront/cart/{session_id}/items/{product_id}`
**Path Parameters:**
@@ -437,7 +437,7 @@ Remove a specific item from the cart.
Remove all items from the cart.
**Endpoint:** `DELETE /api/v1/shop/cart/{session_id}`
**Endpoint:** `DELETE /api/v1/storefront/cart/{session_id}`
**Path Parameters:**
@@ -471,7 +471,7 @@ Order endpoints require customer authentication.
Create a new order (authenticated).
**Endpoint:** `POST /api/v1/shop/orders`
**Endpoint:** `POST /api/v1/storefront/orders`
**Authentication:** Required (customer token)
@@ -520,7 +520,7 @@ Create a new order (authenticated).
Get list of customer's orders (authenticated).
**Endpoint:** `GET /api/v1/shop/orders`
**Endpoint:** `GET /api/v1/storefront/orders`
**Authentication:** Required
@@ -556,7 +556,7 @@ Get list of customer's orders (authenticated).
Get details of a specific order (authenticated).
**Endpoint:** `GET /api/v1/shop/orders/{order_id}`
**Endpoint:** `GET /api/v1/storefront/orders/{order_id}`
**Authentication:** Required
@@ -590,7 +590,7 @@ Get details of a specific order (authenticated).
Create a new customer account.
**Endpoint:** `POST /api/v1/shop/auth/register`
**Endpoint:** `POST /api/v1/storefront/auth/register`
**Request Body:**
@@ -629,7 +629,7 @@ Create a new customer account.
Authenticate a customer and receive JWT token.
**Endpoint:** `POST /api/v1/shop/auth/login`
**Endpoint:** `POST /api/v1/storefront/auth/login`
**Request Body:**
@@ -661,7 +661,7 @@ Authenticate a customer and receive JWT token.
The endpoint also sets an HTTP-only cookie:
```http
Set-Cookie: customer_token=<jwt>; Path=/shop; HttpOnly; SameSite=Lax; Secure
Set-Cookie: customer_token=<jwt>; Path=/storefront; HttpOnly; SameSite=Lax; Secure
```
**Error Responses:**
@@ -675,7 +675,7 @@ Set-Cookie: customer_token=<jwt>; Path=/shop; HttpOnly; SameSite=Lax; Secure
Clear customer session.
**Endpoint:** `POST /api/v1/shop/auth/logout`
**Endpoint:** `POST /api/v1/storefront/auth/logout`
**Response (200 OK):**
@@ -695,7 +695,7 @@ The endpoint clears the `customer_token` cookie.
Get CMS pages for header/footer navigation.
**Endpoint:** `GET /api/v1/shop/content-pages/navigation`
**Endpoint:** `GET /api/v1/storefront/content-pages/navigation`
**Response (200 OK):**
@@ -724,7 +724,7 @@ Get CMS pages for header/footer navigation.
Get full content for a specific page.
**Endpoint:** `GET /api/v1/shop/content-pages/{slug}`
**Endpoint:** `GET /api/v1/storefront/content-pages/{slug}`
**Path Parameters:**
@@ -738,7 +738,7 @@ Get full content for a specific page.
{
"slug": "about",
"title": "About Us",
"content": "<p>Welcome to our shop...</p>",
"content": "<p>Welcome to our store...</p>",
"meta_description": "Learn about our story",
"is_published": true,
"show_in_header": true,
@@ -793,7 +793,7 @@ All endpoints follow standard HTTP error responses:
## Rate Limiting
All Shop API endpoints are rate limited:
All Storefront API endpoints are rate limited:
- **Public endpoints**: 100 requests/minute per IP
- **Authenticated endpoints**: 200 requests/minute per customer
@@ -821,8 +821,8 @@ POST /api/v1/public/vendors/auth/{vendor_id}/customers/login
**New Pattern (Current):**
```http
GET /api/v1/shop/products
POST /api/v1/shop/auth/login
GET /api/v1/storefront/products
POST /api/v1/storefront/auth/login
```
**Key Changes:**
@@ -846,7 +846,7 @@ const sessionId = localStorage.getItem('session_id') || crypto.randomUUID();
localStorage.setItem('session_id', sessionId);
// 2. Add product to cart
const response = await fetch(`/api/v1/shop/cart/${sessionId}/items`, {
const response = await fetch(`/api/v1/storefront/cart/${sessionId}/items`, {
method: 'POST',
headers: {
'Content-Type': 'application/json'
@@ -865,7 +865,7 @@ console.log('Cart updated:', result.cart);
```javascript
// 1. Customer logs in
const loginResponse = await fetch('/api/v1/shop/auth/login', {
const loginResponse = await fetch('/api/v1/storefront/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
@@ -878,7 +878,7 @@ const { access_token } = await loginResponse.json();
localStorage.setItem('customer_token', access_token);
// 2. Place order
const orderResponse = await fetch('/api/v1/shop/orders', {
const orderResponse = await fetch('/api/v1/storefront/orders', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
@@ -908,4 +908,4 @@ For live API testing and exploration:
---
**Questions?** See the [API Migration Status](../architecture/api-migration-status.md) or [Shop Architecture Guide](../frontend/shop/architecture.md).
**Questions?** See the [API Migration Status](../architecture/api-migration-status.md) or [Storefront Architecture Guide](../frontend/storefront/architecture.md).

20
docs/architecture/module-system.md
View File

@@ -83,12 +83,15 @@ Core modules are **always enabled** and cannot be disabled. They provide fundame
| `cms` | Content pages, media library, themes | Content management |
| `customers` | Customer database, profiles, segmentation | Customer data management |
### Optional Modules (7)
### Optional Modules (10)
Optional modules can be **enabled or disabled per platform**. They provide additional functionality that may not be needed by all platforms.
| Module | Dependencies | Description |
|--------|--------------|-------------|
| `cart` | - | Shopping cart management, session-based carts |
| `catalog` | - | Customer-facing product browsing |
| `checkout` | `cart`, `orders`, `payments` | Cart-to-order conversion, checkout flow |
| `payments` | - | Payment gateway integrations (Stripe, PayPal, etc.) |
| `billing` | `payments` | Platform subscriptions, vendor invoices |
| `inventory` | - | Stock management, locations |
@@ -283,13 +286,14 @@ The Framework Layer provides infrastructure that modules depend on. These are **
Modules can depend on other modules. When enabling a module, its dependencies are automatically enabled.
```
payments
↙ ↘
billing orders
inventory
↓
marketplace
payments
↙ ↘
billing orders ←──┐
↑ │
inventory │ │
↓ cart │
marketplace ↘ │
checkout
```
**Dependency Rules:**

2
docs/proposals/PLAN_storefront-module-restructure.md
View File

@@ -316,7 +316,7 @@ After migrated to `app/modules/cart/services/cart_service.py`.
4. **Phase 4** - Move routes to modules ✅ COMPLETE
5. **Phase 5** - Fix direct model imports ✅ COMPLETE
6. **Phase 6** - Delete legacy files ✅ COMPLETE
7. **Phase 7** - Update documentation
7. **Phase 7** - Update documentation ✅ COMPLETE
---