Cache Management

The application uses Redis for caching various types of data to improve performance. This document describes how to manage the cache system.

Cache Structure

The cache uses the following key patterns:

erp:items:* - Product/item related data
erp:shipping:* - Shipping address data
erp:customer:* - Customer data
erp:order:* - Order data

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 (TTL) values:

Search results: 5 minutes
Individual records: 10 minutes
Inventory data: 1 minute

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:

Be authenticated
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:

Flush by pattern:

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

Flush by entity type:

{
  "entity": "ITEM"
}

Valid entity types: ITEM, SHIPPING, CUSTOMER, ORDER

Flush entire cache:

{}

Example Usage

Using curl:

# Flush specific pattern
curl -X POST http://localhost:3000/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:3000/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:3000/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

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

Troubleshooting

Common issues and solutions:

Authentication Errors:
- Ensure you’re including a valid auth token
- Check that your user has the ‘admin’ role
Pattern Not Found:
- Check that the pattern matches the cache key structure
- Note that no error is returned if no keys match the pattern
Rate Limiting:
- The endpoint is rate-limited to prevent abuse
- Wait a few minutes if you receive a 429 response