Module Toggle
Data Entity
Description
Per-organization feature area enable/disable flags that control which modules are available to tenants. Each record represents one area's activation state for one organization, forming the module toggle registry that drives runtime navigation, API access, and UI rendering.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
organization_id |
uuid |
Foreign key to organizations table — the tenant this toggle belongs to | required |
area_id |
string |
Canonical area identifier from the area taxonomy (e.g. 'expense-reimbursement', 'encrypted-assignments'). Must match a registered area ID. | required |
is_enabled |
boolean |
Whether this area/module is active for the organization. Clients and API endpoints check this before rendering or executing module functionality. | required |
is_always_on |
boolean |
Marks non-toggleable core modules (e.g. authentication-access-control, admin-organization). Always-on modules cannot be disabled via the admin UI. | required |
dependencies |
json |
Array of area_id strings that must be enabled when this module is enabled. Declared explicitly so the admin UI can auto-enable dependencies rather than failing silently at runtime. | - |
config |
json |
Module-level configuration flags within the area (e.g. receipt_required_threshold, speech_to_text_enabled). Lighter-weight than promoting config flags to separate modules. | - |
enabled_at |
datetime |
Timestamp when the module was last enabled. Null if never enabled. | - |
enabled_by |
uuid |
User ID of the admin who last enabled this module. Foreign key to users. | - |
disabled_at |
datetime |
Timestamp when the module was last disabled. Null if never disabled. | - |
disabled_by |
uuid |
User ID of the admin who last disabled this module. | - |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Last modification timestamp | required |
Database Indexes
idx_module_toggles_org_area
Columns: organization_id, area_id
idx_module_toggles_org_enabled
Columns: organization_id, is_enabled
idx_module_toggles_area_id
Columns: area_id
Validation Rules
area_id_registered
error
Validation failed
organization_exists
error
Validation failed
config_schema_valid
error
Validation failed
dependencies_are_valid_area_ids
error
Validation failed
Business Rules
always_on_modules_immutable
Modules marked is_always_on cannot be disabled. The admin UI must hide the toggle control for these modules. Attempting to set is_enabled=false on an always-on module is rejected.
dependency_auto_enable
When a module is enabled, all area_ids listed in its dependencies array must also be enabled for the same organization. The service enables them implicitly and surfaces this to the admin UI rather than failing silently.
dependency_cascade_disable_guard
When disabling a module, check whether any currently-enabled module declares it as a dependency. If so, warn the admin and require confirmation before disabling.
backend_authoritative
The enabled module set is the source of truth on the backend. Every API endpoint belonging to a module must verify the tenant's module_toggles record before executing. Clients cannot bypass a disabled module by calling the API directly.
one_record_per_org_per_area
Only one module_toggles row may exist per (organization_id, area_id) pair. Upsert semantics on create: if the record exists, update it; never insert a duplicate.
audit_all_changes
Every enable or disable action must produce an audit_logs entry recording the actor (enabled_by / disabled_by), the organization, the area_id, and the new state.
org_admin_scope
Only Organization Admins (for their own org) and Global Admins may modify module toggles. Coordinators and Peer Mentors have no write access to this table.