Cache System Overview

Introduction

The Planet Cache System is an event-driven caching solution designed to automatically update cached data based on business events. It follows a clean architecture pattern with strict separation of concerns and implements the Strategy pattern for different processing modes.

This system solves common caching challenges by:

• Automatically updating cache when related data changes
• Maintaining data consistency across the application
• Providing type-safe access to cached data
• Supporting both synchronous and asynchronous processing
• Protecting cache data from direct manipulation

Key Features

• Event-Driven Architecture: Cache updates automatically in response to business events
• Type Safety: Strong typing throughout the system with proper validation
• Field Protection: Prevents direct manipulation of cache data
• Data Casting: Ensures data is stored and retrieved with the correct types
• Sync/Async Processing: Flexible processing modes for different performance needs
• Clean Architecture: Strict separation of concerns with well-defined interfaces
• Robust Error Handling: Comprehensive error management and logging

Core Components

Interfaces and Contracts

• CacheableModel: Interface that models must implement to participate in caching
• BusinessEvent: Interface for events that trigger cache updates
• CacheHandler: Interface for cache data generators
• CacheInitializerInterface: Interface for cache data initializers

DTOs and Collections

• CacheConfigDTO: Configuration for each cache key with validation
• CacheConfigCollection: Typed collection of cache configurations
• CacheEventDTO: Event data passed to cache handlers with metadata
• CacheHandlerResult: Single cache result with entity ID and data
• CacheHandlerResultCollection: Typed collection of cache handler results

Core Services

• CacheManager: Main orchestrator implementing Strategy pattern
• CacheEventSubscriber: Event listener with robust error handling
• ModelDiscoveryService: Efficient model discovery with caching
• CacheStorageService: Database operations with transaction safety
• CacheCastingService: Handles type casting for cache data

Architecture Diagram

Event Flow

1. Discovery Phase (One-time):

   • System discovers all models implementing CacheableModel
   • Collects cache configurations
   • Builds event-to-model mapping
   • Caches mapping for performance

2. Event Processing:

   • CacheEventSubscriber listens to BusinessEvents
   • Matches event to related models
   • Creates CacheEventDTO from event data
   • Calls appropriate cache handlers
   • Processes results (sync/async)

3. Cache Handler Execution:

   • Receives CacheEventDTO
   • Processes business logic
   • Returns CacheHandlerResultCollection
   • Contains entity IDs and corresponding cache data

4. Storage:

   • Updates model's cache JSON column
   • Handles sync/async modes
   • Maintains data integrity

Next Steps

Explore the following sections to learn more about the Cache System:

• Implementation Guide - How to implement the cache system in your models
• Field Protection - How the system protects cache data from direct manipulation
• Data Casting - Type casting features for cache data
• Initializer Standards - Standards for cache initializers
• Best Practices - Recommended patterns and approaches
• Troubleshooting - Common issues and solutions