Opacity — Dyslexia Screening Platform
Opacity is a web-based platform that screens for early signs of dyslexia through interactive browser games. Designed for children, parents, and teachers, it uses evidence-based cognitive assessments delivered through engaging gameplay.
Status: All five game API/UI implementations are present. The dashboard's main UI is a placeholder. The Rello Random Forest now has an optional website research demo at /research/rello, backed by ml/service/. Actual Opacity gameplay classification and child report generation are not implemented.
Overview
What is Opacity?
Opacity screens for dyslexia risk through five short, game-like cognitive assessments. The platform supports:
- Children: Play games as guests (no login required) or as registered profiles under a parent account
- Parents: Create accounts, manage multiple children, view risk reports and progress over time
- Teachers: Create or join classrooms, monitor classroom-wide risk screening results (no access to individual session data outside their classroom)
The output is a risk band (low/moderate/elevated), never a diagnostic label. This is a screening tool, not a diagnostic tool.
Key Features
- ✅ Anonymous Guest Play — Play without account setup; claim account later by adding an email
- ✅ Server-Side Grading — All scoring, trial validation, and correctness judgments happen on the server, never in the browser
- ✅ Row-Level Security (RLS) — Every table protected at the database layer; a child's data is invisible to other children by default
- ✅ Adaptive Difficulty — Game difficulty adjusts based on
skill_states stored per child
- ✅ Session Replay — Complete stimulus plans are stored, enabling session replay for QA/debugging
- ✅ Anti-Tampering — Clients send only raw responses (what they chose, when); servers compute correctness independently
- ✅ Accessibility — WCAG 2.1 AA compliance with semantic HTML, keyboard navigation, focus indicators, and reduced-motion support
Architecture
Browser (React 19, Next.js 16, App Router)
│
├─ Supabase browser client (anon key, RLS-scoped)
│
▼
Next.js Route Handlers (frontend/app/api/**/route.ts)
│
├─ Supabase server client (cookie-bound, anon key)
├─ Supabase admin client (service role key, server-only)
│
▼
Supabase (Postgres + Auth + RLS)
Route handlers provide the game and account backend. A standalone FastAPI research service under ml/service/ serves the frozen Rello benchmark to /api/research/rello. Setup instructions cover model installation and the optional demo flag. Product ML scoring and Whisper transcription remain planned; Rello features cannot be substituted with gameplay scores.
Security Model
- RLS is the security boundary, not application code. If a route handler has a bug, the database still refuses unauthorized queries.
- Anonymous auth is native: a "guest" is a real
auth.users row with a real JWT. No separate guest code path.
- Service role key is master-only: bypasses RLS entirely, imported only in
frontend/lib/supabase/admin.ts, used only in server-only code (route handlers).
Tech Stack
| Layer | Technology |
|---|
| Frontend | React 19, Next.js 16, TypeScript, Tailwind CSS, shadcn/ui |
| UI State | Zustand, TanStack React Query |
| Database | Supabase (Postgres + Auth + RLS) |
| API | Next.js route handlers, REST |
| Validation | Zod |
| Animations | Motion, Cuelume (haptics), tw-animate-css |
| Auth | Supabase Auth (email/password + anonymous) |
| ML | Python research baseline and FastAPI demo under ml/; product scoring, XGBoost/SHAP and Whisper remain planned |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
