Phase 8: Project Groups and Permissions¶
Release 2 -- Reconciliation Foundation Phase 8 is the first step in delivering reconciliation. Before anyone can resolve disagreements, the platform needs to know who is allowed to.
Summary¶
This phase adds custom permission groups to SyRF projects, replacing the current simple admin/member role model with flexible, group-based permissions. The key new capability: project administrators can designate specific people as reconcilers on specific stages, giving them authority to resolve disagreements between annotators.
The Problem¶
Today, SyRF projects have only two roles: administrator and member. There is no way to:
- Assign different people to different stages (e.g., senior researchers reconcile while junior researchers annotate)
- Control who can resolve disagreements between annotators
- Create teams within a project with different responsibilities
- Restrict access to sensitive stages or administrative functions
This limitation becomes critical when reconciliation is introduced. Reconciliation requires a designated reconciler role -- someone trusted to make authoritative decisions when annotators disagree. Without group-based permissions, there is no way to assign this responsibility.
What We Are Building¶
Custom project groups with configurable permissions per stage:
- Group management: Administrators create named groups (e.g., "Senior Reviewers", "Screening Team", "Reconciliation Panel") and assign project members to them
- Stage-level permissions: Each group can be granted specific activities per stage -- annotate, screen, reconcile, or administer
- Reconciler role: A new stage activity (
Reconcile) that grants permission to resolve annotation and screening disagreements. This is the critical new permission that enables the reconciliation workflow in Phases 9-10 - Built-in Administrator group: The existing admin role is preserved as a system-managed group with full permissions, ensuring backward compatibility
What stays the same: Existing projects continue to work exactly as they do today. The permission model is additive -- current admin/member distinctions are preserved through the built-in Administrator group.
Why This Matters for Reconciliation¶
Reconciliation (Phases 9-10) requires three things that do not exist today:
- Designated reconcilers -- people trusted to make gold-standard decisions
- Per-stage assignment -- a person might reconcile in one stage but only annotate in another
- Role separation -- reconcilers should not reconcile their own annotations (configurable per stage)
Phase 8 provides all three through the group-based permission model. Without it, reconciliation cannot proceed.
How It Connects¶
| Connection | Detail |
|---|---|
| Phase 9 (Reconciliation Model) | Uses the Reconcile permission to determine who can be assigned reconciliation tasks |
| Phase 10 (Reconciliation Workflow) | The reconciliation UI checks group permissions before assigning studies |
| Phase 11 (Release 2 Migration) | Existing admin permissions are mapped to the new group model |
| Phase 13 (Screening Profiles) | Screener role assignment uses the same group-based permission model |
Existing work: Backend implementation is largely complete (PR #2224, 83 commits, 49 files). The frontend group management UI is incomplete and will be finished in this phase.
Architecture¶
For the platform architecture overview, including the service architecture and data model, see platform-architecture.md.
For the current state of the project groups feature, see the project groups UI/UX redesign.
Phase 8 creates the permission structure. Phase 9 builds the reconciliation data model on top of it. Phase 10 delivers the reconciliation workflow. Phase 11 migrates existing data.