# Domain glossary

This file describes the hypothetical customer settings service in the accompanying article. The rules are examples for discussion, not claims about an existing system.

## Customer

A billable organisation, identified by `customer_id`.
A customer can have several users. A user is a person with a login.
`user_id` must not replace `customer_id` in a settings lookup.

## Customer settings

The configuration stored for one `customer_id` in the source database.
"Account configuration" is an older name for this same data.
Use "customer settings" in new specifications and code.

Example: changing customer A's notification setting must not change customer B's setting.

## Source database

The authoritative store for customer settings.

## Caller

A component that reads customer settings: the request handler or the scheduled worker.

## Settings update

A committed change to customer settings in the source database.
A received update request or a failed transaction is not a settings update.

## Freshness window

The maximum time a caller may return the previous settings after a settings update. The window starts when the settings update commits. In this example, the limit is five minutes.

Cache reads do not extend this window. An implementation must account for the time between reading the source database and the cache write, so that a delayed cache write cannot extend the window.

## Customer settings provider

The shared module through which callers read customer settings. The provider owns cache access and database fallback.

The provider is responsible for meeting the freshness window. Callers must not add their own settings caches or keep settings beyond the freshness window.

## Shared settings cache

The single cache for customer settings, used only through the customer settings provider. Keys include `customer_id`.
Changes to cache keys, freshness rules, or fallback behaviour require review by the engineers responsible for both callers.

## Maintaining these definitions

Update this file when a domain decision changes. Review the corresponding specification, ADR, tests, and agent instructions in the same change.
Read these definitions with [the specification](customer-settings-spec.md) and [ADR-001](adr-001-shared-customer-settings.md).