User Role
Data Entity
Description
Defines the named roles available in the Meander platform. Each role controls which products a user may access, what actions they may perform, and what data they may see. Roles are system-defined and seeded at deployment; they are not created by end-users. The four roles are: Peer Mentor, Coordinator, Organization Admin, and Global Admin.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Stable primary key for the role record, referenced by user_role_assignments and JWT claims | PKrequiredunique |
slug |
string |
Machine-readable identifier used in code, JWT claims, and permission checks. One of: peer_mentor, coordinator, org_admin, global_admin | requiredunique |
name |
string |
Human-readable display name shown in admin UI and mobile role switcher (e.g. 'Peer Mentor', 'Coordinator') | requiredunique |
description |
text |
Explanatory text describing the responsibilities and access boundaries of this role, shown in admin onboarding and role assignment UI | - |
product_access |
json |
Array of product identifiers this role may access. Values: 'mobile_app', 'admin_portal'. Global Admin: admin_portal only. Peer Mentor: mobile_app only. Coordinator and Org Admin: both. | required |
permissions |
json |
Structured permission set as a flat map of permission_key → boolean. Consumed by permission-validation-middleware and role-guard-service to gate API routes and UI widgets. Example keys: can_approve_activities, can_register_on_behalf, can_manage_users, can_export_bufdir, can_view_all_orgs | required |
is_system_role |
boolean |
True for all four predefined roles. System roles cannot be deleted or have their slug modified. Reserved for future custom role support. | required |
is_active |
boolean |
Whether this role can currently be assigned to users. Soft-disabling a role prevents new assignments but does not affect existing ones until revoked. | required |
sort_order |
integer |
Display ordering in UI role selectors. Lower numbers appear first. Peer Mentor=1, Coordinator=2, Org Admin=3, Global Admin=4. | required |
created_at |
datetime |
Timestamp when this role record was created (typically at initial database seed) | required |
updated_at |
datetime |
Timestamp of the most recent update to this role's metadata or permissions map | required |
Database Indexes
idx_user_role_slug
Columns: slug
idx_user_role_is_active
Columns: is_active
idx_user_role_sort_order
Columns: sort_order
Validation Rules
slug_in_allowed_set
error
Validation failed
name_not_empty
error
Validation failed
product_access_valid_keys
error
Validation failed
permissions_keys_match_registry
error
Validation failed
sort_order_positive_integer
warning
Validation failed
Business Rules
system_roles_immutable
Roles where is_system_role=true cannot be deleted and their slug cannot be changed. The four predefined roles (peer_mentor, coordinator, org_admin, global_admin) are seeded at deployment and treated as constants by all consuming services.
global_admin_assignment_restricted
The global_admin role can only be assigned by other Global Admins. Org Admins cannot assign or revoke the global_admin role regardless of their own permissions.
mobile_app_roles_only
Users with only the peer_mentor role must be redirected to the no-access screen in the Admin Web Portal. The product_access field is the authoritative source for this check; the mobile app enforces the same boundary in reverse for global_admin.
role_permissions_loaded_at_login
On successful authentication, the user's assigned roles and their permissions maps are loaded, embedded in the JWT claims, and cached in the mobile Permission Store. Role changes take effect at next token refresh, not immediately.
deactivated_role_blocks_new_assignments
If is_active=false, the role cannot be assigned to additional users. Existing user_role_assignment records linked to the deactivated role remain intact and functional until explicitly revoked.
coordinator_dual_product_access
Coordinators have access to both the mobile app and the admin portal. When a coordinator logs in via the mobile app, they see coordinator-specific home content. When they access the admin portal, they see the coordinator-scoped dashboard and reporting views.
profile_switching_multi_role_users
A user may hold multiple roles (e.g., a coordinator who is also a registered peer mentor). The active role governs the current session's UI and data scope. Role switching is supported via profile-switch-service without requiring re-authentication.