Intelligent Caching System

Relevant source files

The following files were used as context for generating this wiki page:

• src/core/cache/IntelligentCache.ts
• src/background/services/cache/intelligentCache.ts
• src/common/utils/storage.ts
• src/service-worker.ts
• src/core/monitoring/MarketplaceMonitoringDashboard.ts

The Intelligent Caching System is a multi-layered data persistence and optimization framework within MarketSage. It is designed to reduce latency, manage marketplace data lifecycles, and optimize resource utilization by providing sophisticated caching mechanisms for product details, seller information, price history, and AI models.

The system operates across the core application logic and the background service worker, utilizing both in-memory maps for high-speed access and chrome.storage.local for persistent storage. It integrates closely with the Marketplace Monitoring Dashboard to track performance metrics like cache hit rates and resource utilization.

Core Architecture and Logic

The system is primarily managed by the IntelligentCache class, which implements a Singleton pattern to ensure a unified cache state across the application. It handles data categorization, expiration logic, and capacity management.

Cache Operations Flow

The following diagram illustrates the logic flow when retrieving an item from the intelligent cache, including expiration checks and metric recording.

Maintenance and Eviction

The system maintains a background loop that runs every minute to perform maintenance, specifically removing expired entries. Additionally, it implements a Least Recently Used (LRU) eviction policy when the cache reaches its maximum size.

• Maintenance Loop: Iterates through all entries and removes those where isExpired returns true.
• LRU Eviction: When ensureCapacity detects the cache size exceeds config.maxSize, the system identifies the entry with the oldest lastAccessed timestamp and removes it.

Sources: src/core/cache/IntelligentCache.ts:68-103

Data Categorization and TTL

The system categorizes cached data to apply specific Time-To-Live (TTL) policies. This ensures that volatile data (like product details) is refreshed more frequently than stable data (like price history).

Category	TTL Duration	Purpose
PRODUCT	24 Hours	General product metadata and listings
SELLER	7 Days	Seller ratings, trust scores, and history
PRICE_HISTORY	30 Days	Historical price points for trend analysis

Sources: src/background/services/cache/intelligentCache.ts:2-6

Implementation Components

1. Persistent Storage Utility

The Storage utility acts as the interface between the Intelligent Cache and the browser's chrome.storage.local. It manages specific keys for price history, product caches, and seller ratings.

• cacheProduct(product): Saves products and prunes the cache to only keep the last 100 entries based on timestamp.
• savePriceHistory(productId, price): Appends new price points with ISO timestamps to the historical record.

Sources: src/common/utils/storage.ts:29-52, src/common/utils/storage.ts:16-27

2. Service Worker Integration

The service-worker.ts file implements a low-level caching layer using the Cache API. It focuses on static resources and heavy AI model files to ensure offline availability and faster loading.

3. Performance Monitoring

Cache performance is tracked via the PerformanceTracker (internal to core cache) and exposed through the MarketplaceMonitoringDashboard. Key metrics include:

• Cache Hit Rate: Percentage of successful retrievals vs. misses.
• Resource Utilization: Monitoring storage usage as part of overall system health.

Sources: src/core/monitoring/MarketplaceMonitoringDashboard.ts:63, src/core/monitoring/MarketplaceMonitoringDashboard.ts:446

Code Snippets

LRU Eviction Logic

The implementation of the Least Recently Used logic within IntelligentCache.ts:

private async evictLeastRecentlyUsed(): Promise<void> {
  let oldest: [string, CacheEntry] | null = null;
  
  for (const [key, entry] of this.cache.entries()) {
    if (!oldest || entry.lastAccessed < oldest[1].lastAccessed) {
      oldest = [key, entry];
    }
  }

  if (oldest) {
    await this.remove(oldest[0]);
  }
}

Sources: src/core/cache/IntelligentCache.ts:77-90

Multi-Platform Cache Keys

Storage uses unique keys per product and platform to prevent collisions:

static async savePriceHistory(productId: string, price: Price): Promise<void> {
  const history = await this.getPriceHistory(productId);
  history.push({
    ...price,
    timestamp: new Date().toISOString()
  });

  await chrome.storage.local.set({
    [`${this.PRICE_HISTORY_KEY}_${productId}`]: history
  });
}

Sources: src/common/utils/storage.ts:17-27

Conclusion

The Intelligent Caching System provides a robust foundation for MarketSage's performance. By combining in-memory LRU management, categorical TTL policies, and persistent browser storage, the system ensures that market analysis remain fast and reliable while minimizing redundant network requests to marketplace platforms.