How the system works

Shape of the system

FitForm is deliberately small: one Node.js process and one SQLite file. No container orchestration, no message queue, no separate database server. That is what makes it affordable for a school to run and possible for a student to understand end to end.

Layer	What it is
Server	Node.js 18+ with Express, kept alive by pm2
Database	SQLite via better-sqlite3, in WAL mode — synchronous calls, no connection pool
Accounts	bcrypt password hashes; a JSON Web Token in an httpOnly cookie
Pose detection	MediaPipe pose_landmarker_lite, in the browser, on the GPU
Drawing	Canvas 2D over the live video element
FitPass	QR codes generated server-side; scanning uses html5-qrcode
AI marking	Claude Messages API, called only from the server
Pages	Static HTML in public/; public readings and these pages rendered server-side

Where data flows

1. Camera → browser only. Frames are read from getUserMedia, passed to the pose model and drawn to a canvas. They are never encoded, uploaded or stored.
2. Browser → server. At the end of a session: exercise key, repetitions, seconds, score. For learning: which item, right or wrong, minutes. A heartbeat every 30 seconds marks a user as training or learning.
3. Server → Anthropic. Only when a student presses "mark with AI", and only the essay text and title. Nothing else about the student is sent.
4. RSS → server. Public feeds are polled for headlines; only title, short excerpt, source and link are stored.

Things worth knowing before you trust a number

• Rep counting is a joint-angle state machine. It is robust against shaking, but light, clothing and camera angle all affect it. Expect it to miss repetitions more often than it invents them.
• Session writes are rate-limited and near-duplicate sessions merge, so the board resists spamming, but it is not a tamper-proof audit log. It is a school leaderboard.
• Practice companions are flagged is_bot in the database, shown with 🤖 in a separate class, cannot log in, and are filtered out of every statistic including the admin dashboard.
• Quick marking of essays is deterministic and counts only measurable features. AI marking is a language model and can be confidently wrong — the interface says so on every report.

Run your own copy

The deployment guide covers a small Ubuntu VPS: Node, pm2, Nginx, a Let's Encrypt certificate, backups and updates. A school can host it on the cheapest instance available, point a domain at it and keep all data on its own server.

Deployment guide →