Cache Management

The application uses Redis for caching various types of data to improve performance. This document describes how to manage the cache system (defined in packages/utils/src/cache.ts).

Cache Structure

The cache uses the following key prefixes (CACHE_KEYS in packages/utils/src/cache.ts):

• erp:customers:* - Customer data (CACHE_KEYS.CUSTOMER = 'erp:customers')
• erp:items:* - Product/item related data (CACHE_KEYS.ITEM = 'erp:items')
• erp:shipping:* - Shipping address data (CACHE_KEYS.SHIPPING = 'erp:shipping')

Each entity type has specific sub-patterns:

• Search results: erp:{entity}:search:*
• Individual records: erp:{entity}:{id}

Cache TTLs

Different types of data have different Time-To-Live (CACHE_TTLS in packages/utils/src/cache.ts) values:

Constant	TTL (seconds)	Human-Readable
CUSTOMER_SEARCH	300s	5 minutes
CUSTOMER_DETAIL	600s	10 minutes
CUSTOMER_LIST	900s	15 minutes
ITEM_SEARCH	300s	5 minutes
ITEM_DETAIL	600s	10 minutes
ITEM_PRICE	60s	1 minute
ITEM_LIST	900s	15 minutes
SHIPPING_SEARCH	900s	15 minutes
SHIPPING_DETAIL	1800s	30 minutes
SHIPPING_LIST	3600s	1 hour

Flushing the Cache

The application provides an API endpoint for flushing the cache. This endpoint requires admin privileges.

Authentication

To use the cache flush endpoint, you need to:

1. Be authenticated
2. Have the ‘admin’ role in your user metadata

API Endpoint

POST /api/cache/flush

Request Options

The endpoint accepts the following options in the request body:

1. Flush by pattern:

{
  "pattern": "erp:items:search:*"
}

2. Flush by entity type:

{
  "entity": "ITEM"
}

Valid entity types (CacheEntityType): CUSTOMER, ITEM, SHIPPING

3. Flush entire cache:

{}

Example Usage

Using curl:

# Flush specific pattern
curl -X POST http://localhost:4321/api/cache/flush \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_AUTH_TOKEN}" \
  -d '{"pattern": "erp:items:search:*"}'

# Flush all keys for an entity
curl -X POST http://localhost:4321/api/cache/flush \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_AUTH_TOKEN}" \
  -d '{"entity": "ITEM"}'

# Flush all cache
curl -X POST http://localhost:4321/api/cache/flush \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_AUTH_TOKEN}"

Response Format

Success response:

{
  "success": true,
  "data": {
    "flushed": 42, // number of keys flushed, or "all" for full flush
    "pattern": "erp:items:*" // only present when pattern specified
  }
}

Error response:

{
  "success": false,
  "error": "Error message"
}

Best Practices

1. Selective Flushing: Prefer flushing specific patterns or entities over flushing the entire cache
2. Timing: Avoid flushing frequently accessed caches during peak usage times
3. Monitoring: Monitor the cache hit rates and adjust TTLs accordingly
4. Validation: Always validate that the flush was successful by checking the response

Troubleshooting

Common issues and solutions:

1. Authentication Errors:

   • Ensure you’re including a valid auth token
   • Check that your user has the ‘admin’ role

2. Pattern Not Found:

   • Check that the pattern matches the cache key structure
   • Note that no error is returned if no keys match the pattern

3. Rate Limiting:

   • The endpoint is rate-limited to prevent abuse
   • Wait a few minutes if you receive a 429 response