Module Toggle
Data Entity
Description
Per-organization configuration record that enables or disables a functional area (module) for a tenant. Each row represents one area ID toggled on or off for one organization, forming the runtime module registry consumed by mobile clients, the admin portal, and every API endpoint that belongs to a toggleable module.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Surrogate primary key | PKrequiredunique |
organization_id |
uuid |
Foreign key to organizations. Identifies which tenant this toggle belongs to. | required |
module_id |
string |
Canonical area ID from the area taxonomy (e.g. expense-reimbursement, encrypted-assignments). Must match a known area ID; never a free-form string. | required |
is_enabled |
boolean |
Whether the module is currently active for this organization. False means the module's UI, API endpoints, and navigation are suppressed for this tenant. | required |
is_always_on |
boolean |
Marks non-toggleable core modules (e.g. authentication-access-control, home-navigation for mobile; admin-organization for admin portal). Always-on modules cannot be disabled through the Feature Toggles UI. | required |
depends_on |
json |
Array of module_id strings that must also be enabled when this module is enabled. Declared dependencies are enforced at toggle time; enabling this module implicitly enables all listed modules. | - |
config |
json |
Module-level configuration flags that vary within the module without toggling the whole area (e.g. {speech_to_text_enabled: true, receipt_threshold_nok: 100} for expense-reimbursement). Null when the module has no per-org config. | - |
enabled_at |
datetime |
Timestamp when the module was last enabled. Null if never enabled. | - |
enabled_by |
uuid |
User ID (Org Admin or Global Admin) who last enabled the module. Null if never enabled or set by system. | - |
disabled_at |
datetime |
Timestamp when the module was last disabled. Null if never disabled. | - |
disabled_by |
uuid |
User ID who last disabled the module. Null if never disabled. | - |
created_at |
datetime |
Row creation timestamp, set once on insert. | required |
updated_at |
datetime |
Last modification timestamp, updated on every write. | required |
Database Indexes
idx_module_toggles_org_module
Columns: organization_id, module_id
idx_module_toggles_org_enabled
Columns: organization_id, is_enabled
idx_module_toggles_module_id
Columns: module_id
Validation Rules
module_id_known
error
Validation failed
organization_exists
error
Validation failed
depends_on_valid_ids
error
Validation failed
config_schema_valid
error
Validation failed
actor_is_org_or_global_admin
error
Validation failed
Business Rules
always_on_immutable
Modules with is_always_on = true cannot be toggled off. Any update attempt that sets is_enabled = false on an always-on row is rejected with an error before the write reaches the database.
dependency_cascade_enable
When a module is enabled, all module IDs listed in its depends_on array are also enabled for the same organization. The cascade is applied in the same transaction so the enabled set is always consistent.
dependency_block_disable
A module cannot be disabled if another currently-enabled module declares it in its depends_on. The admin UI must show which dependent modules would need to be disabled first.
admin_organization_circular_guard
The admin-organization module is always-on for the Admin Web Portal because it hosts the Feature Toggles UI itself. Disabling it would remove the only surface for re-enabling modules.
toggle_audit
Every enable or disable action is recorded in the organization's audit log with actor, timestamp, module_id, and previous state.
bootstrap_response_reflects_enabled_set
The session bootstrap API response for any user must include the current enabled module set for their organization. Clients use this set exclusively to assemble navigation and entry points; no client-side hardcoding of which modules exist.
api_endpoint_module_gate
Every API endpoint that belongs to a toggleable module checks the organization's enabled set before executing. A request to a disabled module's endpoint returns 403 regardless of the user's role.
one_row_per_org_module
The combination (organization_id, module_id) must be unique. Duplicate rows are prevented by the unique index and rejected at the service layer before insert.