ifixkart-admin/docs/catalog/product-catalog.md
Adithiyan bbd3a3e959 feat: initial commit — full platform snapshot
- Backend: FastAPI app with all models, services, schemas, routes
- Admin Panel: Next.js dashboard with all modules
  (CRM, POS, repairs, warranties, billing, notifications, etc.)
- Ecommerce: storefront (submodule) + product catalog
- AI Agents: .agents/ skill library for Antigravity IDE
- Docs: architecture, billing, notification gateway markdown
- Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
2026-10-13 12:59:47 +05:30

41 lines
1.3 KiB
Markdown

# Product Catalog Architecture (50M Scale)
## Data Model & Hierarchy
The catalog supports up to **50,000,000 SKUs** utilizing 26-character ULID primary keys.
```mermaid
erDiagram
Category ||--o{ Product : contains
Brand ||--o{ Product : manufactures
DeviceSeries ||--o{ Product : applies_to
DeviceModel ||--o{ Product : applies_to
Product ||--|{ ProductVariant : has
ProductVariant ||--|{ VariantAttribute : defines
AttributeType ||--|{ VariantAttribute : types
```
---
## High-Scale Pagination Strategy
For scaling beyond 100,000 items, standard SQL `OFFSET` pagination (e.g. `LIMIT 50 OFFSET 100000`) becomes prohibitively slow ($O(N)$ scan).
### Keyset / Cursor-Based Pagination
All catalog API endpoints enforce Keyset Cursor Pagination using `created_at` and `product_id`:
```sql
SELECT product_id, name, price, created_at
FROM products
WHERE (created_at, product_id) < (:last_created_at, :last_product_id)
ORDER BY created_at DESC, product_id DESC
LIMIT 50;
```
---
## Outbox Catalog Indexing Pipeline
When products or variants are updated in MySQL:
1. An event is written to `outbox_events` (`aggregate_type='PRODUCT'`, `aggregate_id=product_id`, `aggregate_version=v42`).
2. Celery Worker picks up the event, reads `SearchService`, and updates OpenSearch asynchronously.