Test-taking
Multiple choice, fill-in-the-blank, and written exercises. Students can move between questions and revise answers before final submission.
A requirements and architecture reference for an offline-capable language test app, with live classroom monitoring, teacher-reviewed AI scoring, and role-aware analytics.
Students complete assigned tests; teachers and administrators review results, written responses, and learning patterns.
Multiple choice, fill-in-the-blank, and written exercises. Students can move between questions and revise answers before final submission.
Objective questions are evaluated immediately on submission. Written responses can be AI-scored in batches, then verified or adjusted by a teacher.
Separate views support teacher evaluation, monitoring the current student roster, and administrator-wide comparisons.
Permissions follow responsibility: platform-wide oversight for admins, assigned-class management for teachers, and personal testing/results for pupils.
HTTP/API requests use JWT validation. WebSockets authenticate on the first message, then retain the verified identity across Durable Object hibernation.
JWT held in JS memory; reconnect resends it.
{type:'auth', token}
Validates JWT; stores identity with ws.serializeAttachment().
DO wakes, reads identity from attachment; no repeat JWT validation needed.
/api/auth/login.JWT_SECRET from Workers Secrets.sub, role, email, optional teacher_id, must_change_password, and exp.users.password_hash.must_change_password marks temporary credentials; record password_changed_at.Generate random temporary password.
Hash and store; set must_change_password=true.
Credential is communicated in person/by phone; sign in and change it.
JWT.sub matches the userId in the start message. Mismatch or invalid/expired JWT closes the connection.A pupil may change teachers. The current roster changes, but historical test responsibility does not.
At test completion, store the responsible teacher_id as it was at that time. Never rewrite it after a reassignment.
One current teacher per pupil, course, and test type. Update this row when the pupil moves.
Record assignment and unassignment timestamps and reason, preserving the full teaching history.
| View | Filter / source | What it includes | Purpose |
|---|---|---|---|
| My Teaching | test_sessions.teacher_id = meR2 weekly JSON ( perTeacherSubject) | Only tests for which this teacher was responsible, including tests that remain in their history after a pupil moves away. | Admin evaluation of a teacher’s effectiveness. |
| My Students | Current assignments joined to test sessions in D1 | Every result belonging to pupils currently assigned to this teacher, including results earned under previous teachers. Show the historical teacher_id. | Monitor current pupils and their complete history. |
Current assignment: X → A
Tests 1–2 record teacher_id=A.
Current assignment: X → B; history closes A assignment. Tests 3–4 record teacher_id=B.
My Teaching: tests 1–2 remain.
My Students: X no longer appears.
My Teaching: tests 3–4.
My Students: tests 1–4; prior teachers are identified.
Only tests 1–2 are attributed to A.
Example: “The ___ cat sat on the ___ mat.”
Written answer is queued only now.
Answer and session are persisted.
Batch up to 5 answers per AI call; process pending backlog.
Teacher reviews or adjusts per-criteria scores.
Recalculate session score.
Teacher enters per-criteria scores → status becomes final. AI batch skips manually finalized answers.
If a 429 / neuron limit occurs, stop gracefully. Remaining answers stay pending_ai and are picked up on a later hourly run (after daily reset if needed).
@cf/meta/llama-3.1-8b-instruct-awq is the recommended model in the requirements; teacher verification remains authoritative. The source warns against models it says were planned for deprecation on 20 Nov 2026.
The source also lists a later 70B upgrade as a possible option, with roughly 2× cost.
SvelteKit serves pages and APIs. Teacher-scoped Durable Objects manage live WebSocket activity; D1 is the operational record, while scheduled aggregation writes weekly analytics to R2.
JWT_SECRETReads new sessions, aggregates weekly stats, writes R2, updates KV sync timestamp.
Objects such as stats/2026-W46 and stats/2026-W47.
Stores last_aggregated_at for incremental aggregation.
Batch scoring of written exercises, initiated by hourly cron.
Transient session state, cached questions, and live classroom board; purge entries older than 16 hours.
Worker validates JWT and serves SSR page.
Worker upgrades and routes to Teacher DO.
Send JWT; DO verifies and stores identity.
Check JWT subject; load/cache questions from D1.
Prev, next, jump; saved answers remain editable.
Evaluate objective answers; queue written answers; write D1 session and scores.
Hourly aggregation reads new completed sessions from D1, aggregates in Worker memory, merges the weekly JSON in R2, and advances the KV timestamp.
pending_review and current teacher.Read entirely from the Teacher DO’s live_sessions table; no D1 or R2 read is required for the live view.
Hourly schedule or teacher/admin request.
Read last_aggregated_at.
Read newer completed sessions (source query uses LIMIT 1000).
Per-question, per-teacher/subject, question-type/subject; merge weekly data.
Write weekly stats and update sync timestamp.
| Visualization | Data source | Audience / view |
|---|---|---|
| Tests over time · line | R2 weekly JSON | Teaching / Students |
| Time per question · box plot | R2 or D1 | Teaching / Students |
| Choice distribution · bar per question | R2 or D1 | Teaching / Students |
| Fill-blank choice distribution · grouped bar per blank | R2 or D1 | Teaching / Students |
| Written criteria scores · radar/bar | D1 written_scores | Teaching |
| Teacher comparison by subject type · grouped bar | R2 weekly JSON | Admin |
| Correct % by question type × subject · heatmap | R2 weekly JSON | Admin |
| Student lookup · table + answer detail | D1 test_sessions | Teaching / Admin |
| Question type | Past / present | Future tense | Adjectives | Articles |
|---|---|---|---|---|
| Multiple choice | 85% | 72% | 90% | 68% |
| Fill in the blank | 78% | 65% | 82% | 70% |
| Written exercise | 70% | 58% | 75% | 55% |
Illustrative values copied from the requirements, not live application data. The source describes ≥80%, 60–79%, 40–59%, and <40% bands. Suggested drill-down: find which teachers contribute to weak areas via perTeacherSubject.
| Student | Started | Duration | Question states (example) | Session |
|---|---|---|---|---|
| Alice | 14:02 | 12:34 | Correct Wrong Correct Awaiting | Running |
| Bob | 14:05 | 08:12 | Correct Correct Awaiting | Running |
| Carol | 13:55 | 21:07 | Correct Wrong Correct | Completed |
Written exercises use a pending-review state. Completed or abandoned sessions are marked with timestamps; stale running sessions are purged after 16 hours of inactivity.
The source defines seven tables covering identity, assessment, scoring, assignments, and approval workflow.
usersStudents, teachers, admins
id PK, email unique, password_hash, role, teacher_id, must_change_password, password_changed_at, disabled, created_at, created_by.
questionsQuestion bank
id PK, test_type, language, level, question_type, subject_type, prompt, choices/correct answer fields, blank definitions, criteria, position.
test_sessionsImmutable test receipt; teacher frozen at test time
id PK, user_id, teacher_id, test_type, language, level, score, question count, status, start/completion timestamps, duration, answers_json.
written_scoresAsync written scoring
Composite PK: (session_id, question_id). Includes user/teacher IDs, response text, per-criteria AI/final score and feedback JSON, overall AI/final scores, status, AI evaluation and human verification timestamps, verifier.
student_teacher_assignmentsCurrent roster; mutable
PK: (student_id, course, test_type). Stores current teacher_id and assigned_at.
assignment_historyAppend-only audit trail
id PK, student/teacher IDs, course, test type, assigned/unassigned times, reason.
deletion_requestsAdmin approval for pupil deletion
id PK, student ID, requester, request time, pending/approved/rejected status, approver, approval time.
The source models a 30-question test with 20 multiple-choice, 5 fill-blank (3 blanks each), and 5 written exercises. Figures below reflect that model and the source’s Nov 2026 limits.
Bar lengths are normalized for visual ranking, not a linear common-capacity scale. Per-test capacity values are shown exactly as provided in the source model.
| Resource | Free limit stated in source | Reset / scope |
|---|---|---|
| Worker requests | 100,000 / day | Midnight UTC |
| Durable Object requests | 100,000 / day | Midnight UTC |
| DO duration | 13,000 GB-s / day | Midnight UTC |
| DO SQLite rows read / written | 5,000,000 read / 100,000 written per day | Midnight UTC |
| DO SQLite storage | 5 GB | Total |
| D1 rows read / written | 5,000,000 read / 100,000 written per day | Midnight UTC |
| D1 storage | 5 GB | Total |
| R2 Class A / B | 1,000,000 writes / 10,000,000 reads | Monthly |
| R2 storage | 10 GB | Total |
| KV reads / writes | 100,000 reads / 1,000 writes per day | Midnight UTC |
| Workers AI neurons | 10,000 / day | Midnight UTC |
| Queues operations | 10,000 / day | Midnight UTC |
200 students, 10 teachers, 3 admins; each student takes one test per week: about 29 tests/day.
The source concludes the scenario fits the free tier; Workers AI is the highest listed use at 13.3%, while KV writes are listed at 2.4% and cron D1 reads at 8.9%.
The source separately describes a batched-AI strategy of ~8 neurons per answer, or ~250 tests/day with 5 written answers per test. Keep these estimates distinct: the capacity table’s ~217/day uses ~46 neurons/test.
Admin dashboard → POST /api/admin/users with email and role → SvelteKit writes to D1 → temporary password returned and communicated verbally.
Teacher dashboard → POST /api/teacher/pupils with email → D1 user + assignment rows → temporary password returned and communicated; pupil is assigned to creator.
Set users.disabled=1; login is blocked by auth hook. Data is retained; user can be re-enabled.
Teacher requests deletion and types the pupil’s email to confirm. Delete user and related assignment/test/score data; no admin approval needed.
Create pending deletion request. Admin approves to delete related data or rejects to retain pupil. Teacher cannot unilaterally delete a pupil with history.
POST /api/assignments with student, new teacher, course, test type.
Set unassigned_at to now for current assignment.
Delete old assignment; insert new current assignment.
Insert new teacher with assigned_at=now.
test_sessions.teacher_id is unchanged; admin can inspect full assignment history.| Threat | Mitigation in requirements |
|---|---|
| Student takes a test as another student | Teacher DO requires JWT sub to match start.userId. |
| Teacher sees another teacher’s students | Check JWT role and teacher_id in every API route. |
| Student accesses admin dashboard | Role check in auth hook; admin routes reject non-admin JWTs. |
| Teacher deletes a pupil with history without approval | Require admin approval if the pupil has logged in. |
| Password exposure | Bcrypt hash (cost 10); keep JWT_SECRET in Workers Secrets. |
| WebSocket hijack | JWT is the first WebSocket message; DO validates before accepting other messages. |
| Disabled user signs in | Auth hook checks users.disabled=0. |
| JWT replay after disable | 7-day JWT expiry plus a disabled-flag check before starting a test or opening a new WebSocket connection (one D1 read). |