global: document request reviewers feature

Author: zzacharo

docs/maintenance/architecture/requests.md

@@ -42,9 +42,22 @@ With the above examples in mind, a request ...
 
 - is created by someone who can cancel it
 - is received by someone who can accept or decline it
+- may have reviewers assigned to provide feedback and recommendations
 - may require clarifications (i.e. a conversation) between the creator of the request and the recipient(s)
 - may expire after a certain amount of time
 
+### Reviewers in Requests
+
+Reviewers are optional participants in the request process who can be assigned to provide expert opinion, feedback, or recommendations. Unlike the receiver who makes the final decision to accept or decline the request, reviewers serve as consultants or advisors.
+
+Key characteristics of reviewers:
+- Can be individual users or groups
+- Multiple reviewers can be assigned to a single request
+- Do not have direct authority to accept or decline the request
+- Provide input through comments and feedback in the request timeline
+- Can be added or removed throughout the request lifecycle
+- Have specific permissions to view and comment on the request
+
 ## Entities
 
 The key entities in the data model:
@@ -53,14 +66,16 @@ The key entities in the data model:
 - Request actions associated to a given request type.
 - Request events and comments
 - Entity references
+- Reviewers (optional entities that can provide feedback and recommendations)
 
 ## Properties
 
-A request has four key properties:
+A request has five key properties:
 
 - **Creator** - the entity creating request
 - **Topic** - the entity the request is about
 - **Receiver** - the entity the request is addressed to
+- **Reviewers** - optional entities assigned to review and provide input on the request
 - **Status** - the state a request is in
 
 ## Statuses
@@ -108,7 +123,7 @@ Note, we do not allow updating closed requests.
 
 ## Entity references
 
-Entity references is an abstraction that allows any type of creator, topic and
+Entity references is an abstraction that allows any type of creator, topic, reviewer and
 receiver to be modelled.
 
 Technically it's just a type and persistent identifier. Below is an example of
@@ -140,7 +155,7 @@ user have access to.
 An entity grant is a combination of:
 
 - Prefix - The prefix qualifies the grant within the record (e.g. ``creator``,
-  ``receiver``, ``read``, ``write``).
+  ``receiver``, ``reviewers``, ``read``, ``write``).
 - Permission need - Entity reference as a permission need (e.g ``UserNeed(1)``).
 
 *Permission needs* are just tuples. Below you find examples of permission
@@ -156,6 +171,7 @@ into a token that we can use for querying:
 Examples for entity grant tokens:
 
 - ``creator.user.1`` - expresses that the creator.user.1 is granted access.
+- ``reviewers.group.review-board`` - expresses that the group review board is granted access.
 - ``receiver.community.123.manager`` - expresses that the community 123
   managers are granted access.
 

docs/operate/customize/requests.md

@@ -0,0 +1,72 @@
+# Requests
+
+_Introduced in InvenioRDM v14_
+
+Configure the requests system in InvenioRDM, including the reviewers feature for enhanced review workflows.
+
+## Reviewers Configuration
+
+The reviewers feature enables assignment of external experts, collaborators, or community members to provide feedback on requests without granting them decision-making authority.
+
+### Enable/Disable Reviewers
+
+```python
+# Enable the reviewers feature (default: True)
+REQUESTS_REVIEWERS_ENABLED = True
+```
+
+### Reviewer Limits
+
+Control the maximum number of reviewers that can be assigned to a single request. This helps manage workflow complexity and ensures review processes remain manageable.
+
+```python
+# Maximum number of reviewers per request (default: 10)
+REQUESTS_REVIEWERS_MAX_NUMBER = 5
+```
+
+- **Purpose**: Prevents overwhelming requests with too many reviewers
+- **Considerations**: Balance between comprehensive review and manageable workflow
+
+### Group Reviewers
+
+Enable the assignment of user groups as reviewers, allowing entire teams or committees to be assigned to review requests collectively.
+
+```python
+# Enable assignment of groups as reviewers (requires invenio-users-resources)
+USERS_RESOURCES_GROUPS_ENABLED = True
+```
+
+- **Requirements**: Requires the `invenio-users-resources` module to be installed and configured
+- **Use cases**: 
+  - Institutional Review Boards (IRBs)
+  - Editorial committees
+  - Subject matter expert panels
+  - Department review teams
+- **Behavior**: All members of the assigned group receive access to view and comment on the request
+- **Notifications**: Group members may receive notifications based on your notification configuration
+
+## Usage
+
+When enabled, community curators, managers and owners can:
+
+- Assign individual users or groups as reviewers to any request
+- Share requests with external experts outside the community
+- Grant access to community members who normally wouldn't see requests (e.g., readers)
+- Allow multiple reviewers to provide independent feedback
+- Track all reviewer interactions in the request timeline
+
+Reviewers can view the request, participate in conversations, and provide recommendations, but cannot accept or decline the request.
+
+## Permissions
+
+Reviewer assignment requires appropriate community permissions:
+- **Owners** and **managers** can assign/remove reviewers
+- **Curators** can assign/remove reviewers (if configured)
+- **Reviewers** can view and comment on assigned requests
+- **Readers** cannot assign reviewers but can be assigned as reviewers
+
+## Related Configuration
+
+See also:
+- [Communities](../../use/communities.md#requests) - User guide for requests and reviewers
+- [Architecture documentation](../../maintenance/architecture/requests.md) - Technical overview of the requests system

docs/use/communities.md

@@ -126,4 +126,6 @@ In the **Requests** tab, you can view all requests for your community. It allows
 
 The request page provides a dedicated space for communication. You can **have a conversation with the submitter** directly within the request, and you can **accept or decline the inclusion request** based on your community's curation policies.
 
-You can find the high-level architecture documentation for communities [here](../maintenance/architecture/communities.md).
+When a submission requires expert input or peer review, you can **assign reviewers** to give specific users or groups access to evaluate the request. This allows you to share the request with external experts, collaborators outside your community, or community members who normally wouldn't have access (such as readers). Reviewers can provide feedback on the research publication draft or assess whether a record meets your community's inclusion criteria. They participate in the request conversation and share their expertise to help you make an informed curation decision, while you retain the final authority to accept or decline the request.
+
+You can find the high-level architecture documentation for communities [here](../maintenance/architecture/communities.md) and configuration options for requests and reviewers [here](../operate/customize/requests.md).