SyRF Product Features Roadmap¶

The big picture: what SyRF is building, why, and in what order.

Vision¶

SyRF (Systematic Review Facility) is a web platform for conducting systematic reviews and meta-analyses of preclinical research. It is developed by the CAMARADES group and used by research teams worldwide.

The end state: A researcher uploads citations, the system deduplicates them, a team screens and annotates collaboratively with structured reconciliation for quality assurance, and a PRISMA 2020 flow diagram is auto-generated for publication — all auditable, versioned, and traceable.

Core value proposition: Reconciled, authoritative data per study with full PRISMA 2020 compliance.

What Exists Today¶

SyRF is a working platform with active users. The current system supports:

Capability	Status	Limitations
User accounts & authentication	Live (Auth0)	—
Project creation & membership	Live	No custom permission groups
Citation import (RIS, PubMed XML, CSV)	Live	No deduplication pipeline
Basic screening (include/exclude)	Live	No named profiles, no structured reasons, no PRISMA mapping
Annotation (structured questions)	Live	Questions locked after first answer; no versioning; no auto-save
Basic data export	Live	No reconciliation status, no agreement metrics
Risk of Bias AI	Live	ROB AI integration via MapsGroupHttpClient
File uploads (S3 + Lambda notification)	Live	—
Background jobs (Quartz scheduler)	Live	—

What's missing: Question versioning, per-question auto-save, reconciliation workflow, deduplication, screening profiles, stage filtering, PRISMA 2020 reporting. These are the three releases below.

The Three Releases¶

                    ┌──────────────────────────────────────────┐
                    │          SyRF Platform Roadmap            │
                    └──────────────────────────────────────────┘

  ═══ FOUNDATION ═══          ═══ RELEASE 1 ═══
  Phases 1-2 ✅               Phases 3-7
  PRISMA spec,                Annotation versioning,
  data model design           rebuilt form, question mgmt

                              ═══ RELEASE 2 ═══         ═══ RELEASE 3 ═══
                              Phases 8-11                Phases 12-16
                              Permissions &              Dedup, screening
                              reconciliation             pipeline & PRISMA

Release 1: Question Management & Annotation Form¶

Theme: Give teams control over evolving their annotation protocol without breaking past data.

The Problem It Solves¶

Today, annotation questions are locked after the first answer. Teams can't fix ambiguous wording, add missing options, or evolve their protocol. There's no auto-save, so work is lost on browser crashes. And there's no audit trail connecting answers to the exact question version they were collected against.

What Users Get¶

Feature	User Impact
Question versioning	Edit questions at any time. Each edit creates an immutable version. Past annotations remain linked to the version they were answered against. Full audit trail.
Draft → Activate lifecycle	Design questions freely in draft mode. Activate when ready. Structure (data type, parent) locks on activation; content (text, options) remains editable via versioning.
Rebuilt annotation form	Virtual scroll handles 100+ questions without lag. Per-question auto-save means no lost work. Signal-based Angular 21 architecture.
Question set management	Admin dashboard showing version history, side-by-side diffs, and stage-level question configuration.
Annotation import	Import annotations from external tools (Rayyan, Covidence, spreadsheets) via a 5-step wizard.

Phases¶

Phase	Name	Delivers
3	Collection Infrastructure (FEAT-001)	`pmAnnotationQuestion` and `pmQuestionSet` MongoDB collections with scope/concurrency support. Optimistic concurrency on Study writes.
4	Question Lifecycle (FEAT-001)	Draft creation → activation → versioning workflow. DraftQuestion, AnnotationQuestion, AQVersion, QuestionSet, QuestionSetVersion entities.
5	Annotation Form v2 (FEAT-002)	Rebuilt form with virtual scroll, per-question auto-save via `pendingAnswer` buffer, session versioning. All 6 question types: boolean, select, checklist, text, numeric, autocomplete.
6	Question Management UI (FEAT-003)	Version history viewer, side-by-side diff, version badges, admin tools for QSV transitions.
6.1	Annotation Import (FEAT-004)	5-step import wizard (upload → field mapping → validation → conflict resolution → commit). CSV, JSON, YAML support.
7	Release 1 Migration	Backfill existing questions as v1 AQVersions. Create initial QSVs. Feature flag rollout with rollback scripts.

Key Design Pattern: Identity + Immutable Versions¶

Every annotation entity follows this pattern — it is the architectural backbone of the entire platform:

AnnotationQuestion (AQ)     ── stable identity, fixed structure
  └─ AQVersion (AQV)        ── immutable content snapshot (text, options, help)

QuestionSet (QS)             ── stable identity per scope
  └─ QSVersion (QSV)         ── immutable ordered list of AQVersionIds

Session                      ── per-annotator-per-study
  └─ SessionVersion (SV)     ── immutable snapshot on submit
       └─ AnnotationVersion  ── pinned to specific AQVersionId

This pattern repeats for reconciliation sessions (Release 2) and screening decisions (Release 3).

Execution Order¶

Phase 3 → Phase 4 → ┬─ Phase 5 (Form) ──┬→ Phase 6.1 → Phase 7
                     └─ Phase 6 (Mgmt UI)─┘

Phases 5 and 6 can execute in parallel.

Release 2: Reconciliation¶

Theme: When annotators disagree, resolve it with structured reconciliation to produce gold-standard data.

The Problem It Solves¶

Today, when two annotators give different answers for the same study, there's no systematic way to resolve the disagreement. Projects rely on informal discussion or ad-hoc overrides. There's no record of who resolved what, no blinding, and no agreement metrics. Journals increasingly require evidence that annotation disagreements were handled rigorously.

What Users Get¶

Feature	User Impact
Custom permission groups	Create named groups (e.g., "Senior Reviewers", "Screening Team") with per-stage activity permissions. Assign reconciler role to specific people.
Automatic authority determination	System detects when a study needs reconciliation (2+ annotators with completed sessions) and when it can be auto-promoted (single annotator where min=1).
Reconciliation workflow	Reconciler is randomly assigned (no cherry-picking). Sees blinded candidate answers ("Annotator A" vs "Annotator B"). Creates their own annotation, producing a gold-standard record.
Bulk approve	When all annotators agree on all answers, admin can batch-approve without individual review.
Agreement metrics	Percent Agreement and Cohen's Kappa displayed on dashboard per stage.
Cross-stage visibility	Configurable per stage: Blind (see nothing), ShowOwnPrior (see your own previous stage answers), ShowReconciled (see reconciled answers from prior stages).

Phases¶

Phase	Name	Delivers
8	Project Groups & Permissions (FEAT-005)	Named permission groups with per-stage activity control. `Reconcile` stage activity. Built-in Administrator group for backward compatibility.
9	Reconciliation Model & Authority (FEAT-006)	ReconciliationSession and ReconciliationSessionVersion (RSV) entities. Auto-promote rules. Pool population logic.
10	Reconciliation Workflow & UI (FEAT-006)	Random assignment, blinded comparison UI, bulk approve, agreement metrics, reconciliation dashboard.
11	Release 2 Migration	Auto-promote single-annotator studies. Populate reconciliation pool. Map existing permissions to new groups.

Key Entity: Reconciliation Session Version (RSV)¶

The RSV is the gold-standard record — the single authoritative answer set for a study:

ReconciliationSessionVersion (RSV)
├── committedBy: investigatorId (the reconciler)
├── resolution: Manual | SingleAnnotator | BulkApprove | CandidateAgreement
├── answers: AnnotationVersion[]  (reconciler's own answers, pinned to AQVersionIds)
├── candidateSessionVersionIds: string[]  (what they reviewed)
└── committedAt: timestamp

Execution Order¶

Phase 8 → Phase 9 → Phase 10 → Phase 11

Strictly sequential — each phase depends on the previous.

Release 3: Screening Pipeline & PRISMA¶

Theme: Complete the systematic review workflow from deduplication through PRISMA 2020 reporting.

The Problem It Solves¶

Today, screening is a binary include/exclude without structured criteria, multi-profile support, or configurable pipelines. There's no deduplication — teams manually identify duplicates across database searches. And there's no PRISMA flow diagram, which journals require for publication.

What Users Get¶

Feature	User Impact
Deduplication	After import, the system automatically identifies duplicates using the ASySD algorithm. High-confidence duplicates are auto-confirmed. Probable duplicates queue for admin review with a merge wizard.
Three-level data model	Publications (system-wide, DOI/PMID indexed), Citations (immutable per-import citation value objects), and Studies (the reviewable entity). Enables cross-project dedup and PRISMA per-source counting.
Named screening profiles	Create profiles like "Title/Abstract Screen" and "Full-Text Screen" with specific inclusion/exclusion criteria. Profiles are reusable and immutable once used.
Configurable stage filtering	Define which studies appear in each stage's pool using filter rules (e.g., "only studies Included in Profile A").
Structured exclusion reasons	Record why a study was excluded with hierarchical reasons linked to profile criteria. Required for PRISMA boxes 9 and 15.
Screening reconciliation	Same workflow as annotation reconciliation, applied to screening decisions.
PRISMA 2020 flow diagram	Auto-generated from review data. 17 boxes, 34 fields. Dual-column layout. Multiple export formats (interactive, JSON/CSV, R package compatible).
Enhanced data export	Reconciliation status per question, agreement metrics, deduplication reports, screening breakdowns with exclusion reasons.

Phases¶

Phase	Name	Delivers
12	Deduplication Service (FEAT-012)	`pmPublication` collection with DOI/PMID unique sparse indexes. ASySD integration (R subprocess). Import pipeline creating Publication → Citation → Study chain. Merge wizard for probable duplicates.
13	Screening Profiles (FEAT-007) & Stage Settings (FEAT-010)	Named screening profiles with agreement modes (Single, DualManual, DualAutomated). Profile immutability enforcement. Unified stage settings panel.
14	Stage Filtering (FEAT-008)	Configurable filter rules defining stage study pools. FilterCompiler translating rules to MongoDB queries. Random selection for fair distribution.
15	Screening Annotations (FEAT-009)	Structured exclusion reasons with hierarchical sub-reasons. Screening reconciliation workflow. FinalScreeningOutcome with authority tracking.
16	R3 Migration, Export & PRISMA	Study status backfill. Screening data restructuring. Enhanced export with reconciliation and agreement data. PRISMA 2020 flow diagram generation with all 34 fields derived from the data model.

Key Data Model: Three Levels¶

Publication (system-scoped)
│   DOI/PMID unique sparse indexes
│   Best-of-breed metadata from all imports
│   Never deleted
│
├── Citation (project-scoped, immutable Value Object)
│   │   Raw citation from one import/source
│   │   Tagged with SearchSourceType for PRISMA column assignment
│   │   Never modified after creation
│   │
│   └── Study (project-scoped, mutable)
│           Reviewable entity with lifecycleStatus
│           screeningOutcomes[] per profile
│           Annotation sessions, reconciliation sessions
│           What annotators and screeners interact with

Study Lifecycle States (9)¶

Active ──────────────────── Default. In screening/annotation pools.
├── Duplicate                Auto-confirmed duplicate. Excluded.
├── PendingDuplicateReview   Probable duplicate, awaiting admin. Excluded.
├── FullTextSought           Retrieval attempted. Transitional.
│   └── FullTextNotRetrieved Full text not obtained. Terminal.
├── Included                 Passed all screening. Terminal.
├── Merged                   Merged into canonical study. Terminal.
├── RemovedByAutomation      Pre-screen automation removal. Terminal.
└── RemovedOther             Admin removal. Terminal.

Critical invariant: Lifecycle status = pipeline position only. Screening exclusion is per-profile on screeningOutcomes[], not a lifecycle status. A study can be excluded under one screening profile and included under another.

PRISMA 2020 Coverage¶

All 17 boxes and 34 fields are derivable from the data model:

PRISMA Section	Boxes	Data Source
Identification	2, 3, 11	Citation counts, lifecycle status counts
Screening	4-5, 6-7, 8-9, 12-15	Screening outcomes per profile
Included	10, 16, 17	lifecycleStatus = Included

Dual-column layout driven by SearchSourceType: - Column 1 (Databases & Registers): Database, Register - Column 2 (Other Sources): Website, Organisation, CitationSearching, Other

Execution Order¶

Phase 12 → Phase 13 → Phase 14 → Phase 15 → Phase 16

Strictly sequential — screening builds on dedup, filtering builds on profiles, and PRISMA requires everything.

Cross-Cutting Concerns¶

The Versioning Pattern (All Releases)¶

Every major entity follows Identity + Immutable Versions:

Entity	Identity (stable)	Version (immutable snapshot)
Annotation Question	AQ (dataType, parent, scope)	AQVersion (text, options, helpText)
Question Set	QS (scope, stage)	QSVersion (ordered AQVersionId list)
Annotation Session	Session (study, annotator)	SessionVersion (answers pinned to AQVs)
Reconciliation Session	ReconSession (study)	RSV (gold-standard answers + resolution)
Screening Outcome	Per-profile on Study	Decision history with authority tracking

This is not incidental — it is the architectural invariant that makes reconciliation and PRISMA auditing possible.

PRISMA 2020 Compliance¶

The PRISMA specification (Phase 2, complete) defines binding constraints on all subsequent phases. Key documents:

prisma-flow-diagram-mapping.md — 17 boxes, 34 fields, derivation rules
three-level-data-model.md — Publication/Citation/Study specs
study-lifecycle-and-source-taxonomy.md — 9 lifecycle states, 6 source types
deduplication-service-specification.md — ASySD integration
prisma-constraint-annotations.md — Per-phase MUST constraints

Every phase's design must satisfy its PRISMA constraint annotations or the end-state PRISMA diagram will be incomplete.

Data Migrations¶

Each release ends with a migration phase (7, 11, 16) that: - Backfills new fields on existing documents (additive only) - Populates new collections from existing data - Rolls out feature flags in a controlled sequence - Provides rollback scripts (field removal, flag revert) - Validates PRISMA constraint compliance

All migrations target production database syrftest — staging shares the same DB. Database isolation (separate staging/preview databases) is a prerequisite for safe migration testing.

Dependency Graph¶

Phase 1 ✅ ─→ Phase 2 ✅ ─→ Phase 2.1 ✅
                  │
                  ├─→ Phase 3 ─→ Phase 4 ─→ Phase 5 ─┐
                  │                    └──→ Phase 6 ─┤─→ Phase 6.1 ─→ Phase 7
                  │                                  │     (RELEASE 1 COMPLETE)
                  │                                  │
                  ├─→ Phase 8 ─→ Phase 9 ─→ Phase 10 ─→ Phase 11
                  │                                        (RELEASE 2 COMPLETE)
                  │
                  └─→ Phase 12 ─→ Phase 13 ─→ Phase 14 ─→ Phase 15 ─→ Phase 16
                                                                (RELEASE 3 COMPLETE)

Cross-release dependencies: - Phase 10 (reconciliation UI) depends on Phase 5 (form v2) - Phase 12 (dedup) uses StudyLifecycleStatus which is conceptually Release 3 but needed by Release 2 reconciliation - All phases depend on Phase 2's PRISMA constraints

Progress¶

Phase	Release	Status	Completed
1. Spec Resolution	Foundation	✅ Complete	2026-02-15
2. PRISMA Specification	Foundation	✅ Complete	2026-02-17
2.1. Documentation Suite	Foundation	✅ Complete	2026-02-18
3. Collection Infrastructure	R1	⏳ Planned	—
4. Question Lifecycle	R1	⏳ Planned	—
5. Annotation Form v2	R1	⏳ Planned	—
6. Question Management UI	R1	⏳ Planned	—
6.1. Annotation Import	R1	⏳ Planned	—
7. Release 1 Migration	R1	⏳ Planned	—
8. Project Groups & Permissions	R2	⏳ Planned	—
9. Reconciliation Model & Authority	R2	⏳ Planned	—
10. Reconciliation Workflow & UI	R2	⏳ Planned	—
11. Release 2 Migration	R2	⏳ Planned	—
12. Deduplication Service	R3	⏳ Planned	—
13. Screening Profiles & Stage Settings	R3	⏳ Planned	—
14. Stage Filtering	R3	⏳ Planned	—
15. Screening Annotations & Reconciliation	R3	⏳ Planned	—
16. R3 Migration, Export & PRISMA	R3	⏳ Planned	—

What Success Looks Like¶

After all three releases, SyRF delivers:

For researchers: A complete systematic review platform — import through PRISMA — with no need to switch between tools or manually track decisions.

For project admins: Full control over annotation protocols that can evolve mid-project, custom team permissions, and multi-stage screening pipelines.

For reviewers: A fast, auto-saving annotation form with structured reconciliation that produces auditable gold-standard data.

For journals and funders: PRISMA 2020 flow diagrams auto-generated from the actual review data, with 34 fields derived directly from the system — not hand-counted.

For the platform: An immutable, versioned, auditable data model where every decision is traceable from question version through annotation to reconciliation, with PRISMA compliance built into the architecture rather than bolted on.