Technology stack

The web app

Browser + Cloudflare Workers

One responsive web app serves pupils, teachers, and administrators. The browser handles recording and interaction; server code checks access and coordinates the work.

Next.js 16, React 19 & TypeScript

Next.js App Router provides pages, server rendering, and API route handlers. React builds the interface, while TypeScript checks the shapes of data shared across the web application.

Tailwind CSS 4 & custom CSS

Tailwind supplies layout and styling utilities through PostCSS. Shared CSS defines READSmart’s colors, typography, reading layouts, and responsive components.

PWA & browser APIs

A web app manifest and service worker support the PWA. MediaRecorder captures microphone audio; IndexedDB holds pending classroom submissions for retry when a connection returns. Speech recognition still needs the server.

Auth.js & classroom accounts

Auth.js handles credential-based sign-in. Application checks scope access to the person, role, school, and classroom. Teachers create student credentials, so pupils do not need personal email accounts.

MDGFMResearch pages

react-markdown and remark-gfm render the published research findings, including tables and links.

Trade-off

A shared web app reduces separate device-specific builds, but microphone support, browser storage, and connectivity still vary across devices.

Hosting, data & storage

Cloudflare

The application, structured records, and stored audio have distinct responsibilities. This keeps large recordings out of the database and access decisions in the API.

Workers & OpenNext

OpenNext adapts the Next.js application to Cloudflare Workers. Workers serve the application and its API; static assets deliver the built browser files.

D1 & Drizzle ORM

Cloudflare D1 stores SQLite tables for accounts, classrooms, passages, jobs, and results. Drizzle gives the TypeScript application typed queries and a shared schema; Drizzle Kit generates SQL migrations.

S4R2 & aws4fetch

Private R2 buckets hold classroom audio, temporary demo audio, and generated practice artwork. aws4fetch signs upload URLs so a browser can send audio directly to R2. The Worker checks the recording and stores its metadata.

Email Sending

The Cloudflare EMAIL binding sends staff verification, password-reset, and onboarding messages from the application.

Trade-off

This arrangement uses one hosting platform for the web services, but it depends on Cloudflare bindings, service limits, and deployment tooling. Audio and database retention must be coordinated.

Getting a recording processed

Cloudflare → RunPod → Worker API

Uploading audio and analysing it are separate steps. A durable job record lets the system track processing, recover interrupted work, and return results to the right recording.

Queues & D1 job leases

A Cloudflare Queue delivery wakes the RunPod endpoint. The GPU worker claims an eligible job through the Worker API; D1 holds the authoritative job state and processing lease.

Cron Triggers

A scheduled Worker runs every minute to maintain jobs and retention, retry eligible work, and wake RunPod while queued work remains.

Protected result endpoints

The GPU pipeline downloads the authorised audio and posts its measurements back through the Worker API. It never connects to D1 directly. The dashboard reads the saved result for teacher review.

Trade-off

Results are asynchronous. Queue time, GPU startup, and processing add delay; retries and leases are needed when either service is interrupted.

Speech processing & measurement

RunPod Serverless GPU + local research environment

GPU compute handles the work that would be too demanding for a pupil’s phone. The RunPod handler reuses the Python processing pipeline, which can also run as a local polling worker.

Python, Docker, PyTorch & CUDA

A Docker image packages the pipeline and its audio tools for RunPod Serverless. PyTorch uses CUDA on the GPU. FFmpeg converts audio; SoundFile supports audio input, output, and duration measurement.

WXSilero VAD, OpenAI Whisper & WhisperX

Silero VAD detects speech regions. OpenAI Whisper transcribes the recording, and WhisperX aligns words with audio timestamps. Whisper model size is configurable and evaluated through the model-size experiment.

JiWER & recording-level scoring

JiWER supports word error rate measurement. The pipeline compares the transcript with the reference passage and calculates raw reading measurements. Word highlighting is an unvalidated assistive view of differences, not mispronunciation detection.

scikit-learn, NumPy, pandas & Pingouin

The research workflow uses these tools for feature preparation, calibration regression, and agreement analysis. Grade and language are required calibration features. Runtime WCPM correction uses exported coefficients when applicable; it does not train a new model for each reading. Continuous agreement is assessed with ICC and Bland–Altman analysis.

Trade-off

GPU processing introduces compute cost and startup time. Transcripts, alignment, and calibrated measurements can still be wrong, so teachers retain final judgement.

Original practice & illustrations

Cloudflare Workers AI

Practice generation is a separate AI workflow from oral-reading assessment. It creates draft reading material and artwork within consent, school-policy, and usage limits.

MiMistral Small 3.1, Llama 3.3 & Llama Guard 3

Workers AI runs Mistral Small 3.1 24B to write each passage as plain text, rewriting until it fits the grade's word and readability ranges; in our September 2026 tests it kept to a word count and wrote natural Filipino where Llama 3.3 70B wrote 8–45 words when asked for 55–200. Llama 3.3 70B then labels the passage in JSON mode, reviews its facts and writes the comprehension questions; Llama Guard 3 8B moderates. Fact-review findings are flagged for the approving teacher rather than discarding the story.

FLUX.2 [klein] 9B & Llama 4 Scout

FLUX.2 [klein] 9B draws each passage cover from a literal scene written by the labelling step, with two of four READSmart sample covers sent as style references. The pair changes with every picture, and the prompt asks for new characters and a new setting, because with a plain style request the model redrew a reference's family and room. It replaced FLUX.1 Schnell, whose text-only brief gave flatter pictures than the site's artwork; a picture now costs about $0.016 instead of $0.002. FLUX.2 takes multipart input, which AI Gateway cannot receive from the Workers binding, so the picture call goes straight to Workers AI and READSmart counts it in its own usage records. Llama 4 Scout reviews each image against the reading for child safety, faithfulness and style. A rejected image is drawn again, up to three tries within the image limits, and a teacher can ask for a new picture later. Version-linked artwork is stored privately in R2.

Cloudflare Queues & background jobs

A story request returns at once: the Worker reserves it and queues it, and the queue consumer writes, checks and saves the story in the background, recording each stage (writing, checking, saving, questions, picture). Pupils see a progress bar and, on Stories and Home, a notice when the story is ready or waiting for the teacher, even after leaving the page.

AI Gateway & review controls

Cloudflare AI Gateway provides inference observability and spending controls for the text and review calls. Application quotas and budget reservations bound every call, including the pictures that bypass the gateway, and generated readings require teacher approval before pupil access.

Trade-off

Automated review can miss factual, language, or visual errors. Matching passage metrics does not establish validated reading-level equivalence; educator review and learner validation remain necessary.

Building & checking the application

Development and release tooling

Changes are checked with component tests, browser tests, and a Cloudflare build: Workers Builds builds the main branch from GitHub and deploys it. The Python pipeline has separate checks for scoring and its API payloads.

pnpm, TypeScript & ESLint

pnpm manages the web dependencies and scripts. TypeScript checks types, and ESLint checks source-code conventions and common mistakes.

Vitest, Testing Library & Playwright

Vitest runs focused logic and component tests, with Testing Library and jsdom for rendered interfaces. Playwright exercises flows in a real browser. Python checks cover pipeline behavior and data contracts.

pipWrangler, OpenNext & uv/pip

Wrangler manages Cloudflare development and deployment operations, including D1 migrations. OpenNext builds the Worker application. uv/pip manage Python dependencies; Docker packages the RunPod runtime.

Trade-off

Passing software checks does not establish educational validity. Deployment checks and research validation answer different questions, and both need evidence.