Matte-Magi 🎓✨

En rolig och engagerande matematikövningsapp för barn 6-10 år. Träna addition, subtraktion, multiplikation och division med tabellerna 1-9!

Funktioner

• 🔐 PIN-baserad inloggning (4 siffror)
• ➕ Fyra operationer: addition, subtraktion, multiplikation, division
• ⭐ Stjärnbelöningar för fullständiga nivåer
• 🍪 Kakor som tjänas in (1 kaka per 10 stjärnor, max 4/dag)
• 📊 Framstegsspårning per operation och tabell
• 🏆 Topplista för alla användare
• 🎨 Vacker, barnvänlig design på svenska
• 👨‍💼 Adminpanel för lärare och föräldrar

Snabbstart med Docker Compose

# Klona repot
git clone https://github.com/Puttrix/matte-magi.git
cd matte-magi

# Starta med Docker Compose
docker-compose up -d

# Öppna i webbläsaren
open http://localhost:3001

Applikationen är nu tillgänglig! Skapa ett konto genom att välja "Skapa konto" på inloggningsskärmen.

Lokal utveckling

Backend

cd backend
npm install
npm run dev  # Startar på port 3001
npm run test # Kör Node-test för auth/session/leaderboard

Frontend

npm install
npm run dev  # Startar på port 5173

För produktion kan VITE_API_URL lämnas tomt – klienten använder /api (samma origin) som standard.

Miljövariabler

Frontend (.env)

VITE_API_URL=http://localhost:3001/api

Tips: .env används bara för lokal utveckling. Docker-builden har .env exkluderad via .dockerignore, så produktion hamnar automatiskt på /api.

Backend (backend/.env)

PORT=3001
NODE_ENV=development
SESSION_SECRET=din-hemliga-nyckel-här
DB_PATH=./data/matte-magi.db
SESSION_DB=sessions.sqlite # valfritt filnamn för session store
SESSION_COOKIE_SECURE=auto # auto anpassar sig efter HTTP/HTTPS, sätt true bara för strikt HTTPS
FRONTEND_URL=http://localhost:5173
FRONTEND_URLS=http://localhost:5173 # kommaseparerad lista över tillåtna origin

Deploy med Portainer

1. I Portainer, skapa ny Stack
2. Klistra in docker-compose.yml innehållet
3. Ange miljövariabler:
   • SESSION_SECRET: Stark hemlig nyckel (generera med openssl rand -hex 32)
   • SESSION_COOKIE_SECURE: auto för att fungera både via HTTP och HTTPS (använd true endast vid strikt HTTPS)
   • FRONTEND_URL: Primär origin (t.ex. https://math.example.com)
   • FRONTEND_URLS: Lista över tillåtna origin (t.ex. https://math.example.com,http://10.82.1.14:3001)
4. Deploy!

Data sparas automatiskt i en Docker-volym och överlever omstarter.

Arkitektur

• Frontend: React + Vite + Tailwind CSS + shadcn/ui
• Backend: Node.js + Express + better-sqlite3
• Databas: SQLite (enkelfil, noll konfiguration)
• Auth: Session cookies + bcrypt för PIN-hashing
• Deployment: Docker + docker-compose

Tekniska val

• SQLite: Perfekt för självhostat bruk - ingen separat databasserver behövs
• Express: Minimal overhead, lätt att förstå och underhålla
• Session cookies: Enkel autentisering utan tokens
• bcrypt: Branschstandard för lösenords-/PIN-hashing

Databasschema

-- Användare
users (id, first_name, pin_hash, role, created_at)

-- Framsteg per tabell och operation
progress (id, user_id, operation, table_num, levels_completed, correct_count, attempt_count)

-- Belöningar
awards (id, user_id, stars_total, cookies_total, last_cookie_date, cookies_awarded_today)

-- Inlämningshistorik
submissions (id, user_id, operation, table_num, seed, correct, total, created_at)

API Endpoints

Autentisering

• POST /api/auth/register - Skapa konto
• POST /api/auth/login - Logga in
• POST /api/auth/logout - Logga ut
• GET /api/auth/me - Hämta användarprofil

Övningar

• POST /api/exercises/generate - Generera 10 problem
• POST /api/exercises/submit - Skicka in svar

Framsteg & Leaderboard

• GET /api/progress - Hämta användarens framsteg
• GET /api/leaderboard - Hämta topplista

Admin

• GET /api/admin/users - Lista alla användare (kräver admin)
• POST /api/admin/reset - Nollställ användardata (kräver admin)

Säkerhet

• PIN-koder hashas med bcrypt (cost 12)
• HTTP-only session cookies
• SameSite=Lax för CSRF-skydd
• Express-rate-limit skyddar auth-endpoints (50 försök per IP och 15 minuter, /auth/me har högre gräns)
• Parameteriserade SQL-frågor (SQLite injection-skydd)
• Admin-rättigheter kontrolleras server-side

Backup

SQLite-databasen sparas i /app/data/matte-magi.db inuti containern. För backup:

# Kopiera DB-fil från container
docker cp matte-magi:/app/data/matte-magi.db ./backup-$(date +%Y%m%d).db
docker cp matte-magi:/app/data/sessions.sqlite ./backup-$(date +%Y%m%d)-sessions.db

# Återställ från backup
docker cp ./backup-20241011.db matte-magi:/app/data/matte-magi.db
docker cp ./backup-20241011-sessions.db matte-magi:/app/data/sessions.sqlite

Felsökning

Backend startar inte

• Kontrollera att port 3001 är ledig
• Se till att data/ mappen är skrivbar

Frontend kan inte ansluta till backend

• Kontrollera VITE_API_URL i .env
• Se till att backend körs på rätt port
• Kontrollera CORS-inställningar i backend/src/server.js

Databas-fel

• SQLite-filen skapas automatiskt vid första start
• Om korrupt, ta bort backend/data/matte-magi.db och starta om

Roadmap

• Ljudeffekter för rätt/fel svar
• Animerad maskot som uppmuntrar
• Fler belöningar och badges
• Tidsbaserade utmaningar
• Föräldra-/lärarrapporter via e-post
• Multi-tenant support (flera klasser)

Bidra

Pull requests är välkomna! För större ändringar, öppna först en issue för att diskutera vad du vill ändra.

1. Fork projektet
2. Skapa en feature branch (git checkout -b feature/amazing-feature)
3. Commit dina ändringar (git commit -m 'Add amazing feature')
4. Push till branch (git push origin feature/amazing-feature)
5. Öppna en Pull Request

Licens

MIT

Support

Öppna en issue på GitHub för buggar eller feature requests.