Illustrating a Shared Mental Model for Role Terminology and RBAC Model in JupyterHealth Exchange #37
Description
Summary
This issue aims to illustrate a shared mental model to reduce ambiguity around various role-related terms — including Superuser, Practitioner, Manager, Member, and Viewer — which have been used across conversations in JupyterHealth Exchange (JHE).
These terms come from different conceptual layers:
- 🛠 Technical (e.g., Django backend roles)
- 💻 Product/UI (user-facing permissions)
- 🧬 Organizational (lab/study roles)
- 📦 Semantic standards like FHIR (e.g., Practitioner resource)
Without a centralized reference, these overlapping layers can easily become confusing — especially for contributors or collaborators unfamiliar with the full stack. This issue proposes a structured breakdown to clarify the distinctions and relationships between these roles, supporting more consistent communication and documentation across the project.
🔍 Conceptual Layers of Roles in JupyterHealth Exchange
1. 🛠 Technical Layer (Platform/System Level)
Comes from Django and the backend implementation
| Term | Description |
|---|---|
| Superuser | Django-native admin with full access (can create top-level orgs, access Django Admin, etc.) |
| Authenticated User | Anyone who logs into the platform |
| Permission Classes | Mechanism (e.g., Django, Casbin) for enforcing access based on scope. Backend model-level permissions (e.g., can_add_patient, can_edit_study) |
Used in backend code — not visible to most users.
2. 💻 Product Layer (User-Facing Role System)
What users experience inside JupyterHealth Exchange
| Role | Can Manage Users | Can Edit Studies/Patients | Can Only View |
|---|---|---|---|
| Manager | ✅ | ✅ | ✅ |
| Member | ❌ | ✅ | ✅ |
| Viewer | ❌ | ❌ | ✅ |
Roles are assigned per organization, and users may have different roles in different orgs.
User vs Member:
- User: Refers to anyone with an account on the platform. This means they are authenticated (they can log in), but not yet authorized to access any data.
- Member: Refers to someone who has been explicitly granted access to an organization. This is what authorizes them to view or manage specific resources (e.g., patients, studies) within that org.
3. 🧬 Organizational Layer (Real-World Study/Research Roles)
External roles defined by institutional or IRB structures
| Real-World Role | Platform Role (Typical Mapping) |
|---|---|
| PI | Manager |
| Study Coordinator | Manager |
| Postdoc/Researcher | Member |
| Student/Analyst | Viewer or Member |
| External Collaborator | Viewer |
Not represented natively in the system, but maps to platform roles for access control.
4. 📦 Semantic Layer (FHIR Data Model)
Concepts inherited from HL7 FHIR
- Practitioner: A FHIR resource representing a person involved in care or research
- PractitionerRole: Describes the role a practitioner plays, at what org, for what time period, etc.
Currently, "Practitioner" is also being used to refer to platform users — which may cause confusion if not distinguished.
🔄 Summary Table
| Layer | Scope | Example Terms |
|---|---|---|
| Technical | Backend infrastructure | Superuser, Authenticated User, permission_classes |
| Product | UI-facing role model | Manager, Member, Viewer |
| Organizational | Research/lab structure | PI, Student, Coordinator |
| Semantic (FHIR) | Data modeling standard | Practitioner, PractitionerRole (FHIR) |
❓Open Questions
- Is there interest in more clearly separating “Practitioner” (FHIR identity) from “User” (platform login) in our terminology, [instead using "Authenticated User" or at least clarifying the connection/relation between FHIR identity and authenticated user on the platform side?
- Does this layered mental model (Technical / Product / Organizational / FHIR) actually help reduce confusion — or does it introduce more?
- Would it be helpful to include a version of this breakdown anywhere?
- Are there additional conceptual layers (e.g., governance roles, consent roles) we should consider adding over time?