# Redis Cache Migration - Quick Reference

## 🔴 CRITICAL: Redis Keys Requiring Changes

### 1. VideoMedia Cache (MUST CHANGE)

```
Current:  app:video:detail:{videoId} contains categoryId: string
New:      app:video:detail:{videoId} contains categoryIds: string[]
```

**Reason:** Support multi-category association  
**Impact:** All 58,000 video details need update  
**Memory Impact:** +1.2 MB

---

### 2. Category Cache (IMPORTANT CHANGE)

```
Current:  CategoryCachePayload.channelId (remove this)
Current:  CategoryCachePayload.tags: string[] (just names)

New:      CategoryCachePayload (no channelId)
New:      CategoryCachePayload.tags: Array<{id, name}> (JSON objects)
New:      CategoryCachePayload.tagNames: string[] (names only)
```

**Keys Affected:**

- `app:category:all`
- `app:category:by-id:{categoryId}`
- `app:category:with-tags:{categoryId}`

**Impact:** Denormalization of tag data  
**Memory Impact:** +100 KB

---

### 3. Tag Cache (CLEANUP CHANGE)

```
Current:  TagCachePayload { id, name, channelId, categoryId, seq }
New:      TagCachePayload { id, name, categoryId, seq } ← Remove channelId
```

**Keys Affected:**

- `app:tag:all`
- `app:tag:list:{categoryId}`

**Impact:** Simplified structure  
**Memory Impact:** -200 KB (savings)

---

### 4. Channel Cache (ENHANCEMENT)

```
Current:  ChannelCachePayload { id, name, landingUrl, ... }
New:      ChannelCachePayload {
             id, name, landingUrl, ...,
             categories: [{id, name}],  ← NEW
             tags: [{id, name}],        ← NEW
             tagNames: string[]         ← NEW
           }
```

**Keys Affected:**

- `app:channel:all`

**Impact:** Denormalization for quick lookups  
**Memory Impact:** +2.5 KB

---

## 🟢 NEW Redis Keys to Add

### Essential (For Multi-Category Support)

```typescript
// 1. Category-to-Video Index (ZSET - sorted by addedTime)
app:video:category:index:{categoryId}:videos
→ ZSET with video IDs and scores
→ Enables efficient pagination across multiple categories
→ TTL: 2 hours
→ Impact: +12.2 MB

// 2. Video-to-Categories Lookup (SET)
app:video:categories:{videoId}
→ SET of category IDs for a specific video
→ Enables quick lookup of all categories a video belongs to
→ TTL: 24 hours
→ Impact: +7.5 MB

// 3. Category Video Count (STRING)
app:category:video:count:{categoryId}
→ INTEGER count of videos in category
→ For UI display and statistics
→ TTL: 1 hour
→ Impact: +80 KB
```

### Optional (For Search Optimization)

```typescript
// 4. Tag Search Index (SET)
app:tag:search:{prefix}
→ SET of tag IDs matching a prefix
→ For tag autocomplete/search
→ TTL: 2 hours
→ Impact: +0.5-1 MB

// 5. Category Tagnames Flat (STRING)
app:category:tagnames:flat:{categoryId}
→ Space-separated lowercase tag names
→ For efficient substring search without JSON parsing
→ TTL: 24 hours
→ Impact: +400 KB
```

---

## 📊 Memory Impact Summary

| Phase              | Memory    | Change  | Notes                     |
| ------------------ | --------- | ------- | ------------------------- |
| Current            | ~44-49 MB | -       | Before changes            |
| After Core Changes | ~77-82 MB | +33 MB  | Include all new indexes   |
| **Increase**       | **33 MB** | **66%** | Acceptable for 58K videos |

---

## 🔄 Cache Invalidation Strategy

### When CategoryIds Changes (Video Updated)

```typescript
// Invalidate
app:video:detail:{videoId}
app:video:category:index:{categoryId}:videos  // For EACH category
app:video:categories:{videoId}
app:category:video:count:{categoryId}         // For EACH category
```

### When Tag is Updated

```typescript
// Invalidate
app:tag:all
app:tag:list:{categoryId}
app:tag:search:*                    // All prefixes
app:category:tagnames:flat:{categoryId}
app:category:video:count:{categoryId}
```

### When Category is Updated

```typescript
// Invalidate
app:category:all
app:category:by-id:{categoryId}
app:category:with-tags:{categoryId}
app:category:video:count:{categoryId}
app:category:tagnames:flat:{categoryId}
```

---

## ✅ Implementation Checklist

### Phase 1: Core Changes (Days 1-3)

- [ ] Update Prisma migrations (categoryIds, remove channelId fields)
- [ ] Update VideoMedia cache builder for categoryIds
- [ ] Update CategoryCachePayload interface (add tags as JSON, tagNames)
- [ ] Update TagCachePayload interface (remove channelId)
- [ ] Update ChannelCachePayload interface (add categories, tags, tagNames)
- [ ] Update cache builders: Tag, Category, Channel
- [ ] Run migrations and test cache builders

### Phase 2: Indexes (Days 4-6)

- [ ] Create VideoCategoryIndexBuilder
- [ ] Create VideoCategories lookup cache builder
- [ ] Create CategoryVideoCount cache builder
- [ ] Implement index refresh logic (every 2 hours)
- [ ] Add invalidation logic to cache sync service

### Phase 3: Search Optimization (Days 7-8)

- [ ] Add tag search index builder
- [ ] Add category tagnames flat builder
- [ ] Update video service to use new indexes
- [ ] Performance test with 58K+ videos

### Phase 4: Testing & Documentation

- [ ] Load test Redis with 80MB data
- [ ] Update CACHE_SEMANTICS.md
- [ ] Add monitoring and alerting
- [ ] Document migration steps for deployment

---

## 🚀 Deployment Warnings

1. **Data Migration Required**: Update all existing video cache entries
2. **Redis Memory**: Ensure 100+ MB available headroom
3. **Backward Compatibility**: Plan cache invalidation strategy
4. **Monitoring**: Watch Redis memory and CPU during transition
5. **Rollback Plan**: Keep old cache builders available for rollback

---

## 📝 TTL Recommendations

```
Short-lived (refresh on update):
  - app:category:video:count:{id}              → 3600s (1 hour)
  - app:video:category:index:{id}:videos       → 7200s (2 hours)
  - app:tag:search:{prefix}                    → 7200s (2 hours)

Medium-lived (cache 24 hours):
  - app:video:detail:{id}                      → 86400s (24 hours)
  - app:video:categories:{id}                  → 86400s (24 hours)
  - app:category:tagnames:flat:{id}            → 86400s (24 hours)

Long-lived (cache 7 days):
  - app:channel:all                            → 604800s (7 days)
  - app:category:all                           → 604800s (7 days)
  - app:tag:all                                → 604800s (7 days)
```

---

## 🔍 Files to Update

```
libs/common/src/cache/cache-keys.ts
  → Add new key patterns

libs/core/src/cache/tag/tag-cache.builder.ts
  → Remove channelId from TagCachePayload

libs/core/src/cache/category/category-cache.builder.ts
  → Update to include tags as JSON + tagNames
  → Remove channelId

libs/core/src/cache/channel/channel-cache.builder.ts
  → Add categories, tags, tagNames to payload

libs/core/src/cache/video/
  → Create VideoCategoryIndexBuilder
  → Update video detail builder for categoryIds

apps/box-mgnt-api/src/cache-sync/cache-sync.service.ts
  → Add builders for new indexes

CACHE_SEMANTICS.md (libs/common/src/cache/)
  → Document new key patterns and semantics
```

---

**Total Estimated Effort:** 6-9 days  
**Team:** 1-2 backend engineers  
**Risk Level:** Medium (data migration required)