# Hierarchical Configuration

This project resolves configuration records in a consistent order so that global defaults can be overridden by each tenant and department/location. The main scope levels are:

1. **Super Admin** – records with `NULL` tenant and department identifiers.
2. **Tenant** – records with a specific `tenant_id` and a `NULL` department.
3. **Department/Location** – records with both `tenant_id` and `department_id` set.

When a module requests configuration data the system checks for matches at the most specific level first. If nothing is found it falls back to the broader scopes.

## Inheritance Examples

### Forms
Form metadata is stored in the `forms` table with each record containing an
`elements` JSON column describing its fields. `FormConfigService` searches for a
matching form at the department level first, then tenant and finally the super
scope. Legacy rows in `form_definitions` are still consulted for backward
compatibility so department records override tenant or global forms if the
`base_form_id` matches.

### Workflows
`WorkflowEngine` loads active workflows using the same precedence. Department level workflows run before tenant level ones, which run before any global workflows. This allows counsels or departments to customise automated actions without affecting others.

### Page Configs and UI Actions
`ConfigResolver` centralises fetching of page layouts and UI actions. It returns the row matching the department and tenant first, then falls back to tenant or super records. Only one entry per `action_key` is returned, so department specific actions replace tenant or super entries with the same key.

### Settings
`SettingsService` resolves configuration values stored in `department_settings`, `tenant_settings` and `super_settings` tables. The helper checks the department then tenant tables before using the global setting or a provided default.

These services work together to provide consistent override behaviour across the application.