global: document request reviewers feature

closes #859

Author: zzacharo

docs/maintenance/architecture/requests.md

@@ -42,6 +42,7 @@ 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
 
@@ -56,11 +57,12 @@ The key entities in the data model:
 
 ## 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
@@ -85,6 +87,19 @@ In addition, the following meta states exists:
 Note that the *deleted* state is not implemented directly in the code, as the request is completely
 removed from the database in this case.
 
+
+## Reviewers in requests
+
+Reviewers are optional participants in a request process. They provide expert opinions, feedback, or recommendations but cannot make the final decision to accept or decline the request. That responsibility lies solely with the receiver.
+
+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
+
 ## Actions
 
 An action transitions a request from state to another state. Only the state transitions
@@ -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,73 @@
+# Requests
+
+_Introduced in 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 the possibility of accepting or declining a request.
+
+### 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. If you allow
+groups to be defined in your instance, i.e.
+
+```python
+# Enable assignment of groups as reviewers (requires invenio-users-resources)
+USERS_RESOURCES_GROUPS_ENABLED = True
+```
+then you will be able to use them as request reviewers.
+
+- **Use cases**: 
+  - Institutional Review Boards
+  - 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
+
+By default, reviewers can be added or removed by community members with roles:
+- **Owners** and **managers** can assign/remove reviewers
+- **Curators** can assign/remove reviewers
+
+Community members with the role: *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 review the inclusion 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 the possibility to accept or decline the request remains to the community responsibles (curators, managers and owners).
+
+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).