1. Overview
The application currently operates with a single role per user. This approach limits users who are assigned multiple responsibilities, as they cannot switch between different role-specific activities without changing their session or logging in again.
This enhancement introduces a multi-role access and role-switching framework that allows a single user to be assigned multiple roles and seamlessly switch between those roles within the application.
The solution will provide:
Support for multiple roles for a single user.
Role switching through a bottom navigation bar.
A role-specific Home experience for each assigned role.
Role-specific module visibility.
Role-specific permissions for actions such as View, Add, Edit and Update.
A structure that can be extended easily when new roles are introduced.
The role context will remain within the current user session. Switching roles will not require logout or re-authentication.
2. Objective
The objective is to provide a clear and consistent way for field users with multiple responsibilities to perform activities associated with each of their assigned roles.
Example
A user may be assigned:
Registrar
Nurse
The user should be able to switch between these roles using the bottom navigation bar.
When Registrar is selected, the user sees Registrar-specific activities.
When Nurse is selected, the user sees Nurse-specific activities.
The user can switch between the two contexts at any time without leaving the application or logging out.
3. Role Context
Each user can have one or more roles assigned to them.
The application will identify the roles assigned to the logged-in user and make those roles available through the bottom navigation.
Supported Roles
| Role | Purpose |
|---|---|
| Registrar | Household and beneficiary-related activities |
| Nurse | Clinical screening, examination and referral-related activities |
| Counselling | Counselling and follow-up-related activities |
The framework will be designed so that additional roles can be introduced in the future without requiring a redesign of the overall role-switching experience.
4. Role Switching
The application will provide a bottom navigation bar for switching between assigned roles.
Behaviour
The bottom navigation will display one tab for each role assigned to the user.
A single-role user will also see the role navigation.
The currently selected tab represents the user's active role context.
Switching tabs changes the user's active role.
The user remains within the same logged-in session.
The active role will reset to the user's first assigned role when the application starts again.
The application will not persist the previously selected role.
Example
User assigned to Registrar + Nurse
------------------------------------------------
| Home |
| |
| Role-specific modules |
| |
------------------------------------------------
| Registrar | Nurse |
------------------------------------------------
Selecting Registrar displays Registrar activities.
Selecting Nurse displays Nurse activities.
5. Role-Specific Home Modules
Each role will have its own set of modules displayed on the Home screen.
Registrar
The Registrar role will provide access to:
Household
Beneficiaries
Non-Household
Nurse
The Nurse role will provide access to:
Referral
Tuberculosis
The Nurse role may also have permissions for additional clinical modules that are not necessarily displayed as Home cards.
Counseling
The Counselling role will provide access to:
Counselling
Contact Tracing
TB Treatment Follow-up
TPT
6. Role-Based Permissions
Role switching is not limited to changing the modules displayed on Home.
Each role will also determine what actions the user can perform within a module.
The permission model will support the following actions:
View
Add
Edit
Update
For example, a user may be able to view a particular module under one role but may not have permission to add or edit information.
This ensures that the user's access is controlled according to the responsibilities associated with their active role.
7. Role & Module Mapping
The application will maintain a centralized mapping between:
Role → Home Modules → Permissions
This provides a single source of truth for role-specific behaviour.
Conceptually:
Role
│
├── Home Modules
│ ├── Module A
│ ├── Module B
│ └── Module C
│
└── Permissions
├── View
├── Add
├── Edit
└── Update
This approach avoids scattering role-specific conditions throughout the application.
It also makes future changes easier when:
A module is added to a role.
A module is removed from a role.
A role receives additional permissions.
A new role is introduced.
8. Existing Functionality Compatibility
The multi-role capability will be introduced as a new flow, as role information will be integrated from a separate API.
The current single-role functionality will remain unchanged and will continue to operate as it does today, since the existing role mapping flow is still supported.
The new role context will be applied for:
Switching between roles
Controlling Home module visibility
Enforcing new role-based permission checks
Supporting future enhancements that depend on role awareness
9. User Experience Flow
Application Launch
User Login
↓
Identify Assigned Roles
↓
Determine Available Role Tabs
↓
Open First Assigned Role
↓
Display Role-Specific Home
Role Switching
Current Role
↓
User selects another role
↓
Active Role changes
↓
Home modules refresh
↓
Role-specific permissions are applied
Example: Registrar → Nurse
Registrar
├── Household
├── Beneficiaries
└── Non-Household
↓ Switch Role
Nurse
├── Referral
└── Tuberculosis
The user remains logged in throughout the entire process.
10. Permission Enforcement
Role permissions should be applied consistently across the application.
At a high level:
Modules should only expose functionality available to the active role.
Actions that the role cannot perform should be hidden or disabled where appropriate.
Permission checks should also be applied when an action is actually performed, ensuring that restricted operations cannot be executed through alternate flows.
This provides both a clear user experience and consistent access control.
11. Handling Unknown or Missing Roles (Needs discussion)
Since future backend APIs may return multiple roles that are not yet defined or registered within the application, a fallback mechanism should be in place to handle such scenarios.
If the application is unable to identify the user’s assigned roles due to missing, outdated, or unrecognized role data, it will revert to the existing default behavior.
In such cases, the user will be assigned the Registrar role as the default context.
The role information can then be updated during the next successful login.
This approach ensures that users are not prevented from accessing the application due to unexpected or unsupported role data.
12. Extensibility
The solution should support additional roles in the future.
For example:
Currently we have
Registrar
Nurse
Counseling
In Future we can have more roles added
Registrar
Nurse
Counseling
Lab Technician
Adding a new role should primarily involve defining:
The new role.
Its Home modules.
Its module permissions.
Its role navigation representation.
The overall navigation and role-switching experience should remain unchanged.
13. Key Principles
The implementation should follow these principles:
Single User, Multiple Roles
Seamless Role Switching
No Logout During Role Switching
Role-Specific Home Experience
Role-Based Module Visibility
Role-Based Permissions
Centralized Role-to-Module Mapping
Backward Compatibility
Easy Future Extension
Consistent Permission Enforcement
14. Expected Outcome
After implementation, a user assigned to multiple roles will be able to operate the application according to each role without maintaining separate sessions.
For example:
Registrar + Nurse
→ Select Registrar
→ Manage households and beneficiaries
→ Switch to Nurse
→ Access clinical and referral activities
→ Switch back to Registrar
→ Continue Registrar activities
The overall experience will make the application role-aware, scalable and easier to extend, while keeping the user's session and workflow uninterrupted.