Annotation Form v2

Summary

Phase 5 rebuilds the annotation form that reviewers use to answer questions about studies. The new form solves a known performance problem where projects with many questions become slow and unresponsive. It also introduces per-question auto-save (so work is never lost) and tracks exactly which version of each question was answered -- creating the audit trail that reconciliation depends on.

The Problem

The current annotation form has a fundamental performance issue: it renders every question on the page simultaneously. A stage with 50 questions and 20 study units creates 1,000 interactive elements in the browser at once. This causes:

• Slow loading -- Projects with many questions can take several seconds to render the form
• Sluggish typing -- Every keystroke triggers re-processing across the entire form, causing noticeable delays
• All-or-nothing saving -- The entire form is saved as one block. If the browser crashes mid-session, all unsaved answers are lost
• No version tracking -- Answers are not linked to the specific question version or stage configuration that was active when they were recorded

These issues have been reported by users (GitHub issue #1125) and become worse as projects grow in complexity.

What We're Building

For Reviewers/Annotators

What changes	Today	After
Loading speed	All questions render at once (slow with 50+ questions)	Only visible questions render -- smooth scrolling even with 100+
Saving	Must save the entire form at once	Each answer saves automatically as you work
Work preservation	Browser crash = lost work	Auto-saved answers survive crashes, device switches, and session timeouts
Navigation	No warning when leaving	Warning dialog if you have unsaved changes
Version awareness	Hidden	Each answer silently records which question version it was collected against

The experience in practice: An annotator opens a study, scrolls through questions, and answers them one at a time. Each answer saves automatically within seconds -- a small indicator confirms the save. If the annotator closes their laptop and reopens it later (even on a different computer), their work is exactly where they left it. When they click Submit, the system creates a permanent, unchangeable record of their complete session.

For Project Administrators

The rebuilt form ships behind a project-level feature flag, meaning administrators can enable it for specific projects before rolling it out broadly. Both the old and new forms can coexist during the transition period. The rollout follows a deliberate sequence:

1. Opt-in beta -- Selected projects switch to the new form. Feedback gathered on performance and usability.
2. Default on -- All new projects use the new form. Existing projects can opt out.
3. Remove old form -- After a migration period, the old form is retired.

Performance Targets

The rebuilt form sets specific performance targets to ensure the improvements are measurable:

• Loading time for a 50-question stage: under 200 milliseconds (current: approximately 800ms)
• Loading time for 1,000 question units: under 300 milliseconds (current: over 5 seconds)
• Keystroke response: under 16 milliseconds (smooth 60fps), eliminating the frame drops users experience today
• Auto-save latency: under 100 milliseconds per answer, compared to approximately 500ms for the current full-form save
• Memory usage with 1,000 units: under 15MB, compared to approximately 50MB today

Key Decisions

1. Per-question auto-save to the server -- Rather than saving to the browser's local storage (which would be lost when switching computers), each answer saves directly to the server. This is a lightweight, frequent write -- updating a single temporary field on the answer record -- rather than the current approach of serialising the entire form.

2. Virtual scrolling -- Only the questions visible on screen are rendered in the browser. As the annotator scrolls, new questions are loaded and off-screen questions are removed from memory. This keeps performance constant regardless of the total number of questions.

3. Immutable session snapshots on submit -- When an annotator clicks Submit, the system creates a permanent record that captures the exact answers at that moment, linked to the exact question versions that were active. This snapshot can never be modified, providing a tamper-proof audit trail.

4. Candidate blinding enforced at the system level -- Annotators can only see their own answers, never another annotator's. This is enforced in the backend, not just in the user interface, ensuring that the blinding guarantee holds even if someone tries to bypass the front end.

5. Built with next-generation form technology -- The form uses Angular's newest form system (signal-based forms), which provides the performance characteristics needed for large question sets. The technology was verified as viable in Phase 1.

How It Connects

Phase 5 depends on Phase 4 (Question Lifecycle) for the versioned question model it reads from. It feeds into: - Phase 6 (Question Management UI) -- Administrators use the preview tab to see exactly what the rebuilt form looks like - Phase 10 (Reconciliation) -- The reconciliation view reuses the form components, adding a side-by-side comparison mode where reconcilers see anonymised candidate answers alongside their own form

---

See also: Platform Architecture | Technical Spec Related briefs: Question Lifecycle | Question Management UI