Settings → /settings (organisation) · Config Settings → /config-settings (engine)
Nyumba Zetu keeps configuration in one engine with one resolution rule, rather than scattering switches across modules. Understanding the rule explains most "I changed it and nothing happened" questions.
The scope chain
A setting is resolved by walking from the most specific scope to the least, and taking the first value found:
lease → unit → block → branch → organisation → platform default
The most specific scope wins. This is how one scheme runs a stricter collections ladder, a different billing day, or a different late-fee policy without duplicating everything else.
Definitions and overrides
The settings engine has two halves:
| Surface | What it holds |
|---|---|
| Settings Definitions | The catalogue: key, display name, module, category, subcategory, type, default value, and the scopes at which it may be overridden. |
| Settings Overrides | The actual values set at a scope, with what they apply to. |
A definition without an override uses its default. An override without a definition cannot exist.
Reading the definitions list
| Column | Meaning |
|---|---|
| Key | The stable identifier modules read. |
| Display name | The human label. |
| Module / Category / Subcategory | Where the setting belongs and how it groups in the UI. |
| Type | The value's data type. |
| Value | The default. |
| Sort | Display order within its category. |
Reading the overrides list
| Column | Meaning |
|---|---|
| Key | Which setting is overridden. |
| Value | The value at this scope. |
| Org / Branch / Block / Unit / Lease | The scope the override applies to. |
Changing settings in context
You rarely need the raw engine. Most screens with configurable behaviour carry a settings gear that opens the settings for that area, filtered to its category and set at the scope you are working in. Changing a collections threshold from the collections console is safer than finding the key in a list of hundreds.
Where each kind of configuration lives
| Kind | Where |
|---|---|
| Organisation identity, branding, plan | Settings → Account / Property / Plan & billing |
| Users, roles, branch assignment | Settings → Team / Roles. See Users and roles |
| Notification behaviour | Settings → Notifications |
| Security and sessions | Settings → Security |
| Background jobs | Settings → Jobs, and Scheduled tasks |
| Organisation notices | Settings → Notice |
| Running release | Settings → Version |
| Accounts and service types | Chart of accounts |
| Payment matching and allocation order | Payment rules |
| Module availability per scope | Feature flags |
| Message content | Templates |
| Collections thresholds and ladders | Collection strategies |
Changing a setting safely
Decide the scope first
Ask whether this should be true for the organisation, or only for one branch or scheme. Setting at too broad a scope is the most common configuration mistake.
Check for existing overrides
A more specific override will win regardless of what you set.
Make the change
From the contextual settings panel where one exists.
Verify against the behaviour, not the value
Open the screen the setting affects and confirm it did what you expected.
Record why
Settings changes are audited, but the audit records what changed — the reason is worth noting for whoever reads it later.
A caution on inert settings
A setting only does something if a module reads it. When new configuration is introduced, its read-site is wired at the same time — a value that exists but is never read is worse than no setting, because it looks like a control and is not one.
If you set something and behaviour does not change, and there is no more specific override, raise it rather than assuming the value is wrong.
Feature flags versus settings
| Setting | Feature flag | |
|---|---|---|
| Question it answers | "How should this behave?" | "Is this available here?" |
| Typical value | A threshold, a mode, an identifier | On or off |
| Scope chain | Yes | Yes |
The two are converging onto one engine; today, module availability is managed under Feature flags.
Common problems
| Symptom | Cause |
|---|---|
| Change had no effect | A more specific override wins. |
| A setting is missing | It has no definition for your organisation, or you lack the permission to see it. |
| Behaviour differs between two branches | Branch-level overrides — that is the engine working as designed. |
| A module disappeared | Feature flag, not a setting. |