Czytanko

A simple, ad-free web app for teaching children to read Polish — and a companion math game (Liczonko). Built for my kids, shared in case it's useful to others.

Note

This repository is archived and read-only. The project is no longer hosted or maintained, and issues/pull requests are not being accepted. The code is published here for reference and can still be run locally (see below).

Features

• Three reading levels — by sounds (głoski), by syllables (sylaby), and whole words. Higher levels use longer and rarer words.
• Custom mode — pick letter case, word length, and word frequency yourself.
• Read-aloud check — after each word, it's spoken out loud and the child marks whether they read it correctly. Daily stats keep them motivated.
• Liczonko — a basic arithmetic practice game with a number pad.
• Clean dictionary: vulgar and controversial words have been removed.

Tech stack

• Frontend — Preact + Vite + TypeScript, Pico.css, Preact Signals. (react-frontend/)
• Backend — Node + Express + Prisma over SQLite, TypeScript. (node-backend/)
• Infra — Docker, Caddy (static frontend), Traefik (routing + TLS). (infra/)
• Tests — Jest (backend) and Cypress + Cucumber (e2e in cypress-tests/).

Getting started

Backend

cd node-backend
npm install
# create a .env file (gitignored) — see variables below
npx prisma generate
npm start              # dev server with hot reload
npm test               # Jest tests

The backend expects a .env file (gitignored). Required variables:

NODE_ENV=development
PORT=8000
DATABASE_URL="file:../czytanko.test.db"
JWT_ACCESS_SECRET="<random-string>"
JWT_REFRESH_SECRET="<random-string>"
JWT_ACCESS_LIFETIME="15m"
JWT_REFRESH_LIFETIME="7d"

Frontend

cd react-frontend
npm install
npm start              # Vite dev server
npm run build          # production build to dist/

End-to-end tests

cd cypress-tests
npm install
npm test

Deployment

Production ran via Docker Compose behind Traefik (TLS) with Caddy serving the built frontend. See infra/docker-compose.yml and infra/production.yml.

License

No license specified — all rights reserved. Open an issue if you'd like to reuse it.