sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions 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 ## Endpoint Categories
### Shop API (`/shop/`) - Customer-Facing ### Storefront API (`/storefront/`) - Customer-Facing
Multi-tenant shop endpoints with automatic vendor context from middleware: Multi-tenant storefront endpoints with automatic vendor context from middleware:
- **Products**: Browse catalog, search, product details - **Products**: Browse catalog, search, product details
- **Cart**: Shopping cart operations (session-based) - **Cart**: Shopping cart operations (session-based)
- **Orders**: Order placement and history (authenticated) - **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 **API Version:** v1
**Base Path:** `/api/v1/shop` **Base Path:** `/api/v1/storefront`
--- ---
## Overview ## 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 ### Key Features
✅ **Automatic Vendor Detection** - Vendor extracted from Referer header via middleware ✅ **Automatic Vendor Detection** - Vendor extracted from Referer header via middleware
✅ **Multi-Tenant** - Each vendor has isolated customer data ✅ **Multi-Tenant** - Each vendor has isolated customer data
✅ **Session-Based Cart** - No authentication required for browsing/cart ✅ **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 ✅ **RESTful Design** - Standard HTTP methods and status codes
--- ---
## How Vendor Context Works ## 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`) 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/shop/products` 2. **Browser automatically sends Referer header**: `http://localhost:8000/vendors/wizamart/storefront/products`
3. **Middleware extracts vendor** from Referer path/subdomain/domain 3. **Middleware extracts vendor** from Referer path/subdomain/domain
4. **Middleware sets** `request.state.vendor = <Vendor: wizamart>` 4. **Middleware sets** `request.state.vendor = <Vendor: wizamart>`
5. **API endpoint accesses vendor**: `vendor = request.state.vendor` 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 ### 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` - **Subdomain**: `wizamart.platform.com` → extracts `wizamart`
- **Custom domain**: `customshop.com` → looks up vendor by domain - **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. Get paginated list of products for current vendor.
**Endpoint:** `GET /api/v1/shop/products` **Endpoint:** `GET /api/v1/storefront/products`
**Query Parameters:** **Query Parameters:**
@@ -91,7 +91,7 @@ Get paginated list of products for current vendor.
**Request Example:** **Request Example:**
```http ```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 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. 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:** **Path Parameters:**
@@ -141,7 +141,7 @@ Get detailed information for a specific product.
**Request Example:** **Request Example:**
```http ```http
GET /api/v1/shop/products/1 GET /api/v1/storefront/products/1
Referer: http://localhost:8000/vendors/wizamart/shop/products 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. Retrieve cart contents for a session.
**Endpoint:** `GET /api/v1/shop/cart/{session_id}` **Endpoint:** `GET /api/v1/storefront/cart/{session_id}`
**Path Parameters:** **Path Parameters:**
@@ -199,7 +199,7 @@ Retrieve cart contents for a session.
**Request Example:** **Request Example:**
```http ```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 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. 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:** **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. 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:** **Path Parameters:**
@@ -409,7 +409,7 @@ Update the quantity of an existing item in the cart.
Remove a specific item from 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:** **Path Parameters:**
@@ -437,7 +437,7 @@ Remove a specific item from the cart.
Remove all items 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:** **Path Parameters:**
@@ -471,7 +471,7 @@ Order endpoints require customer authentication.
Create a new order (authenticated). Create a new order (authenticated).
**Endpoint:** `POST /api/v1/shop/orders` **Endpoint:** `POST /api/v1/storefront/orders`
**Authentication:** Required (customer token) **Authentication:** Required (customer token)
@@ -520,7 +520,7 @@ Create a new order (authenticated).
Get list of customer's orders (authenticated). Get list of customer's orders (authenticated).
**Endpoint:** `GET /api/v1/shop/orders` **Endpoint:** `GET /api/v1/storefront/orders`
**Authentication:** Required **Authentication:** Required
@@ -556,7 +556,7 @@ Get list of customer's orders (authenticated).
Get details of a specific order (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 **Authentication:** Required
@@ -590,7 +590,7 @@ Get details of a specific order (authenticated).
Create a new customer account. Create a new customer account.
**Endpoint:** `POST /api/v1/shop/auth/register` **Endpoint:** `POST /api/v1/storefront/auth/register`
**Request Body:** **Request Body:**
@@ -629,7 +629,7 @@ Create a new customer account.
Authenticate a customer and receive JWT token. Authenticate a customer and receive JWT token.
**Endpoint:** `POST /api/v1/shop/auth/login` **Endpoint:** `POST /api/v1/storefront/auth/login`
**Request Body:** **Request Body:**
@@ -661,7 +661,7 @@ Authenticate a customer and receive JWT token.
The endpoint also sets an HTTP-only cookie: The endpoint also sets an HTTP-only cookie:
```http ```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:** **Error Responses:**
@@ -675,7 +675,7 @@ Set-Cookie: customer_token=<jwt>; Path=/shop; HttpOnly; SameSite=Lax; Secure
Clear customer session. Clear customer session.
**Endpoint:** `POST /api/v1/shop/auth/logout` **Endpoint:** `POST /api/v1/storefront/auth/logout`
**Response (200 OK):** **Response (200 OK):**
@@ -695,7 +695,7 @@ The endpoint clears the `customer_token` cookie.
Get CMS pages for header/footer navigation. 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):** **Response (200 OK):**
@@ -724,7 +724,7 @@ Get CMS pages for header/footer navigation.
Get full content for a specific page. 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:** **Path Parameters:**
@@ -738,7 +738,7 @@ Get full content for a specific page.
{ {
"slug": "about", "slug": "about",
"title": "About Us", "title": "About Us",
"content": "<p>Welcome to our shop...</p>", "content": "<p>Welcome to our store...</p>",
"meta_description": "Learn about our story", "meta_description": "Learn about our story",
"is_published": true, "is_published": true,
"show_in_header": true, "show_in_header": true,
@@ -793,7 +793,7 @@ All endpoints follow standard HTTP error responses:
## Rate Limiting ## Rate Limiting
All Shop API endpoints are rate limited: All Storefront API endpoints are rate limited:
- **Public endpoints**: 100 requests/minute per IP - **Public endpoints**: 100 requests/minute per IP
- **Authenticated endpoints**: 200 requests/minute per customer - **Authenticated endpoints**: 200 requests/minute per customer
@@ -821,8 +821,8 @@ POST /api/v1/public/vendors/auth/{vendor_id}/customers/login
**New Pattern (Current):** **New Pattern (Current):**
```http ```http
GET /api/v1/shop/products GET /api/v1/storefront/products
POST /api/v1/shop/auth/login POST /api/v1/storefront/auth/login
``` ```
**Key Changes:** **Key Changes:**
@@ -846,7 +846,7 @@ const sessionId = localStorage.getItem('session_id') || crypto.randomUUID();
localStorage.setItem('session_id', sessionId); localStorage.setItem('session_id', sessionId);
// 2. Add product to cart // 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', method: 'POST',
headers: { headers: {
'Content-Type': 'application/json' 'Content-Type': 'application/json'
@@ -865,7 +865,7 @@ console.log('Cart updated:', result.cart);
```javascript ```javascript
// 1. Customer logs in // 1. Customer logs in
const loginResponse = await fetch('/api/v1/shop/auth/login', { const loginResponse = await fetch('/api/v1/storefront/auth/login', {
method: 'POST', method: 'POST',
headers: { 'Content-Type': 'application/json' }, headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ body: JSON.stringify({
@@ -878,7 +878,7 @@ const { access_token } = await loginResponse.json();
localStorage.setItem('customer_token', access_token); localStorage.setItem('customer_token', access_token);
// 2. Place order // 2. Place order
const orderResponse = await fetch('/api/v1/shop/orders', { const orderResponse = await fetch('/api/v1/storefront/orders', {
method: 'POST', method: 'POST',
headers: { headers: {
'Content-Type': 'application/json', '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 | | `cms` | Content pages, media library, themes | Content management |
| `customers` | Customer database, profiles, segmentation | Customer data 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. Optional modules can be **enabled or disabled per platform**. They provide additional functionality that may not be needed by all platforms.
| Module | Dependencies | Description | | 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.) | | `payments` | - | Payment gateway integrations (Stripe, PayPal, etc.) |
| `billing` | `payments` | Platform subscriptions, vendor invoices | | `billing` | `payments` | Platform subscriptions, vendor invoices |
| `inventory` | - | Stock management, locations | | `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. Modules can depend on other modules. When enabling a module, its dependencies are automatically enabled.
``` ```
payments payments
↙ ↘ ↙ ↘
billing orders billing orders ←──┐
↑ │
inventory inventory │ │
↓ ↓ cart │
marketplace marketplace ↘ │
checkout
``` ```
**Dependency Rules:** **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 4. **Phase 4** - Move routes to modules ✅ COMPLETE
5. **Phase 5** - Fix direct model imports ✅ COMPLETE 5. **Phase 5** - Fix direct model imports ✅ COMPLETE
6. **Phase 6** - Delete legacy files ✅ COMPLETE 6. **Phase 6** - Delete legacy files ✅ COMPLETE
7. **Phase 7** - Update documentation 7. **Phase 7** - Update documentation ✅ COMPLETE
--- ---