# ADR-001: Share the customer settings provider and cache

Status: Proposed. Illustrative example; depends on the open questions in [the specification](customer-settings-spec.md).

## Context

The request handler and scheduled worker read the same customer settings. Both must meet the freshness window defined in [the glossary](glossary.md).

Separate cache implementations would duplicate freshness rules and make it harder to know what each caller returns after a settings update.

## Decision

Both callers use one customer settings provider and one shared settings cache. The provider owns cache keys, freshness rules, and source database fallback. Callers do not add their own settings caches.

Cache entries expire. Measure expiry from the start of the source database read, not from the cache write, so that a slow read or a delayed cache write cannot extend the freshness window. A time-to-live setting alone does not show that the freshness window holds.

Failure behaviour follows the specification. Serving settings beyond the freshness window requires a separate decision.

## Alternatives considered

Separate caches for each caller would let engineers work independently, but would duplicate freshness rules and allow the two callers to disagree about the same data.

Reading the source database on every request would remove cache freshness concerns. The team would need load evidence before choosing that approach.

Event-driven invalidation may reduce stale reads, but adds event delivery and recovery work. Reconsider it if the domain requires a shorter freshness window.

## Consequences

Both callers depend on the same provider interface and cache infrastructure. A cache failure increases source database traffic. Before release, the team must validate fallback capacity and define the operational procedure in the specification.

The team can change freshness rules in one provider. Engineers must still verify both caller integrations and the user-visible behaviour.

## Revisit this decision when

- The product requires a shorter freshness window.
- Measurements show that database fallback is unsafe at the expected load.
- One caller needs different availability or freshness guarantees.

## Instructions for implementation sessions

Read the glossary, specification, and this ADR. State which component the current task changes. Report conflicts, unresolved requirements, or proposed architectural changes to the responsible engineer before implementing them.

During review, provide evidence for the acceptance examples and identify any change to the agreement.