> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://cla-demo.postmansolutions.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://cla-demo.postmansolutions.com/_mcp/server.

# Caching Implementation Guidelines

## Standard

Distributed cache: Azure Cache for Redis\
Provisioning: Terraform libraries repo: [az-modules-tf](https://dev.azure.com/CLADevOps/Cloud%20Operations/_git/az-modules-tf)\
Landing zone implementation: [az-adc-lz-tf](https://dev.azure.com/CLADevOps/Cloud%20Operations/_git/az-adc-lz-tf)\
Integration: [framework-nodejs-caching](https://dev.azure.com/CLADevOps/Development/_wiki/wikis/Framework/8680/Caching)\
Pattern: Cache-aside\
TTL: Mandatory for all keys

---

## 1. Infrastructure Requirements

Fluxx should use Azure Cache for Redis provisioned via Terraform modules from:

* `az-modules-tf`
* Implemented within the Fluxx landing zone in `az-adc-lz-tf`

Required characteristics:

* SKU/tier must support:
  * Microsoft Entra ID authentication
  * Disabling access keys
* Access key authentication disabled
* Entra ID authentication enabled
* Private endpoint enforced
* Private DNS configured
* Deployed within Fluxx ALZ networking boundaries

Fluxx services must assume:

* No key-based authentication
* No public endpoint access
* Redis reachable only via private networking
* Identity-based authentication only

---

## 2. Authentication Model

### Azure environments

* Services authenticate using Managed Identity
* Entra ID token is acquired by the framework
* Redis access is authorized via Entra ID

### Local development

* May use username/password only if explicitly configured
* Must not rely on access keys in non-local environments

---

## 3. Framework Integration

### Required package

```ts
import 'framework-nodejs-caching';
```

### Redis client creation

In `src/index.ts`, after AppConfig initialization:

```ts
await frameworkApp.initAppConfig({
  useEnvironmentVariables: true,
});

await frameworkApp.createRedisClient('RedisClient');
```

Configuration source:

* AppConfig key: `FRAMEWORK_REDIS_CONFIG`
* Client selected by matching `"name": "RedisClient"`

Redis configuration must not be hardcoded

---

## 4. AppConfig Structure

Example structure for `FRAMEWORK_REDIS_CONFIG`:

```json
[
  {
    "name": "RedisClient",
    "config": {
      "host": "<redis-host>",
      "port": 6380,
      "usetls": true,
      "resiliencePolicy": {
        "retryOptions": {
          "enabled": true,
          "interval": 200,
          "maxAttempts": 2,
          "intervalType": "regular"
        },
        "circuitBreakerOptions": {
          "enabled": true,
          "errorThresholdTimespan": 5000,
          "errorThresholdPercentage": 25,
          "resetTime": 5000,
          "requestTimeout": 1500
        }
      }
    }
  }
]
```

---

## 5. Application ID Standard

Each Fluxx service must define an `appId`.

Rules:

* Must be lowercase
* Must be prefixed with `fluxx-`
* Must represent the service boundary

Examples:

```
fluxx-file-intake
fluxx-registration
fluxx-extractor
fluxx-statuscheck
```

Recommended implementation:

```ts
export const APP_ID = 'fluxx-file-intake';
```

`appId` must not be derived from Entra client IDs or GUIDs

---

## 6. Key Format Standard

```
{appId}:v1:{resource}:{identifier}
```

Examples:

```
fluxx-file-intake:v1:client:fd394f62-da0e-46f0-977c-65ad2c0c2aee
fluxx-file-intake:v1:status:job-edc26186-a780-46e6-98d3-015da9b656a3
```

Rules:

* `appId` must be first segment
* Version segment required and must follow `appId`
* Resource segment required and singular
* Identifier must uniquely represent the cached object
* TTL required on every key
* No PII stored
* No document payloads stored

### Versioning

If key schema changes:

* Increment version segment (v2, v3) for schema changes
* Allow coexistence during migration
* Remove legacy keys after migration window

---

## 7. Cache Pattern

### Required: Cache-aside

Read flow:

1. Attempt `GET` from Redis
2. On miss, retrieve from authoritative data store
3. Write to Redis with TTL
4. Return value

Write flow:

1. Persist to authoritative data store
2. Invalidate or update cache key

No write-through.
No background refresh unless explicitly designed

---

## 8. TTL Standards

TTL is mandatory. Redis does not enforce TTL automatically

Defined ranges:

* Auth metadata: 5 to 15 minutes
* Config/reference: 5 to 60 minutes
* Status responses: 10 to 60 seconds
* Idempotency keys: 1 to 24 hours aligned to retry window

### TTL Jitter

Apply ±10 percent jitter to avoid synchronized expiration.

---

## 9. Eviction Policy

Preferred policy: `volatile-lru`

Reason:

* Only keys with TTL are eligible for eviction.
* Fluxx requires TTL on all keys.

Keys without TTL will not be evicted under this policy.

---

## 10. Stampede Protection

For hot keys:

* Implement in-process single-flight locking around cache-miss path
* Apply TTL jitter
* Avoid synchronized expirations

---

## 11. Size and Payload Constraints

* Recommended max value size: 256 KB
* Do not cache large JSON payloads
* Do not cache document contents
* Prefer caching identifiers over full objects
* Avoid high-cardinality keys without TTL

---

## 12. Kubernetes Client Best Practices

* Stagger pod startup to avoid simultaneous connection spikes
* Avoid reconnection storms during rolling deployments
* Ensure sufficient CPU and memory for pods
* Reuse Redis connections via the framework client
* Avoid excessive connection churn

---

## 13. Connection and Resilience

* Use framework resiliencePolicy configuration
* Limit retry attempts
* Fail fast on sustained outages
* Services must degrade safely on Redis failure
* Redis outages must not corrupt workflow state

---

## 14. Memory Constraints (In-Pod)

Redis is the shared cache layer

In-pod memory caching:

* Only request-scoped memoization
* Strict size bounds required
* Micro-TTL only
* Must not affect correctness

Each service must:

* Define container memory limits
* Avoid unbounded maps
* Monitor heap usage
* Handle OOM restarts safely

---

## Definition of Done for Redis Adoption

* Azure Cache for Redis provisioned via `az-modules-tf`
* Implemented within Fluxx landing zone in `az-adc-lz-tf`
* SKU supports Entra ID and disabled access keys
* Private endpoint connectivity validated
* `RedisClient` created via framework
* AppConfig entry defined
* All cache writes include TTL
* Keys follow naming convention
* No PII stored in Redis
* Services operate correctly with cold cache