# Caching (Beta)

### 🧠 Caching Strategy

To enhance performance and reduce unnecessary image transformations, **PichaX** is building a two-tier caching system that temporarily stores previously transformed images either **in memory** or/and a global **CDN** network.

This system is **best-effort** and **non-persistent**, meaning **cached images are not guaranteed to be available**. Users should always provide the original image source (`src`) in every request.

***

#### 🔑 Cache Key Generation

Each transformation request must include a unique `id` parameter. This `id`, combined with other request parameters (e.g. `expires`, `params`, `src`), is used to generate a **hash** which acts as the **cache key**.

This approach:

* Uniquely identifies each image transformation.
* Prevents recomputation when the same request is made.
* Enables cache lookups using deterministic keys.

***

#### 💾 Caching Layers

ImageAura will implement the following caching layers:

**1. CDN Cache (Primary)**

* Offers the fastest response times for frequently accessed or recent images.
* Ideal for high-throughput environments.
* Memory size is not limited and caches respect your cache expiry setting in your settings.

**2. In-memory (Secondary)**

* Used as a fallback when CDN caches are not available for any reason. from memory or when persistence across restarts is possible.
* Cached images are stored in memory
* Memory size is limited and subject to eviction policies.

***

#### ⚠️ Disclaimer on Cache Reliability

> ⚠️ **Important:**\
> PichaX does **not guarantee** that transformed images will be cached or retained permanently.
>
> * Cache storage is **opportunistic** and based on system load, memory, and disk availability.
> * Cached entries may be **evicted at any time**.
> * Clients **must always provide the original image source (`src`)** in every request to ensure the transformation can be performed.

***

#### 🔄 Cache Lookup Lifecycle

1. Request arrives with transformation parameters and `id`.
2. A hash key is computed from the request data.
3. The system checks the cache (CDN,).
4. If a cached version exists, it is returned immediately.
5. If not found, in-memory cache is checked.
6. If both caches are not found, the image is fetched, transformed, cached (if possible), and returned.

***

#### 🚧 Development Status

This caching strategy is currently **under development**. Additional features, and manual cache invalidation will be introduced incrementally. Documentation will be updated as these capabilities evolve.