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

---

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗