Spec 01 Product Context - SekiroKenjii/Quizzivy GitHub Wiki

Section of Quizzivy — Frontend Portal & Data Model Specification · Next

1. Product context

Quizzivy is a web app supporting a private English-teaching practice. Students take tests assigned by their teacher; the teacher/admin builds tests, assigns them, monitors attempts, grades open answers, and reviews results.

v1 ships one capability end-to-end: test-taking. Later versions add vocabulary practice, homework, pronunciation drills, and class management. v1 must not paint us into a corner for those, but must not build them either.

1.1 Personas

Persona	Built-in role	Description
Owner	Admin	Runs the practice and teaches in it. Holds every permission ("Take tests" only when turned on) and reaches every teacher's data (`scope.all`). Works in the teacher console until R5 builds the Admin console. Desktop/tablet only.
Teacher	Teacher	Builds tests, manages students and classes, grades, reads results, over the classes and content they own. Desktop/tablet only. Data-dense UI is fine.
Student	Student	Joins a class with a code, takes assigned tests, sees own results. Often on a phone. Needs a calm, focused UI.

Roles are data (app.roles), one per user (users.role_id). The four built-in roles are Admin, Teacher, Assistant and Student; their grants from the permission catalogue are in docs/plan/70-redesign-overview.md §4.1, and §5 says how they are enforced. The Assistant role exists with the deck's grants; until the deck draws class staff, no class has an assistant and no role picker offers the role (D14, 70 §1). No screen creates a role or a staff account before R5.

1.2 Goals (v1)

A student can join a class and complete an assigned test on a phone without losing work on refresh, tab close, or brief network loss.
The admin can author a test with mixed question types — including listening — in under 15 minutes without reading docs.
Every attempt is reviewable: answers, timing, score breakdown, and an integrity timeline.
Codebase is structured so the next feature (e.g., vocabulary sets) is a new folder under features/, not a rewrite.

1.3 Non-goals (v1)

Payments and subscriptions. The AI assistant's credits (§13.10) are a budget that stops the assistant, not a payment: the product bills nobody and takes no card. What the centre spends with the provider is paid for outside Quizzivy.
An AI that decides. The assistant suggests; a teacher accepts, edits or drops. Nothing it returns is saved as a grade, a question or a comment by itself, and no AI response reaches a student.
Open public sign-up. Self-signup exists but is gated behind a class join code (§6). There is no "create an account" entry point without one.
Multi-tenant / multiple schools. One organization with several teachers. Each class, test, question, question group and media asset has an owning teacher, and each Word import its creator (§5); the Admin reaches them all. No org/tenant scoping in the schema.
Hard proctoring — webcam, screen recording, screen-lock, remote inspection. §10 covers browser-signal monitoring only; see §10.5 on its limits.
Audio transcoding, trimming, or waveform editing. Upload, validate, serve. Nothing more (§11.2).
Speaking/recording questions. Students listen in v1; they do not record. That is a separate feature with its own storage, consent, and grading model.
Rich analytics dashboards. Per-test and per-student score tables only.
Native mobile apps. Responsive web only.
Real-time collaborative authoring. One person edits at a time.