Feature: Groups

1. Overview

• Goal: A group is a named set of participants — a team, a unit, a tent — used to move and count people together. Instead of picking a dozen names one by one, staff select the group and a movement expands to its current members. Registry also tracks how many of a group's members are inside versus outside, turning the headcount into something teams can read at their own level of organization.
• Who uses it: All three roles create, read, edit and maintain group membership (add/remove members); only PROJECT_ADMINISTRATOR can permanently delete a group.
• Option required: None — always available. Groups are part of the core.

2. Roles & Permissions

Actions use CRUD shorthand — Create, Read, Update, Delete. See Roles & Permissions and Domain Model → Group.

Role	Permitted actions	Conditions / Scope
PROJECT_ADMINISTRATOR	C R U D + add/remove members	Only role that can permanently delete a group; also creates, edits and maintains membership (REGISTRY_...GROUP_C/R/U/D).
PROJECT_COORDINATOR	C R U + add/remove members	Creates, edits, disables/enables and maintains membership, same as the administrator — but cannot delete a group.
PROJECT_PARTICIPANT	C R U + add/remove members	Same floor as the coordinator: creates, edits, disables/enables and maintains membership — but cannot delete a group.

3. Business rules

• Name identifies the group.
• Members. A group holds at least one member; members are chosen from the project's participants via multi-select.
• Availability window is optional. With no window of its own, a group inherits the project's window — see Domain Model → Availability windows. When both start and end are set, start must be before end (@StartBeforeEnd).
• Expansion in movements. Selecting a group in a movement expands to its current members at that moment — later membership changes do not rewrite past movements. Each participant added this way carries a pool label on their movement entry, set to the name of the group they were added through and snapshotted at that instant. See Domain Model → Movement and Technical → Data Model (tb_movement_content.pool_name).
• Inside/outside counts. Registry tracks how many members are currently inside versus outside, derived from their movements.
• Disabling is a soft, reversible action. A disabled group is hidden but can be re-enabled.
• Deleting a group removes only the grouping. Its participants stay registered on the project and keep all their movement history; the group's name simply stops being available for future expansions, while past movements keep the pool labels they already recorded.

4. Behavioral scenarios (BDD)

Scenario: A coordinator creates a group with members
  Given I am a PROJECT_COORDINATOR on a project
  And the participants "Ana", "Ben" and "Cora" are registered
  When I create a group "Tent 1" with those three members
  Then the group is created with three members

Scenario: A group must have at least one member
  Given I am creating a group
  When I submit the group with no members
  Then the request is rejected because a group requires at least one member

Scenario: The availability start must be before its end
  Given I am creating a group
  When I set the availability start after its end
  Then the request is rejected by the @StartBeforeEnd validator

Scenario: Selecting a group in a movement expands to its current members
  Given the group "Tent 1" currently has members "Ana", "Ben" and "Cora"
  When staff record a movement selecting the group "Tent 1"
  Then the movement includes Ana, Ben and Cora
  And each of those three movement entries carries the pool label "Tent 1"

Scenario: A participant adds and removes members, but cannot delete the group
  Given I am a PROJECT_PARTICIPANT on a project
  And the group "Tent 1" has members "Ana" and "Ben"
  When I add "Cora" and remove "Ben"
  Then the group's members become "Ana" and "Cora"
  When I then attempt to delete "Tent 1"
  Then the request is refused for lack of permission

Scenario: Only an administrator can delete a group
  Given I am the PROJECT_ADMINISTRATOR of a project
  And the group "Tent 1" exists with members "Ana" and "Ben"
  When I delete "Tent 1"
  Then the group is permanently removed
  And "Ana" and "Ben" remain registered on the project — only the grouping is removed

Scenario: Registry reports a group's inside/outside split
  Given the group "Tent 1" has three members, two of whom are currently on site
  When I read the group
  Then it reports two members inside and one outside

5. API surface

The endpoints backing this feature — their paths, methods and the permission each one requires — are specified in Technical → API Reference, and kept there only so the transport contract never drifts from this spec. The authority for each action is in §2; the rules it must satisfy are in §3.