Version #

Version 1

Module Type #

Standard

Status #

Draft

Internal Name #

userRoles

Description #

In Version 1, the User Roles module allows administrators to define and manage system roles. Roles are identified by a numeric “Role Index” that indicates priority—higher indexes represent higher priority. Users can hold multiple roles at once, and each user must have at least one role to ensure they have a baseline set of permissions.

Role management includes creating new roles, updating existing ones, and assigning roles to users or removing them. This module works closely with the User Rights module, which uses each role”s index to determine the effective permissions a user receives when holding multiple roles. The module also supports basic error handling and logs events via webhooks for auditing.

This module has basic error handling.

User Journeys #

To be written.

Authentication #

Authentication for is managed via the Auth Module. Module-to-module communication in Version 1 does not require Authentication. Internal services can call the Admins Module freely.

Schema #

UserRoles #

Name	Type	Internal Name	Description
role_id	UUID/String	userRoles.UserRoles.role_id	A unique identifier for each role.
role_name	String	userRoles.UserRoles.role_name	The name of the role (e.g., “Customer”, “PremiumUser”).
role_description	String	userRoles.UserRoles.role_description	A brief description of the role’s purpose and scope.
role_index	Number	userRoles.UserRoles.role_index	A numeric value representing the role’s priority; higher indexes imply more extensive rights.

UserRolesAssignments #

Name	Type	Internal Name	Description
mapping_id	UUID/String	userRoles.UserRolesAssignments.mapping_id	A unique identifier for each user-role mapping.
user_id	UUID/String	userRoles.UserRolesAssignments.user_id	The identifier for the user in the mapping.
role_id	UUID/String	userRoles.UserRolesAssignments.role_id	The identifier for the role assigned to the user.

Functions #

Name	Endpoint	Description	Internal Name	Input	Response
createRole	/userRoles/create	Creates a new user role in the system.	userRoles.CreateRole	{“RoleName”: “PremiumUser”, “RoleDescription”: “Grants premium access to advanced features”, “RoleIndex”: 2}	{“status”: “success”, “RoleID”: “role-1234”}
updateRole	/userRoles/update	Updates the details of an existing role.	userRoles.CreateRole	{“RoleID”: “role-1234”, “RoleDescription”: “Updated description”, “RoleIndex”: 3}	{“status”: “success”}
deleteRole	/userRoles/delete	Permanently deletes a role from the system.	userRoles.CreateRole	{“RoleID”: “role-1234”}	{“status”: “success”}
softDeleteRole	/userRoles/softDelete	Marks a role as inactive without permanently removing it.	userRoles.CreateRole	{“RoleID”: “role-1234”}	{“status”: “success”}
getRole	/userRoles/get	Retrieves details of a specific role by RoleID.	userRoles.CreateRole	{“RoleID”: “role-1234”}	{“RoleID”: “role-1234”, “RoleName”: “PremiumUser”, “RoleDescription”: “Grants premium access to advanced features”, “RoleIndex”: 2}
listRoles	/userRoles/list	Retrieves a paginated list of all roles, with filtering and sorting.	userRoles.CreateRole	{“page”: 1, “pageSize”: 20}	{“roles”: [/* Array of role objects */], “total”: 50}
assignRoleToUser	/userRoles/assignRole	Assigns a role to a user. Each user must have at least one role.	userRoles.CreateRole	{“UserID”: “user-5678”, “RoleID”: “role-1234”}	{“status”: “success”}
removeRoleFromUser	/userRoles/removeRole	Removes an assigned role from a user.	userRoles.CreateRole	{“UserID”: “user-5678”, “RoleID”: “role-1234”}	{“status”: “success”}
listRolesForUser	/userRoles/listRolesForUser	Retrieves all roles assigned to a specific user.	userRoles.listRolesForUsers	{“UserID”: “user-5678”}	{“roles”: [/* Array of role objects */]}
listUsersWithRole	/userRoles/listUsersWithRole	Retrieves all users assigned to a specific role.	userRoles.listUsersWithRole	{“RoleID”: “role-1234”}	{“users”: [/* Array of user objects */]}

Webhooks #

Name	Trigger	Destination	Payload	Description	Error Handling
roleCreated	When a new user role is successfully created.	Log Module	{ “event”: “roleCreated”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “role”: { “RoleID”: “role-XXXX”, “RoleName”: “PremiumUser”, “RoleDescription”: “Grants premium access”, “RoleIndex”: 2 } }	Sends a webhook notification to log the creation of a new user role.	None
roleUpdated	When an existing user role is successfully updated.	Log Module	{ “event”: “roleUpdated”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “role”: { “RoleID”: “role-XXXX”, “UpdatedFields”: { “RoleDescription”: “Updated description”, “RoleIndex”: 3 } } }	Notifies that a user role’s details have been updated.	None
roleDeleted	When a user role is permanently deleted.	Log Module	{ “event”: “roleDeleted”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “role”: { “RoleID”: “role-XXXX” } }	Sends a webhook to log that a user role has been permanently removed from the system.	None
roleSoftDeleted	When a user role is marked as inactive (soft-deleted).	Log Module	{ “event”: “roleSoftDeleted”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “role”: { “RoleID”: “role-XXXX”, “status”: “soft-deleted” } }	Notifies that a user role has been soft-deleted, making it inactive while retaining its record.	None
roleRetrieved	When the details of a user role are successfully retrieved.	Log Module	{ “event”: “roleRetrieved”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “role”: { “RoleID”: “role-XXXX”, “RoleName”: “PremiumUser”, “RoleDescription”: “Grants premium access”, “RoleIndex”: 2 } }	Sends a notification that role information has been successfully fetched from the system.	None
rolesListed	When the listRoles function successfully retrieves all roles.	Log Module	{ “event”: “rolesListed”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “roles”: [ { “RoleID”: “role-XXXX”, “RoleName”: “PremiumUser”, “RoleIndex”: 2 } ] }	Notifies that a complete list of user roles has been successfully fetched.	None
roleAssigned	When assignRoleToUser successfully assigns a role to a user.	Log Module	{ “event”: “roleAssigned”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “assignment”: { “UserID”: “user-XXXX”, “RoleID”: “role-XXXX” } }	Notifies that a role has been successfully assigned to a user.	None
roleRemoved	When removeRoleFromUser successfully removes a role from a user.	Log Module	{ “event”: “roleRemoved”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “assignment”: { “UserID”: “user-XXXX”, “RoleID”: “role-XXXX” } }	Notifies that a role has been successfully removed from a user.	None
rolesForUserListed	When listRolesForUser successfully retrieves all roles assigned to a specific user.	Log Module	{ “event”: “rolesForUserListed”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “user”: { “UserID”: “user-XXXX” }, “roles”: [ { “RoleID”: “role-XXXX”, “RoleName”: “PremiumUser” } ] }	Notifies that the list of roles for a particular user has been successfully fetched.	None
usersWithRoleListed	When listUsersWithRole successfully retrieves a list of users assigned to a specific role.	Log Module	{ “event”: “usersWithRoleListed”, “timestamp”: “YYYY-MM-DDTHH:MM:SSZ”, “role”: { “RoleID”: “role-XXXX” }, “users”: [ { “UserID”: “user-XXXX”, “UserName”: “John Doe” } ] }	Notifies that the list of users with a specific role has been successfully fetched.	None

Settings #

Settings for the User Roles module are maintained in an internal key-value store. These settings may include configuration for pagination defaults, feature toggles (e.g., whether role assignments can be edited by non-admins), and webhook URLs. Settings are stored in JSON format to allow flexible and dynamic configuration.

Clarifications #

• User Membership: Every user must be assigned at least one role; however, users can belong to multiple roles concurrently.
• Role Index: Each role has a numeric index that signifies its priority. When a user has multiple roles, the effective permissions for each field are determined by the role with the highest index (i.e., the most permissive role takes precedence).
• Separation of Concerns: While the User Roles module manages the assignment and metadata of roles, the actual permissions (rights) corresponding to each role are managed by the User Rights module.
• Administrative Operations: All role management functions (create, update, delete, assign, remove) are intended to be used by administrators. Proper Authentication (via the Auth module) is required to perform these operations.
• User Retrieval: In addition to administrative functions, the module provides endpoints that allow users to retrieve their own role information, supporting transparency and self-service.
• Extensibility: The module is designed with simplicity in version 1, providing a foundation for potential future enhancements, such as more complex role hierarchies or dynamic permission evaluations.