Building a Windows app with Node.js and Prisma/SQLite: what we learned

Schools rarely have a server; they have a Windows PC in an office. So ClassBan was built to run from a double click. Here are the choices and lessons.

Architecture

Backend: Node.js with Express and TypeScript. Database: SQLite through Prisma, with no database server to install. Frontend: React built with Vite and served by the backend. Packaging: pkg turns the app into a single ClassBan.exe for Node 18 on Windows.

Why SQLite

For one school the database is a file you can copy, back up and move. Three settings are turned on: journal_mode = WAL (fewer locks between reads and writes), busy_timeout = 5000 (wait up to 5 seconds instead of failing instantly with "database is locked") and synchronous = NORMAL. WAL means two extra files appear next to the database, and backups must include all three (see the backup guide).

Prisma with pkg needs care

Prisma ships a binary engine that must sit next to the exe. List needed files explicitly in the pkg assets or the app works on your machine and not at the school. My rule: test every build on a clean Windows install.

Licensing

The full ClassBan ties to a device with a license file and a machine id. That logic is deliberately absent from the demo. Security note: any licensing scheme with a fixed key or guessable algorithm inside the exe will eventually be broken; do not treat it as a hard barrier.

Lessons

Resolve file paths relative to the exe, not the working directory. Add logging from day one (we use winston). Convert Jalali dates in one place. Add the SMS queue and retries early (details). Keep secrets in environment variables.

Where it falls short

The SMS queue is in memory, restoring a backup is manual, and there is no automatic updater. Those are next, not solved.