# Settings Hierarchy

## Purpose

The Settings module provides typed, inheritable configuration without mixing business truth
with temporary cache/runtime state.

## Effective precedence

Highest wins:

1. User preference
2. Register override
3. Branch override
4. Company override
5. Tenant override
6. Platform default

A user-level override is evaluated only when the setting definition explicitly allows it.

## Data model

`settings.definitions`
- global setting key catalog
- value type
- platform default
- validation metadata
- sensitivity flag
- user-overridable flag

`settings.overrides`
- tenant-owned override records
- explicit scope type
- scope foreign keys
- JSONB typed value payload
- actor metadata
- partial unique indexes so only one override exists for a setting at a given scope

## Supported types

- boolean
- integer
- decimal
- string
- enum
- json

Type and validation checks happen before persistence.

## Scope selection

Request scope headers:
- `X-Tenant-ID`
- `X-Company-ID`
- `X-Branch-ID`
- `X-Register-ID`

Headers select context; they do not grant authorization.

## API

- `GET /api/v1/settings/definitions`
- `GET /api/v1/settings/effective/{key}`
- `PUT /api/v1/settings/{key}`

Write body:
```json
{
  "scope_type": "branch",
  "value": true
}
```

## Security

Permissions:
- `settings.view`
- `settings.manage`

All endpoints remain behind authentication, active tenant membership, organization scope
resolution, and RBAC permission enforcement.

## Audit

Override writes emit:
- `settings.override.created`
- `settings.override.updated`

## Architectural boundary

The platform default lives on the setting definition.
Tenant APIs cannot mutate platform defaults.
Platform-level administration can be added later through a separate privileged boundary.