Skip to content

Roadmap

Jump to bottom
Wouter Meetsma edited this page Jun 13, 2026 · 48 revisions

Development Roadmap

🎯 Overview

RubricMaker is an offline-first rubric creation and grading tool for educators. This roadmap outlines completed features, current work in progress, and planned development phases.

✅ Completed Phases

Phase 0: MVP & Core Features (Launched)

  • ✅ Rubric builder with multiple scoring modes (Total Points, Weighted, Single-Point)
  • ✅ Interactive grading interface with score modifiers
  • ✅ CEFR framework integration (Can-Do statements)
  • ✅ Student self-assessment & peer review
  • ✅ Essay assignments with rich text editor
  • ✅ Analytics dashboard with class statistics
  • ✅ Multi-format export (PDF, DOCX, CSV)
  • ✅ Student portal with shareable links
  • ✅ Offline-first architecture with localStorage
  • ✅ Basic theme customization

Status: Stable and feature-complete for core education workflows

Phase 1: Cloud Sync & Collaboration (Completed)

PR #128 — Final Three Roadmap Items

#15 — Sync Conflict Resolution ✅

Supabase-first implementation with intelligent merge strategy

  • src/utils/syncMerge.ts replaces wholesale spread operations at all three hydration sites
    • Startup sync
    • Network reconnect hydration
    • In-page OTP sync
  • Strategy: Remote as baseline (preserves deletions); locally queued edits protected from stale data; pending deletes not resurrected
  • Rubrics only: Last-write-wins (LWW) on updatedAt — other collections carry event timestamps (gradedAt, submittedAt) only
  • Offline-first preservation: Changes queue locally, sync on reconnection
  • Test coverage: 1263/1263 unit tests passing; e2e spec 17-offline-sync-merge.spec.ts (static validation + CI coverage)

#18 — Cambridge English Framework ✅

CEFR ↔ Cambridge Exam mapping + vocabulary API integration

  • Static CEFR-to-exam mapping (src/data/cambridgeExams.ts)
    • A2 Key → C2 Proficiency coverage
    • Function: cambridgeExamForLevel()
  • UI: Opt-in showCambridgeLabels setting renders "B2 · FCE" labels alongside CEFR badges
    • Visible on CEFR overview page
    • Shown on student profile pages
  • API Integration: Previously unused cambridgeApi.lookupWord() now wired to vocabulary editor
    • Admin-configured API key required
    • Enriches vocab items with CEFR level + definition
    • Offline-first: fully hidden without key, fills empty fields only
  • i18n: New cambridge.* namespace added to 5 locales with parity tests

#23 Phase 2 — Full Theme Bundles ✅

One-click theme presets + tonal accent scales + Google Fonts support

  • 5 Theme Bundles (src/data/themes.ts)
    • Academy, Nature, Midnight, Warm, Slate
    • Visual card picker in Settings → General
    • Atomic update: single updateSettings call with new colorPreset field
  • Tonal Scale Generation (src/utils/accentScale.ts)
    • --accent-50..900 scale via CSS color-mix() in oklab
    • Applied globally from AppContext
  • Export Fonts
    • DOCX: headings/body honor rubric format font via document styles
    • PDF: 5 new decorative Google Fonts (Playfair Display, Oswald, Bebas Neue, Special Elite, Courier Prime)
    • Format picker: live preview included
    • Export pathway: fonts injected at generation time
  • i18n: New themes.* namespace added to 5 locales with parity tests

Test Results: 123 new unit tests + 1 new Playwright spec; full suite: 1263/1263 passing, typecheck and lint clean

🚀 In Progress

Phase 2.1 — Multi-Device E2E Testing 🚧 (branch feat/multi-device-e2e)

  • Added secondSupabasePage fixture to e2e/fixtures/supabase.fixture.ts — a second browser context signed in as the SAME test user (shares testUserEmail with supabasePage), enabling true two-device tests
  • New e2e/specs/18-multi-device-sync.spec.ts: basic propagation (device A edits, device B reloads and sees it), simultaneous-edit/LWW race (the device that saves last wins the whole record, per syncMerge.ts), and network-partition resilience (offline edit on A flushes after reconnect without disturbing a concurrent online edit on B)
  • The old test.skip "Multi-device propagation" placeholder in 17-offline-sync-merge.spec.ts is removed
  • typecheck/lint/unit suite (1283/1283) clean
  • Outstanding: new specs are statically reviewed and register correctly with Playwright, but have not yet run against a real local Supabase stack — no Docker daemon was available in the dev sandbox. Run npm run db:start && npm run e2e:supabase once Docker (Desktop/colima/orbstack) is available and iterate as needed before merging.

Phase 2.2 — LWW for all editable collections ✅ (done, PR #129 merged)

  • StudentRubric.updatedAt added; set on every grade/peer-review save and self-assessment submit
  • updatedAt also added to Class, Student, GradeScale, CommentSnippet, CommentBankItem, SelfAssessment, SpeakingSession, DocumentAnalysisResult — set on every create/update via the AppContext reducer
  • syncMerge.ts now applies LWW to all 10 of these collections (previously rubrics-only)
  • attachments, exportTemplates, and favoriteStandards intentionally left out — add/delete-only, no update action, so pending-queue protection already covers their conflicts
  • 1283/1283 unit tests passing, typecheck and lint clean

Phase 2.3 — Wiki Documentation Cleanup ✅ (this session)

  • Added a "Cambridge English exam labels" guide to Features.md
  • Added a "Themes & Appearance" section to Features.md (theme bundles, tonal accent scale, export fonts)
  • Added a "Conflict resolution & sync strategy" section to Supabase-Sync.md documenting LWW, pending-queue protection, deletion handling, and known limits
  • The previously-noted "#38/#39/#40 marked Planned" cleanup item was checked against the current wiki — no page outside this Roadmap references those numbers as "Planned", so no further action was needed there

📊 Next Phases

Phase 2: Infrastructure Stabilization (Immediate Post-Merge)

2.1 Multi-Device E2E Testing 🚧 In Progress

  • Upgraded secondSupabasePage fixture (shares testUserEmail with supabasePage) ✅
  • Race condition scenarios: simultaneous edits across devices ✅
  • Network partition resilience validation ✅
  • Sync state consistency under network failures ✅
  • Owner: Followed spec-14 pattern from existing e2e suite
  • Priority: HIGH — foundational for multi-device feature stability
  • Remaining: run npm run db:start && npm run e2e:supabase against a real local Supabase stack (no Docker daemon was available when the spec was written) and merge feat/multi-device-e2e
  • Note: e2e/specs/17-offline-sync-merge.spec.ts now passes in CI (post PR #128). Two lessons it taught, relevant for the multi-device fixture work:
    1. Sync adapters return { success: false } instead of throwing — pushOne must check the SyncResult, or offline writes are silently dropped instead of queued.
    2. In the Supabase Playwright project, data seeded only into localStorage is wiped by post-reload hydration — seed matching rm_pending_sync upsert entries so the startup flush re-pushes it.

2.2 Extend Last-Write-Wins (LWW) to Remaining Collections ✅ Done

  • LWW now covers rubrics, grades (studentRubrics), peer reviews, classes, students, grade scales, comment snippets, comment bank items, self-assessments, speaking sessions, and analysis results — all via an updatedAt field set on every save and compared in syncMerge.ts
  • attachments, exportTemplates, favoriteStandards are add/delete-only (no edit action) — pending-queue protection already covers them, LWW would add no value
  • No DB migrations needed — all data columns are jsonb, so the new updatedAt field flows through automatically
  • Impact: Enables distributed grading sessions, multi-teacher rubric curation, and concurrent class/student roster edits

2.3 Wiki Documentation Cleanup ✅ Done

  • Verified items #38, #39, #40 are not referenced as "Planned" anywhere else in the wiki — no further status update needed
  • Added visual guides for Cambridge exam framework to Features.md
  • Added theme customization tutorial (theme bundles, accent scale, export fonts) to Features.md
  • Documented LWW sync strategy & conflict resolution limits in Supabase-Sync.md
  • Priority: MEDIUM — UX clarity for adopters

Phase 3: EFL Classroom Enhancements (Month 1–2) ✅ Done

Implemented across four merge waves (branch feature/phase-3-efl-enhancements): Wave 1 — shared infra + test data layer (2ceeeec); Wave 2 — recordings, vocab dashboard, peer analytics, testing UI (45249a7); Wave 3 — test results, class-average adjustment, live monitor (d9f71b9); Wave 4 — e2e test-environment lifecycle + docs (f7e2ae8).

3.1 Speaking Session Recordings ✅

  • Audio/video recording via useMediaRecorder + IndexedDB blob store (src/services/mediaStore.ts) — blobs never touch localStorage/quota
  • Wired into SpeakingSession.tsx; read-only playback in the student portfolio (StudentProfilePage.tsx)
  • Privacy-first: audio allowed local-only (persistent on-device warning banner); video gated behind a configured Supabase database (session-length video doesn't fit a device-only model)
  • Optional cloud sync via RecordingSync.ts (private recordings bucket, 50 MB cap, signed-URL cache); deleting a session cascades to local + cloud blobs
  • Migration 034_recordings_storage.sql

3.2 Vocabulary Profiling Dashboard ✅

  • New /vocabulary route (VocabularyDashboardPage.tsx) with per-student/class CEFR vocabulary distribution charts (VocabCefrDistributionChart.tsx, A1→C2 stacked bars)
  • src/utils/vocabProfileAggregator.ts aggregates DocumentAnalysisResult.levelCounts
  • Open CEFR-banded word lists (src/data/openCefrVocabulary.ts) merged into cefrVocabularyProfiler.ts — reduces reliance on the paid Cambridge API (kept as optional definitions-only enrichment)
  • CSV export of vocab lists filtered by CEFR band

3.3 Peer Review Analytics ✅

  • StudentRubric.gradedBy now populated on peer-review save — peer feedback is traceable ("Anonymous reviewer" only when absent on older data)
  • New /peer-analytics/:rubricId route (PeerReviewAnalyticsPage.tsx): consistency scoring (mean abs deviation vs. teacher baseline), per-reviewer leniency bias, inter-rater spread, comment-frequency heatmap (reusing CriterionHeatmap.tsx), round-over-round trends
  • src/utils/peerReviewAggregator.ts (+ tests covering missing-baseline / missing-gradedBy)

3.4 Testing environment ✅

  • Full Test/StudentTest/TestQuestion/ProctorEvent data model, synced via the standard LWW collection pattern (migrations 033–034)
  • Teacher: /tests list + builder (TestBuilderPage.tsx) with MC/short-answer/open questions, CEFR/Standards linking, requireSEB toggle, share-link assignment modal (offline links embed the full test for no-DB use)
  • Student: /test/:code (StudentTestPage.tsx) — no-auth, draft autosave, optional timer, SEB advisory gate (SebGate.tsx, UA-based — documented as deterrent only, not enforcement)
  • Results: /tests/:testId/results/:studentTestId (TestResultsPage.tsx) — auto-scored MC/short-answer, manual grading for open questions, per-standard/CEFR rollups, grade-scale mapping
  • Class-average adjustment: ClassAverageAdjuster.tsx + testCalc.ts — reversible, auditable adjustment field, raw scores preserved
  • Live monitor: /tests/:testId/monitor and /essays/:assignmentId/monitor (LiveMonitorPage.tsx), Formative-style presence/response-grid/live-draft preview, built on the generic useLiveSessionTelemetry hook (tab-switch/copy-paste/battery/heartbeat) and proctorAggregator.ts; offline mode falls back to post-hoc event-log review
  • e2e: 19-test-environment.spec.ts — full offline lifecycle (build → assign → take → submit with proctoring telemetry → import → grade → adjust), green on chromium/firefox/webkit
  • Docs triple-update (DocsPage ROUTE_TREE, README routes table, LandingPage feature cards) completed for all of 3.1–3.4

Verification (WP5): supabase/bootstrap.sql regenerated from 34 migrations (no drift); typecheck clean; lint 0 errors (138 pre-existing any warnings); full unit suite 1475/1475 passing across 99 files; coverage 64.0% lines / 62.6% statements / 54.9% branches / 52.7% functions (all above the 50%/37% thresholds); i18n parity green for en/nl/fr/de/es. e2e: 243 passed, 1 skipped; the only failures are pre-existing and unrelated — 12-navigation.spec.ts on mobile-chrome (fails identically on main, tracked separately) and the supabase project specs (14–17, 19-test-environment.spec.ts firefox flake under full-suite load — passes in isolation), which require npm run db:start (no Docker daemon in this dev sandbox, same outstanding item as Phase 2.1).

Phase 4: Admin & School Operations (Month 2–3)

4.1 Admin Panel Hardening

  • User Roles: Expand teacher-only to admin/observer roles
  • Data Retention: Auto-purge old grades, GDPR deletion workflows
  • Student Anonymisation: Support for external/standardized assessments
  • Audit Log: Track all edits, exports, role changes
  • Estimated effort: 3–4 weeks

4.2 Magister SIS Integration

  • Bulk import students + classes from Dutch VO schools
  • Ongoing sync: add/retire students dynamically
  • Mock API testing for common scenarios
  • Note: Docstring present in codebase, validation needed
  • Estimated effort: 2–3 weeks

4.3 Self-Hosting Operations

  • Validate & update HestiaCP & Virtualmin guides against latest Docker compose
  • Backup/restore automation with cross-version migration testing
  • Monitoring: CPU/memory alerts, Supabase quota tracking
  • Estimated effort: 2 weeks

Phase 5: UI/UX Polish (Month 3–4)

5.1 Mobile Grading Experience

  • Touch-friendly rubric level input (replace sliders for mobile)
  • Sticky score summary during grading
  • Responsive tests: iOS/Android, iPad portrait mode
  • Estimated effort: 2–3 weeks

5.2 WCAG 2.1 AAA Audit

  • Current: AA compliant (axe-core in CI)
  • Stretch Goals:
    • Focus management for complex workflows
    • Color contrast audits on new theme bundles
    • Keyboard navigation for rubric builder
  • Tool: axe DevTools + manual screen reader testing
  • Estimated effort: 2–3 weeks

5.3 Help & Documentation

  • In-app: Video tours (create rubric, grade, export)
  • Tooltips: Complex features (score modifiers, LWW sync behavior)
  • Multilingual: EN, NL, FR, DE, ES
  • Estimated effort: 2–3 weeks

Phase 6: Strategic Features (Future Roadmap)

6.1 Student Learning Paths

  • Recommend next rubrics based on CEFR targets & past performance
  • Teacher dashboard: cohort analysis, outlier identification, intervention flags

6.2 Rubric Marketplace

  • Community template sharing (CC-BY-SA)
  • Voting & discoverability by subject/level
  • Minimal backend API for metadata

6.3 Integration Ecosystem

  • LMS: Canvas, Blackboard, Moodle (LTI 1.3)
  • Data Feeds: Clever CSV, OneRoster (for large districts)

📌 Known Issues & Technical Debt

Issue Impact Owner Priority
e2e offline sync not tested locally (Docker unavailable at PR #128 write time) Offline sync race conditions untested in CI Dev HIGH — confirm e2e passes post-merge
Multi-device e2e specs (18-multi-device-sync.spec.ts) not yet run against a real Supabase stack — no Docker daemon in dev sandbox Multi-device propagation/LWW/partition scenarios statically reviewed but unverified end-to-end QA HIGH — run npm run db:start && npm run e2e:supabase and merge feat/multi-device-e2e

📋 Quick Reference: Recent PR Links

🎓 Development Notes

For Contributors

  1. Before merging PR #128: Confirm e2e suite passes in CI with Docker stack
  2. Branch feat/multi-device-e2e: run npm run db:start && npm run e2e:supabase against a real local Supabase stack and merge once green
  3. Month 1 Priority: Stabilize sync infrastructure (Phase 2) before new EFL features
  4. Tech Stack: TypeScript + React; Supabase for optional cloud sync; Playwright for e2e

Testing Standards

  • Unit tests: Vitest (target >90% coverage)
  • E2E tests: Playwright (spec-14 pattern for async operations)
  • i18n: Parity tests across EN, NL, FR, DE, ES locales
  • Accessibility: axe-core in CI (WCAG 2.1 AA minimum)
  • Performance: Offline-first validation; sync latency benchmarks for > 100 rubrics

Last updated: 13 June 2026 (Phase 3 — EFL Classroom Enhancements — complete)

Clone this wiki locally