Lumbre

Lumbre is an open-source Spanish learning platform (Next.js + TypeScript + Drizzle + PostgreSQL) with a curriculum-first exercise engine, SM-2 SRS, XP/streak progression, and Docker support.

Why the name?

Lumbre means flame/glow. The product focus is steady mastery and momentum, not gamified noise.

Core capabilities

• 120 lessons (A1/A2)
• 2640 seeded sentences
• 10 supported exercise types
• XP + streak + SM-2 SRS progression
• Admin panel (/admin) and vocabulary browser (/vocab)
• Resilient API surface (/api/health, /api/progress, /api/streak, /api/srs/review, /api/lesson/[slug])

Local development

cp .env.example .env
npm install
npm run lint
npm run test
npm run build
npm run dev

Production-like run (with DB migrate + seed on startup)

docker compose up --build

This starts:

• lumbre-db (PostgreSQL 16)
• lumbre-app (Next.js app)

The app startup path automatically runs:

1. npm run db:migrate (with DB readiness retries)
2. npm run db:seed
3. next start

API quick checks

curl http://localhost:3000/api/health
curl -X POST http://localhost:3000/api/progress -H 'content-type: application/json' -d '{"correct":8,"total":10,"quality":4,"streak":3}'
curl -X POST http://localhost:3000/api/streak -H 'content-type: application/json' -d '{"streak":4,"lastActiveAt":"2026-03-01T00:00:00.000Z"}'

Known limits

• Current curriculum text is synthetic and not CEFR-reviewed by native teachers yet.
• Startup migrates/seeds each container boot by design (safe via conflict handling, but slower cold starts).
• No auth layer yet; admin APIs/pages are currently open in local/dev setups.

Useful scripts

npm run lint
npm run test
npm run build
npm run db:generate
npm run db:migrate
npm run db:seed
npm run seed:offline