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

refactor: rename public routes and templates to platform

Browse Source 
Complete the public -> platform naming migration across the codebase.
This aligns with the naming convention where "platform" refers to
the marketing/public-facing pages of the platform itself.

Changes:
- Update all imports from public to platform modules
- Update template references from public/ to platform/
- Update route registrations to use platform prefix
- Update documentation to reflect new naming
- Update test files for platform API endpoints

Files affected:
- app/api/main.py - router imports
- app/modules/*/routes/*/platform.py - route definitions
- app/modules/*/templates/*/platform/ - template files
- app/modules/routes.py - route discovery
- docs/* - documentation updates
- tests/integration/api/v1/platform/ - test files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2026-02-02 18:49:39 +01:00
parent 967f08e4ba
commit fb8cb14506
44 changed files with 980 additions and 327 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/architecture/api-consolidation-proposal.md
View File

@@ -7,7 +7,7 @@
## Executive Summary
The platform currently has **two parallel API structures** for shop/customer-facing endpoints:
1. **Original:** `/api/v1/public/vendors/{vendor_id}/*`
1. **Original:** `/api/v1/platform/vendors/{vendor_id}/*`
2. **New:** `/api/v1/shop/*`
This divergence creates confusion, maintenance overhead, and potential bugs. This document analyzes the situation and proposes a consolidation strategy.
@@ -16,19 +16,19 @@ This divergence creates confusion, maintenance overhead, and potential bugs. Thi
## Current State Analysis
### 1. Original Architecture (`/api/v1/public/vendors/`)
### 1. Original Architecture (`/api/v1/platform/vendors/`)
**Location:** `app/api/v1/public/vendors/`
**Location:** `app/api/v1/platform/vendors/`
**Endpoints:**
```
GET /api/v1/public/vendors → List active vendors
GET /api/v1/public/vendors/{vendor_id}/products → Product catalog
GET /api/v1/public/vendors/{vendor_id}/products/{product_id} → Product detail
POST /api/v1/public/vendors/{vendor_id}/cart → Cart operations
GET /api/v1/public/vendors/{vendor_id}/orders → Customer orders
POST /api/v1/public/vendors/auth/login → Customer authentication
POST /api/v1/public/vendors/auth/register → Customer registration
GET /api/v1/platform/vendors → List active vendors
GET /api/v1/platform/vendors/{vendor_id}/products → Product catalog
GET /api/v1/platform/vendors/{vendor_id}/products/{product_id} → Product detail
POST /api/v1/platform/vendors/{vendor_id}/cart → Cart operations
GET /api/v1/platform/vendors/{vendor_id}/orders → Customer orders
POST /api/v1/platform/vendors/auth/login → Customer authentication
POST /api/v1/platform/vendors/auth/register → Customer registration
```
**Characteristics:**
@@ -60,7 +60,7 @@ GET /api/v1/shop/content-pages/{slug} → CMS page content
**Characteristics:**
- ✅ **Vendor-agnostic URLs:** Clean paths without vendor_id
- ✅ **Middleware-driven:** Relies on `VendorContextMiddleware` to inject vendor
- ✅ **Simpler URLs:** `/api/v1/shop/products` vs `/api/v1/public/vendors/123/products`
- ✅ **Simpler URLs:** `/api/v1/shop/products` vs `/api/v1/platform/vendors/123/products`
- ❌ **Incomplete:** Only CMS endpoints implemented
- ❌ **Divergent:** Not consistent with existing public API
@@ -80,7 +80,7 @@ GET /api/v1/shop/content-pages/{slug} → CMS page content
fetch('/api/v1/shop/content-pages/about')
// Products use old pattern
fetch('/api/v1/public/vendors/123/products')
fetch('/api/v1/platform/vendors/123/products')
```
### Confusion
@@ -143,7 +143,7 @@ Developers must remember:
**Implementation:**
- Vendor extracted by `VendorContextMiddleware` from request
- All endpoints use `request.state.vendor` instead of path parameter
- URLs are cleaner: `/api/v1/shop/products` instead of `/api/v1/public/vendors/123/products`
- URLs are cleaner: `/api/v1/shop/products` instead of `/api/v1/platform/vendors/123/products`
**Pros:**
- ✅ Clean, consistent API structure
@@ -162,18 +162,18 @@ Developers must remember:
---
### Option 2: Keep `/api/v1/public/vendors/*` and Deprecate `/api/v1/shop/*`
### Option 2: Keep `/api/v1/platform/vendors/*` and Deprecate `/api/v1/shop/*`
**Approach:** Move CMS endpoints to `/api/v1/public/vendors/{vendor_id}/content-pages/*`
**Approach:** Move CMS endpoints to `/api/v1/platform/vendors/{vendor_id}/content-pages/*`
**Proposed Changes:**
```
# Move CMS endpoints
FROM: /api/v1/shop/content-pages/navigation
TO: /api/v1/public/vendors/{vendor_id}/content-pages/navigation
TO: /api/v1/platform/vendors/{vendor_id}/content-pages/navigation
FROM: /api/v1/shop/content-pages/{slug}
TO: /api/v1/public/vendors/{vendor_id}/content-pages/{slug}
TO: /api/v1/platform/vendors/{vendor_id}/content-pages/{slug}
```
**Pros:**
@@ -240,7 +240,7 @@ async def get_products_legacy(vendor_id: int, db: Session = Depends(get_db)):
fetch('/api/v1/shop/products')
// ❌ BAD
fetch('/api/v1/public/vendors/123/products')
fetch('/api/v1/platform/vendors/123/products')
```
3. **Multi-Tenant Best Practice**: Vendor context should be implicit (from domain/path), not explicit in every API call.
@@ -258,7 +258,7 @@ async def get_products_legacy(vendor_id: int, db: Session = Depends(get_db)):
**Day 1-2: Move Products**
```bash
# Copy and adapt
app/api/v1/public/vendors/products.py → app/api/v1/shop/products.py
app/api/v1/platform/vendors/products.py → app/api/v1/shop/products.py
# Changes:
- Remove vendor_id path parameter
@@ -268,24 +268,24 @@ app/api/v1/public/vendors/products.py → app/api/v1/shop/products.py
**Day 3: Move Cart**
```bash
app/api/v1/public/vendors/cart.py → app/api/v1/shop/cart.py
app/api/v1/platform/vendors/cart.py → app/api/v1/shop/cart.py
```
**Day 4: Move Orders**
```bash
app/api/v1/public/vendors/orders.py → app/api/v1/shop/orders.py
app/api/v1/platform/vendors/orders.py → app/api/v1/shop/orders.py
```
**Day 5: Move Auth**
```bash
app/api/v1/public/vendors/auth.py → app/api/v1/shop/auth.py
app/api/v1/platform/vendors/auth.py → app/api/v1/shop/auth.py
```
### Phase 2: Update Frontend (Week 1)
**Templates:**
- Update all `fetch()` calls in shop templates
- Change from `/api/v1/public/vendors/${vendorId}/...` to `/api/v1/shop/...`
- Change from `/api/v1/platform/vendors/${vendorId}/...` to `/api/v1/shop/...`
**JavaScript:**
- Update any shop-related API client code
@@ -316,10 +316,10 @@ app/api/v1/public/vendors/auth.py → app/api/v1/shop/auth.py
## Code Examples
### Before (Current - `/api/v1/public/vendors`)
### Before (Current - `/api/v1/platform/vendors`)
```python
# app/api/v1/public/vendors/products.py
# app/api/v1/platform/vendors/products.py
@router.get("/{vendor_id}/products")
def get_public_product_catalog(
vendor_id: int = Path(...),
@@ -332,7 +332,7 @@ def get_public_product_catalog(
```javascript
// Frontend
const vendorId = 123;
fetch(`/api/v1/public/vendors/${vendorId}/products`)
fetch(`/api/v1/platform/vendors/${vendorId}/products`)
```
### After (Proposed - `/api/v1/shop`)
@@ -358,14 +358,14 @@ fetch('/api/v1/shop/products') // Vendor context automatic
## Impact Assessment
### Breaking Changes
- All frontend code calling `/api/v1/public/vendors/*` must update
- All frontend code calling `/api/v1/platform/vendors/*` must update
- Mobile apps (if any) must update
- Third-party integrations (if any) must update
### Non-Breaking
- Admin APIs: `/api/v1/admin/*` → No changes
- Vendor APIs: `/api/v1/vendor/*` → No changes
- Vendor listing: Keep `/api/v1/public/vendors` (list all vendors for marketplace)
- Vendor listing: Keep `/api/v1/platform/vendors` (list all vendors for marketplace)
### Risk Mitigation
1. **Deprecation Period**: Keep old endpoints for 2-4 weeks
@@ -383,7 +383,7 @@ If full migration is not approved immediately, we can do a **minimal fix** for t
```python
# Move: app/api/v1/shop/content_pages.py
# To: app/api/v1/public/vendors/content_pages.py
# To: app/api/v1/platform/vendors/content_pages.py
# Update routes:
@router.get("/{vendor_id}/content-pages/navigation")
@@ -402,7 +402,7 @@ If full migration is not approved immediately, we can do a **minimal fix** for t
Should we:
1. ✅ **Consolidate to `/api/v1/shop/*`** (Recommended)
2. ❌ **Keep `/api/v1/public/vendors/*`** and move CMS there
2. ❌ **Keep `/api/v1/platform/vendors/*`** and move CMS there
3. ❌ **Hybrid approach** with both patterns
4. ❌ **Quick fix only** - move CMS, address later
@@ -412,7 +412,7 @@ Should we:
## Appendix: Current Endpoint Inventory
### `/api/v1/public/vendors/*`
### `/api/v1/platform/vendors/*`
- ✅ `vendors.py` - Vendor listing
- ✅ `auth.py` - Customer authentication
- ✅ `products.py` - Product catalog

58
docs/architecture/api-migration-status.md
View File

@@ -174,15 +174,15 @@ Updated all shop templates to use new API endpoints:
| Template | Old Endpoint | New Endpoint | Status |
|----------|-------------|--------------|---------|
| `shop/account/login.html` | `/api/v1/public/vendors/${id}/customers/login` | `/api/v1/shop/auth/login` | ✅ Complete |
| `shop/account/register.html` | `/api/v1/public/vendors/${id}/customers/register` | `/api/v1/shop/auth/register` | ✅ Complete |
| `shop/product.html` | `/api/v1/public/vendors/${id}/products/${pid}` | `/api/v1/shop/products/${pid}` | ✅ Complete |
| `shop/product.html` | `/api/v1/public/vendors/${id}/products?limit=4` | `/api/v1/shop/products?limit=4` | ✅ Complete |
| `shop/product.html` | `/api/v1/public/vendors/${id}/cart/${sid}` | `/api/v1/shop/cart/${sid}` | ✅ Complete |
| `shop/product.html` | `/api/v1/public/vendors/${id}/cart/${sid}/items` | `/api/v1/shop/cart/${sid}/items` | ✅ Complete |
| `shop/cart.html` | `/api/v1/public/vendors/${id}/cart/${sid}` | `/api/v1/shop/cart/${sid}` | ✅ Complete |
| `shop/cart.html` | `/api/v1/public/vendors/${id}/cart/${sid}/items/${pid}` (PUT) | `/api/v1/shop/cart/${sid}/items/${pid}` | ✅ Complete |
| `shop/cart.html` | `/api/v1/public/vendors/${id}/cart/${sid}/items/${pid}` (DELETE) | `/api/v1/shop/cart/${sid}/items/${pid}` | ✅ Complete |
| `shop/account/login.html` | `/api/v1/platform/vendors/${id}/customers/login` | `/api/v1/shop/auth/login` | ✅ Complete |
| `shop/account/register.html` | `/api/v1/platform/vendors/${id}/customers/register` | `/api/v1/shop/auth/register` | ✅ Complete |
| `shop/product.html` | `/api/v1/platform/vendors/${id}/products/${pid}` | `/api/v1/shop/products/${pid}` | ✅ Complete |
| `shop/product.html` | `/api/v1/platform/vendors/${id}/products?limit=4` | `/api/v1/shop/products?limit=4` | ✅ Complete |
| `shop/product.html` | `/api/v1/platform/vendors/${id}/cart/${sid}` | `/api/v1/shop/cart/${sid}` | ✅ Complete |
| `shop/product.html` | `/api/v1/platform/vendors/${id}/cart/${sid}/items` | `/api/v1/shop/cart/${sid}/items` | ✅ Complete |
| `shop/cart.html` | `/api/v1/platform/vendors/${id}/cart/${sid}` | `/api/v1/shop/cart/${sid}` | ✅ Complete |
| `shop/cart.html` | `/api/v1/platform/vendors/${id}/cart/${sid}/items/${pid}` (PUT) | `/api/v1/shop/cart/${sid}/items/${pid}` | ✅ Complete |
| `shop/cart.html` | `/api/v1/platform/vendors/${id}/cart/${sid}/items/${pid}` (DELETE) | `/api/v1/shop/cart/${sid}/items/${pid}` | ✅ Complete |
| `shop/products.html` | Already using `/api/v1/shop/products` | (No change needed) | ✅ Already Updated |
| `shop/home.html` | Already using `/api/v1/shop/products?featured=true` | (No change needed) | ✅ Already Updated |
@@ -196,7 +196,7 @@ grep -r "api/v1/public/vendors" app/templates/shop --include="*.html"
### ✅ Phase 3: Old Endpoint Cleanup (COMPLETE)
Cleaned up old `/api/v1/public/vendors/*` endpoints:
Cleaned up old `/api/v1/platform/vendors/*` endpoints:
**Files Removed:**
- ❌ `auth.py` - Migrated to `/api/v1/shop/auth.py`
@@ -209,14 +209,14 @@ Cleaned up old `/api/v1/public/vendors/*` endpoints:
**Files Kept:**
- ✅ `vendors.py` - Vendor lookup endpoints (truly public, not shop-specific)
- `GET /api/v1/public/vendors/by-code/{vendor_code}`
- `GET /api/v1/public/vendors/by-subdomain/{subdomain}`
- `GET /api/v1/public/vendors/{vendor_id}/info`
- `GET /api/v1/platform/vendors/by-code/{vendor_code}`
- `GET /api/v1/platform/vendors/by-subdomain/{subdomain}`
- `GET /api/v1/platform/vendors/{vendor_id}/info`
**Updated:**
- ✅ `/app/api/v1/public/__init__.py` - Now only includes vendor lookup endpoints
- ✅ `/app/api/v1/platform/__init__.py` - Now only includes vendor lookup endpoints
**Result:** Old shop endpoints completely removed, only vendor lookup remains in `/api/v1/public/vendors/*`
**Result:** Old shop endpoints completely removed, only vendor lookup remains in `/api/v1/platform/vendors/*`
### ⚠️ Phase 4: Deprecation Warnings (SKIPPED - Not Needed)
@@ -252,16 +252,16 @@ Old endpoint cleanup completed immediately (no gradual migration needed):
1. ✅ Removed old endpoint files:
```bash
rm app/api/v1/public/vendors/products.py
rm app/api/v1/public/vendors/cart.py
rm app/api/v1/public/vendors/orders.py
rm app/api/v1/public/vendors/auth.py
rm app/api/v1/public/vendors/payments.py
rm app/api/v1/public/vendors/search.py
rm app/api/v1/public/vendors/shop.py
rm app/api/v1/platform/vendors/products.py
rm app/api/v1/platform/vendors/cart.py
rm app/api/v1/platform/vendors/orders.py
rm app/api/v1/platform/vendors/auth.py
rm app/api/v1/platform/vendors/payments.py
rm app/api/v1/platform/vendors/search.py
rm app/api/v1/platform/vendors/shop.py
```
2. ✅ Updated `/api/v1/public/__init__.py`:
2. ✅ Updated `/api/v1/platform/__init__.py`:
```python
# Only import vendor lookup endpoints
from .vendors import vendors
@@ -280,12 +280,12 @@ Old endpoint cleanup completed immediately (no gradual migration needed):
### Before (Old Pattern)
```
# Verbose - requires vendor_id everywhere
/api/v1/public/vendors/123/products
/api/v1/public/vendors/123/products/456
/api/v1/public/vendors/123/cart/abc-session-id
/api/v1/public/vendors/123/cart/abc-session-id/items
/api/v1/public/vendors/123/customers/789/orders
/api/v1/public/vendors/auth/123/customers/login
/api/v1/platform/vendors/123/products
/api/v1/platform/vendors/123/products/456
/api/v1/platform/vendors/123/cart/abc-session-id
/api/v1/platform/vendors/123/cart/abc-session-id/items
/api/v1/platform/vendors/123/customers/789/orders
/api/v1/platform/vendors/auth/123/customers/login
```
### After (New Pattern)

2
docs/architecture/frontend-structure.md
View File

@@ -452,7 +452,7 @@ All frontends communicate with backend via APIs:
- `/api/v1/admin/*` - Admin APIs
- `/api/v1/vendor/*` - Vendor APIs
- `/api/v1/storefront/*` - Storefront APIs
- `/api/v1/public/*` - Platform APIs
- `/api/v1/platform/*` - Platform APIs
**Benefits:**
- Clear backend contracts