# Customer settings freshness

Status: Draft. Illustrative example for a hypothetical service; see the open questions below.

Read [the glossary](glossary.md) and [ADR-001](adr-001-shared-customer-settings.md) before planning an implementation.

## Problem

The request handler and scheduled worker need customer settings. Separate caches would allow them to return different settings for the same customer and duplicate the freshness rules and fallback behaviour.

## Scope

Provide a common read path for both callers. The source database remains authoritative. This change does not redesign the settings write API.

## Expected behaviour

Both callers use the same customer settings provider, keyed by `customer_id`.

After a settings update, neither caller may return the previous value once the freshness window ends. Cache hits do not extend the freshness window. The provider must prevent delayed cache writes from extending it.

If the cache is unavailable, the provider reads the source database. If neither the cache nor the source database is available, the provider returns an explicit error. It must not substitute default settings or settings belonging to another customer.

## Acceptance examples

- After a settings update for customer A, both callers observe the updated value within five minutes.
- Updating customer A leaves customer B's settings unchanged.
- A continuous stream of cache hits does not extend the freshness window.
- A delayed cache write of an old value does not extend the freshness window.
- If the cache is unavailable, both callers read the source database.
- If both the cache and source database are unavailable, both callers receive an explicit error.
- A failed settings transaction does not become visible through the provider.

## Operational checks

Before release, the engineers responsible for the source database confirm the expected fallback load and agree on a safe limit. Record the load evidence and the limit in this document. These values are unresolved in this example.

The implementation exposes cache hits, misses, database fallback, and read failures. Reviewers check the behaviour of both callers during a cache failure.

If rollout causes unacceptable database load, disable the affected feature or pause the scheduled worker. The operational procedure for this is not yet agreed. Reverting to separate caches for each caller is not an agreed rollback.

## Work split

One engineer implements the customer settings provider. Other engineers integrate the request handler and scheduled worker after agreeing on the provider interface.

Every implementation task includes these documents. If implementation reveals a conflict or a new architectural choice, return it to the affected engineers and update the agreement before proceeding with that choice.

## Questions for the joint specification session

- Does the product owner accept a five-minute freshness window for both callers?
- Can the source database handle the expected fallback load, and what limit will we enforce?
- Which failure behaviour should each caller expose to its user or operator?
- What is the operational procedure if rollout causes unacceptable database load?
- Which engineer owns each implementation task and operational check?

The team must answer these questions before treating this example as a specification ready for implementation.