Skip to content

Latest commit

 

History

History
161 lines (132 loc) · 4.54 KB

DISCOVER_CACHE_SYSTEM.md

File metadata and controls

161 lines (132 loc) · 4.54 KB

Discover Cache System Documentation

Overview

The Discover Cache System implements smart server-side caching for the discovery endpoint with automatic daily updates and fallback mechanisms.

How It Works

1. Smart Caching Strategy

Request for discover data
  ↓
Check if cache exists?
  ├─ YES → Serve cache immediately
  │   ├─ Check if expired (24h)?
  │   │   ├─ NO → Return cache (DONE)
  │   │   └─ YES → Return cache + fetch fresh in background
  │   └─ On fresh data: Compare hash
  │       ├─ Different → Update cache
  │       └─ Same → Reset 24h timer only
  └─ NO → Fetch fresh from API
      └─ Save to cache for next time

2. Cache Storage

  • Location: .cache/discover-cache.json (server filesystem)
  • Metadata: .cache/discover-cache-meta.json
    • lastUpdated: Timestamp of last update
    • hash: SHA-256 hash of data (for change detection)
  • TTL: 24 hours

3. Update Logic

Background Updates

  • Cache is served immediately while being checked
  • If cache is older than 24h, fresh data is fetched in background
  • Hash comparison ensures only actual changes trigger updates
  • Timer resets even if data is unchanged (prevents unnecessary fetches)

Data Integrity

  • All responses are hashed
  • Only saves if hash differs (prevents unnecessary I/O)
  • Metadata tracks both timestamp and hash for optimal updates

4. Implementation Files

/services/discoverCache.service.ts

Core caching service with these functions:

getCachedDiscover()                    // Get cached data
getDiscoverWithCache(fetchFresh)      // Smart fetch with caching
clearDiscoverCache()                  // Manual cache clear

/services/singnifyApi.actions.ts

New server action:

fetchDiscoveryCachedAction(token)     // Uses smart cache

/app/(Main)/browse/browse-content.tsx

Updated to:

  • Import fetchDiscoveryCachedAction
  • Extract and display introductions from discover response
  • Show editorial featured picks section

/app/lib/nextData.ts

Static fallback data with full discover structure:

  • status: API response status
  • message: Success/error message
  • introductions: Editorial featured content array
  • result: Object with numbered recommendation categories

API Response Structure

Discover (No Type) - Full Featured Page

{
  "status": "200",
  "message": "success",
  "introductions": [
    {
      "id": "1",
      "title": "Artist Name",
      "description": "Track description...",
      "image": "https://...",
      "thumb_image": "https://...",
      "middle": "Track Name",
      "button_name": "Listen Here",
      "app_url": "item.detail.html?i=..."
    }
    // ... more introductions
  ],
  "result": {
    "1": [ // Category 1
      { track_name, artist_name, ... }
      // ... more tracks
    ],
    "2": [ // Category 2
      { track_name, artist_name, ... }
      // ... more tracks
    ]
    // ... more categories
  }
}

Benefits

✅ Performance: Cached responses served instantly ✅ Reliability: Fallback to cache if server is down ✅ Freshness: Updated automatically once daily ✅ Efficiency: Only updates on actual data changes ✅ User Experience: No loading delays on repeat visits ✅ Server Load: Reduced API calls with 24h batching

Console Logging

The system logs its actions for debugging:

✅ Discover cache saved successfully
🔄 Serving from cache
⏰ Cache expired (1440 minutes old)
🔃 Updating cache in background...
✓ Cache is still current
📥 No cache found, fetching fresh data...
⚠️ Error occurred, falling back to cache
🗑️ Discover cache cleared

Manual Cache Clearing

import { clearDiscoverCache } from '@/services/discoverCache.service';

// Clear the cache to force fresh fetch
await clearDiscoverCache();

Error Handling

  1. Cache Read Fails → Tries to fetch fresh
  2. Fresh Fetch Fails → Falls back to existing cache
  3. Both Fail → Throws error (client handled)
  4. File System Issues → Gracefully logs and continues

Performance Metrics

  • Cache Hit: ~1ms (filesystem read)
  • Cache Miss: Network latency (API call)
  • Update Check: ~5ms (hash comparison)
  • Memory Impact: ~500KB for typical discover data

Future Enhancements

  • Redis caching for multi-server deployments
  • Incremental cache updates (partial refreshes)
  • Cache versioning for API schema changes
  • Analytics on cache hit rates
  • Configurable TTL per data type