┌─────────────────────────────────────────────────────────────────┐
│                         MEDUSA V2                               │
│                                                                 │
│  Admin Action                                                   │
│       │                                                         │
│       ▼                                                         │
│  Event Bus ──► Subscriber/Hook ──► Try immediately             │
│                                        │                        │
│                                   ┌────┴──────┐                 │
│                                   │  Success  │  ✓ done         │
│                                   │  Failure  │──► Redis Queue  │
│                                   └───────────┘       │         │
│                                               Scheduled Job     │
│                                               (every 5 min)     │
│                                                   │             │
└───────────────────────────────────────────────────┼─────────────┘
                                                    │ REST API
                                                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                         STRAPI V5                               │
│                                                                 │
│   Products / Variants / Options / Option Values                 │
│   Product Categories / Product Types                           │
│                                                                 │
│   Webhook (entry.update) ──────────────────────────────────────►│
│                                          Medusa /webhooks/strapi│
└─────────────────────────────────────────────────────────────────┘

POST /admin/products
    │
    ▼
product.created event
    │
    ▼
Subscriber: wait 2s (DB relations commit) → run createProductInStrapiWorkflow
    │
    ├─ success → done ✓
    └─ failure → push to Redis queue with attempts: 1
                      │
                      ▼ (within 5 minutes)
                 Scheduled Job retries → up to 3 more attempts → dead letter

Workflow steps:
    ├─ useQueryGraphStep (fetch product with options, variants, images, categories, type)
    ├─ uploadImagesToStrapiStep
    ├─ resolveCategoryDocumentIdsStep (Medusa category IDs → Strapi documentIds)
    ├─ resolveTypeDocumentIdStep (Medusa type_id → Strapi documentId)
    ├─ createProductInStrapiStep (with categories + type linked)
    ├─ updateProductMetadataStep (save strapi_id, strapi_document_id)
    ├─ createOptionsInStrapiStep
    ├─ createOptionValuesInStrapiStep
    ├─ updateProductOptionValuesMetadataStep
    ├─ createVariantsInStrapiStep (with option_values linked)
    └─ updateProductVariantsMetadataStep

DELETE /admin/products/:id
    │
    ▼
deleteProductsWorkflow.productsDeleted hook
    │
    ├─ findByMedusaId → strapiService.delete(product) → success ✓
    └─ failure → push to Redis queue → retry up to 3 more times
       (Strapi product cascade deletes variants + options automatically)

PATCH /admin/products/:id
    │
    ▼
product.updated event
    │
    ├─ Check strapi_sync_source === "strapi" AND flag age < 5s → skip (loop prevention)
    ├─ Sync title, subtitle, description to Strapi
    ├─ Resolve category documentIds → sync categories to Strapi
    ├─ Read type_id → resolve Strapi documentId → sync type to Strapi
    └─ Check for new options / option values → create missing ones in Strapi

Strapi editor updates title/subtitle/description
    │
    ▼
Strapi webhook → POST /webhooks/strapi
    │
    ▼
handleStrapiWebhook()
    │
    ├─ Set strapi_sync_source: "strapi" + strapi_sync_at: Date.now() on product metadata
    └─ Update title/subtitle/description in Medusa
         │
         ▼
    product.updated fires → subscriber checks flag age (< 5s) → clears flag → skips outbound sync

POST/PATCH /admin/product-categories
    │
    ▼
product-category.created / product-category.updated event
    │
    ▼
syncCategoryToStrapiWorkflow
    │
    ├─ Fetch category (id, name, description, parent_category_id)
    ├─ If has parent → findByMedusaId(parent) → resolve parent documentId
    ├─ findByMedusaId(category) → exists? → update : create
    └─ success ✓ / failure → Redis queue retry

DELETE /admin/product-categories/:id
    │
    ▼
product-category.deleted event
    │
    └─ findByMedusaId → strapiService.delete(category) → success ✓

POST/PATCH /admin/product-types
    │
    ▼
product-type.created / product-type.updated event
    │
    ▼
syncProductTypeToStrapiWorkflow
    │
    ├─ Fetch type (id, value)
    ├─ findByMedusaId(type) → exists? → update : create
    └─ success ✓ / failure → Redis queue retry

DELETE /admin/product-types/:id
    │
    ▼
product-type.deleted event
    │
    └─ findByMedusaId → strapiService.delete(type) → success ✓

POST /admin/products/:id/options
    │
    ▼
product-option.created event
    │
    ├─ Check product has strapi_id → if not, skip (workflow handles it)
    ├─ Create option in Strapi
    ├─ Save strapi_id to product metadata strapi_options map
    └─ Create all initial option values in Strapi with strapi_id saved to metadata

Edit option in Admin (add new value)
    │
    ▼
product-option.updated event
    │
    ├─ Detect new values (no strapi_document_id in metadata)
    ├─ Create option value in Strapi
    └─ Save strapi_id, strapi_document_id to option value metadata

Edit option in Admin (remove value)
    │
    ▼
product-option.updated event
    │
    ├─ Fetch Strapi option with populate: ["values"]
    ├─ Compare Strapi values vs current Medusa values
    └─ Delete stale Strapi values (medusaId not in Medusa anymore)

DELETE /admin/products/:id/options/:optionId
    │
    ▼
deleteProductOptionsWorkflow.productOptionsDeleted hook
    │
    ├─ findByMedusaId → strapiService.delete(option) → success ✓
    │   (Strapi cascades to delete option values automatically)
    └─ failure → push to Redis queue → retry up to 3 more times

Add variant to existing product
    │
    ▼
product-variant.created event
    │
    ├─ Check product has strapi_id → if not, skip (initial workflow handles it)
    ├─ Resolve each option value's strapi_id from metadata
    ├─ Create variant in Strapi with option_values linked
    └─ Save strapi_id, strapi_document_id to variant metadata

Medusa → Strapi:
PATCH /admin/products/:id/variants/:variantId
    │
    ▼
product-variant.updated
    │
    ├─ Wait 1.5s (allow option-created subscriber to finish saving strapi_ids)
    ├─ Resolve all current option values' strapi_ids
    └─ Sync title, sku, option_values to Strapi

Strapi → Medusa:
Editor updates variant title/sku → webhook → handleStrapiWebhook()
    │
    ├─ Set strapi_sync_source: "strapi" + strapi_sync_at: Date.now() on variant metadata
    └─ Update title/sku in Medusa → loop prevention skips outbound sync

DELETE /admin/products/:id/variants/:variantId
    │
    ▼
deleteProductVariantsWorkflow.productVariantsDeleted hook
    │
    ├─ findByMedusaId → strapiService.delete(variant) → success ✓
    └─ failure → push to Redis queue → retry up to 3 more times

Any sync failure (create, upsert, or delete):

Attempt 1 — immediate (subscriber/hook)            → fail
Attempt 2 — +5 min (job run 1, strapi:sync:queue)  → fail
Attempt 3 — +10 min (job run 2)                    → fail
Attempt 4 — +15 min (job run 3)                    → fail → strapi:sync:dead (1 day TTL)

Strapi webhook → update Medusa with { strapi_sync_source: "strapi", strapi_sync_at: <timestamp> }
    │
    ▼
product.updated / product-variant.updated fires
    │
    ├─ Flag detected AND age < 5s → remove flag → return early (no Strapi sync)
    ├─ Flag detected BUT age ≥ 5s → stale flag, clear it and proceed with sync
    └─ Flag NOT detected → normal Medusa update → sync to Strapi

pnpm strapi:queue              # show status of all queues
pnpm strapi:queue:retry        # move dead items back to queue for retry (resets attempts to 0)
pnpm strapi:queue:clear-dead   # permanently delete all dead items
pnpm strapi:queue:clear-all    # wipe all queues (use with caution)

{
  "strapi_id": 21,
  "strapi_document_id": "yo7mro8ul1316gexx4bpqgsh",
  "strapi_sync_source": "strapi",
  "strapi_sync_at": 1741234567890,
  "strapi_options": {
    "opt_01xxx": { "strapi_id": 5, "strapi_document_id": "def456" },
    "opt_01yyy": { "strapi_id": 6, "strapi_document_id": "ghi789" }
  }
}

{
  "strapi_id": 41,
  "strapi_document_id": "bopc6lm2wundpptptd1m67ua"
}

{
  "strapi_id": 38,
  "strapi_document_id": "t5yvmkjydclb7nfgn1t5cf2v",
  "strapi_sync_source": "strapi",
  "strapi_sync_at": 1741234567890
}

src/api/product-category/
├── content-types/product-category/schema.json
├── controllers/product-category.ts   ← factories.createCoreController(...)
├── routes/product-category.json      ← standard CRUD routes
└── services/product-category.ts      ← factories.createCoreService(...)

# Strapi
STRAPI_API_URL=http://localhost:1337/api
STRAPI_API_TOKEN=your-strapi-api-token
STRAPI_MEDIA_BASE_URL=https://your-minio-domain.com
STRAPI_DEFAULT_LOCALE=en

# MinIO / S3 (shared file storage)
MINIO_ENDPOINT=http://localhost:9002
MINIO_FILE_URL=http://localhost:9002/medusa-uploads
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=miniopassword
MINIO_REGION=us-east-1
MINIO_BUCKET=medusa-uploads

# Redis (already configured for Medusa)
REDIS_URL=redis://localhost:6379