Role
Data Entity
Description
Defines the named permission profiles available on the Meander platform. Each role encodes a fixed set of capabilities and access boundaries. Roles are platform-defined (not org-defined) and drive RBAC enforcement across both the mobile app and the admin portal.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Surrogate primary key. UUID v4 generated at seed time. Roles are seeded at deployment and rarely created at runtime. | PKrequiredunique |
slug |
string |
Machine-readable identifier used in code and API responses. One of the four canonical platform roles. | requiredunique |
display_name |
string |
Human-readable role name shown in the UI. English canonical name; organization-specific labels are handled via terminology_overrides. | required |
description |
text |
Prose description of the role's purpose, responsibilities, and access boundaries. Used in admin UI and onboarding. | - |
product_access |
json |
Array of products this role can access. Values: 'mobile_app', 'admin_portal'. Sales website has no auth. | required |
permissions |
json |
Flat list of permission strings that RBAC middleware enforces. E.g. ['activity:create', 'expense:read', 'user:manage']. Canonical source of truth for all access checks. | required |
can_act_as_proxy |
boolean |
Whether users with this role are permitted to register activities on behalf of other users. True for coordinator and global_admin. | required |
can_view_cross_org |
boolean |
Whether users with this role can access data across multiple organizations. True only for global_admin. | required |
requires_org_context |
boolean |
Whether a valid organization context (org_id) is required for the user to authenticate and operate. False only for global_admin. | required |
is_assignable_by_org_admin |
boolean |
Whether an org_admin can assign this role to users within their organization. False for global_admin (assigned only by platform operators). | required |
sort_order |
integer |
Display ordering in admin UIs. Lower value = higher prominence. 1=peer_mentor, 2=coordinator, 3=org_admin, 4=global_admin. | required |
is_active |
boolean |
Soft-disable flag. Inactive roles cannot be assigned to new users; existing assignments are unaffected until re-evaluated. | required |
created_at |
datetime |
Row creation timestamp. Set at seed time. | required |
updated_at |
datetime |
Last modification timestamp. Updated whenever permissions or flags change. | required |
Database Indexes
idx_roles_slug
Columns: slug
idx_roles_is_active
Columns: is_active
idx_roles_sort_order
Columns: sort_order
Validation Rules
slug_must_be_canonical
error
Validation failed
slug_is_immutable
error
Validation failed
permissions_is_valid_json_array
error
Validation failed
product_access_is_valid_json_array
error
Validation failed
display_name_not_empty
error
Validation failed
sort_order_positive_integer
warning
Validation failed
can_view_cross_org_only_global_admin
error
Validation failed
Business Rules
platform_defined_roles_only
Only the four canonical roles (peer_mentor, coordinator, org_admin, global_admin) may exist. Organizations cannot create custom roles. All role management is handled by platform operators via seeded data.
global_admin_not_org_assignable
Org admins cannot assign the global_admin role. is_assignable_by_org_admin must be false for global_admin, and the role-assignment-service must reject any attempt by a non-platform operator to assign it.
global_admin_no_org_data_access
Users with the global_admin role must not have access to an organization's operational data by default. They manage the platform, not tenant content. requires_org_context = false and can_view_cross_org = true are both required.
peer_mentor_mobile_only
Users assigned only the peer_mentor role must be redirected away from the admin portal. product_access for peer_mentor does not include 'admin_portal'. The role-screen-router enforces this on session establishment.
coordinator_dual_product_access
Coordinators have access to both the mobile app and the admin portal. Both 'mobile_app' and 'admin_portal' must appear in product_access for this role.
proxy_registration_requires_role_flag
Only roles where can_act_as_proxy = true may register activities on behalf of other users. The proxy-activity-service and bulk-activity-service must check this flag before accepting proxy submissions.
inactive_role_blocks_new_assignments
If is_active = false, no new user_roles records may reference this role. Existing assignments are not automatically revoked, but the role-assignment-service must reject new assignment attempts.
permissions_are_additive
A user with multiple active role assignments (e.g., peer_mentor + coordinator in different orgs) accumulates permissions. RBAC enforcement must union all active role permissions for the current session context.