Add Roles and Governance docs for 3.1 - #88
Conversation
Publish the Roles and Permission, Organisation, User, Supplier and Responsibility modules from the care_docs sources. Refreshes three access-governance concepts, adds Supplier and Responsibility as new concepts, and adds twenty-one flows under a new Access & Governance category in the 3.1 flows sidebar.
Deploying coredocs with
|
| Latest commit: |
c59f28e
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://93dd870e.coredocs.pages.dev |
| Branch Preview URL: | https://docs-governance-modules.coredocs.pages.dev |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Care docs review — PR #88 (Roles and Governance, 3.1)
A large, well-organised drop: 21 flows, 5 concepts, a nested sidebar category and per-module _category_.json files. Structure, kebab-case slugs, verb-phrase flow slugs, sidebar_position-only frontmatter and the relative .mdx link style all follow the conventions. No corruption markers, no {#...} heading ids, no bare { }, no code, endpoints or permission slugs leaked into the user-facing layers. The manual flow sidebar was updated (checklist 10) and the key values match the _category_.json keys.
The one blocker
Mirroring (checklist 11). Everything lands in versioned_docs/version-3.1/ only. The shared conventions require 3.0 and 3.1 to stay byte-identical, and 3.0 still has the old access-control.mdx, organization.mdx and user.mdx and no flows/access-governance/ folder at all. This is the largest divergence between the two versions in the repo. Mirror the set (docs plus versioned_sidebars/version-3.0-sidebars.json), or record the decision to fork the versions.
Recurring themes in the inline comments
- FHIR narration (checklist 7) in
access-control.mdxanduser.mdx— including the "there is no FHIR resource for this" note, which is the same commentary in negative form. - Template conformance (checklist 8) —
supplier.mdxandresponsibility.mdxadd top-level sections the concept template does not define;change-password.mdxreplaces numbered steps with lettered groups and covers two tasks in one flow. - Empty permission tables — several flows put "None. ..." in the Permission column.
create-role.mdxgets this right with a plain sentence; copy that pattern. - Terminology (checklist 14) — "Organisation" in the concept H1 and sidebar against "organization" everywhere else. Your PR body flags it; please settle it in this PR.
Verified against source
Can create User in care,Can list Users in Care—care/security/permissions/user.py✅Can Manage Users in an Organization,Can Manage Organizations,Can Manage Connected Role Organizations—care/security/permissions/organization.py✅Can Manage Users in a Facility Organization—care/security/permissions/facility_organization.py✅
Could not verify
- The "only a super administrator" gate on role, organization and responsibility management. No permission covers role CRUD, but I did not find the viewset or route guard that enforces superuser. Please cite it.
- The user status and activity badge strings (
Archived,Online,Never Logged In,Service Account) againstcare_fepublic/locale/en.json. - The government hierarchy level list and the claim that deployments configure the maximum depth.
- The password reset link expiry being deployment-configured.
Non-blocking — the content is strong and mostly in the right layer. Fix the mirroring and the template deviations and this is ready.> Generated by Docs Reviewer for #88 · opus50 · 206.1 AIC · ⌖ 18.1 AIC · ⊞ 11K
| }, | ||
| { | ||
| "type": "category", | ||
| "label": "Access & Governance", |
There was a problem hiding this comment.
Mirroring (checklist 11). The shared conventions require versioned_docs/version-3.0/ and version-3.1/ to stay byte-identical (.claude/skills/care-concept-doc/references/conventions.md, "Mirror 3.0 → 3.1"). This PR adds all 33 files to 3.1 only — versioned_docs/version-3.0/concepts/access-governance/ still holds the old access-control.mdx, organization.mdx and user.mdx, and there is no versioned_docs/version-3.0/flows/access-governance/ at all. Either mirror the whole set to 3.0 (and its sidebar file) or state why 3.1 diverges.
| A **role** in Care is a named set of permissions. A permission allows one action, for example to register a patient. Care builds every permission into the product, so you cannot create or change a permission. You group permissions into a role, and then you give the role to a user. | ||
|
|
||
| There is no single FHIR resource for access control. Care builds it from three primitives that only mean something together: | ||
| Note: Roles and permissions belong to Care's access control. FHIR R5 has no resource for them, so this concept has no FHIR reference. |
There was a problem hiding this comment.
FHIR narration (checklist 7). The concept skill says link the FHIR page and never narrate the mapping; a sentence whose only content is that there is no mapping is the same kind of narration. Delete this line — a concept with no FHIR analogue simply omits the link.
| A **user** in Care is the staff account of a person who works in your organization. Doctors, nurses, and administrators sign in to Care with this account. A user account is separate from a patient record. | ||
|
|
||
| In Care's FHIR-aligned model, a user corresponds most closely to the **Practitioner** resource — the person delivering or supporting care. The account captures: | ||
| A user is closest to two FHIR R5 resources. [Practitioner](https://build.fhir.org/practitioner.html) holds the identity of a staff member. [PractitionerRole](https://build.fhir.org/practitionerrole.html) holds the role of a person in an organization. Care does not implement these as literal FHIR resources. The mapping is approximate. |
There was a problem hiding this comment.
FHIR narration (checklist 7). "Care does not implement these as literal FHIR resources. The mapping is approximate." is exactly the mapping commentary the concept template forbids. Keep the two links and cut the commentary, e.g. "A user is close to the FHIR [Practitioner]((build.fhir.org/redacted) and [PractitionerRole]((build.fhir.org/redacted) resources."
|
|
||
| Suppliers are a flat list. A supplier has no parent organization and no child organizations. | ||
|
|
||
| ## Where to find it |
There was a problem hiding this comment.
Template conformance (checklist 8). The concept template has exactly three top-level sections in this order: ## Definition, ## Key Attributes, ## Related. This page adds ## Where to find it (here, and before Key Attributes) and ## Use in purchase orders. Fold the navigation sentence into Definition and the purchase-order note into a ### sub-section under Key Attributes, or move it to the flow.
| | Name | The name of the vendor or distributor. This field is required. | | ||
| | Description | More detail about the supplier. This field is optional. | | ||
|
|
||
| ### On-screen wording |
There was a problem hiding this comment.
Layer discipline (checklist 2/3). ### On-screen wording documents a UI defect — the shared organization form showing "Create Department/Team" for a supplier. That is a bug report, not a concept. Remove it from the concept and raise it against care_fe; if the wording must be documented for now, it belongs in the create/update supplier flow steps.
|
|
||
| | Permission | Access | | ||
| | --- | --- | | ||
| | Can Manage Organizations | Lets you link or unlink one responsibility from another. You need this permission on both responsibilities. | |
There was a problem hiding this comment.
Permission name (checklist 16). Verified: Can Manage Organizations matches can_manage_organization in care/security/permissions/organization.py. But the Pre-requisites above also require super administrator, which makes the permission row redundant — pick the constraint the backend actually enforces for this action and drop the other.
| --- | ||
|
|
||
| # Roles & Permissions | ||
| # Roles and Permission |
There was a problem hiding this comment.
Naming (checklist 9). H1 is sentence case and names the resource: "Roles and permissions". "Roles and Permission" is title case and singular where the page describes many permissions. The same string is repeated in the sidebar label and in every Related link, so fix it consistently.
|
|
||
| | Permission | Access | | ||
| | --- | --- | | ||
| | Can create User in care | Lets you create a new user account. | |
There was a problem hiding this comment.
Verified — no change needed. Can create User in care matches the display name in care/security/permissions/user.py exactly, including its lowercase "create" and "care". Noting it so a later editor does not "correct" the casing.
|
|
||
| | Permission | Access | | ||
| | --- | --- | | ||
| | Can Manage Users in an Organization | Lets you add a user, remove a user, or change a user's role in an Organization, a Supplier, or a Responsibility. | |
There was a problem hiding this comment.
Verified. Both names match care: Can Manage Users in an Organization (permissions/organization.py) and Can Manage Users in a Facility Organization (permissions/facility_organization.py). No change needed here.
| A user is the actor that ties the rest of the record together: | ||
| | Status | Description | | ||
| | --- | --- | | ||
| | Archived | The person cannot sign in to Care. Care keeps the history of the person. The user card shows a grey "Archived" badge. | |
There was a problem hiding this comment.
Display labels (checklist 4). "Archived" and the badge labels (Online, Never Logged In, Service Account) should be traceable to care_fe public/locale/en.json. Please confirm these are the shipped strings — I could not verify them from the diff alone. Also, a Status table with one row plus a second Badge table is not in the concept template; consider merging into one Status section.
1 participant
What
Publishes the five Roles & Governance modules from
care_docsinto the docs site (version 3.1). 21 flows, 3 refreshed concepts and 2 new ones.access-control.mdxorganization.mdxuser.mdxAdds an
Access & Governancecategory to the 3.1 flows sidebar with the five modules nested under it.Module mapping
All five publish under the existing
access-governancedomain.Roles and Permissionmaps toaccess-control.mdx, which is already titled "Roles & Permissions" and covers the same subject.Supplier and Responsibility are new concepts. Both are modelled as organization types in Care but are shown as their own lists in the product, so they get their own pages.
Frontmatter
None of these files had publishing frontmatter, so
domain,moduleandsidebar_positionwere added to the five concepts and aslugplussidebar_positionto all twenty-one flows. Flow titles were converted from "How to Create a Role" to "Create a role".Concept titles
Two existing pages change title, since the authored title is published as written:
Note the spelling shift to "Organisation" on the concept page while the route, the module folder and the flow titles stay "organization". Flag if that should be unified.
Verification
Docusaurus build passes for both
enandmllocales.