Mattespelet – Star Cookies for Math Practice

This project is a delightful web app where kids practice math, earn stars for completing quizzes, and trade every ten stars for a well-deserved cookie. The experience is built for quick sessions, rewarding progress, and giving parents an easy way to celebrate learning victories.

Project info

URL: https://lovable.dev/projects/d8923b6b-765e-492a-a279-8451e6664d9b

How can I edit this code?

There are several ways of editing your application.

Use Lovable

Simply visit the Lovable Project and start prompting.

Changes made via Lovable will be committed automatically to this repo.

Use your preferred IDE

If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable.

The only requirement is having Node.js & npm installed - install with nvm

Follow these steps:

# Step 1: Clone the repository using the project's Git URL.
git clone <YOUR_GIT_URL>

# Step 2: Navigate to the project directory.
cd <YOUR_PROJECT_NAME>

# Step 3: Install the necessary dependencies.
npm i

# Step 4: Start the development server with auto-reloading and an instant preview.
npm run dev

Edit a file directly in GitHub

• Navigate to the desired file(s).
• Click the "Edit" button (pencil icon) at the top right of the file view.
• Make your changes and commit the changes.

Use GitHub Codespaces

• Navigate to the main page of your repository.
• Click on the "Code" button (green button) near the top right.
• Select the "Codespaces" tab.
• Click on "New codespace" to launch a new Codespace environment.
• Edit files directly within the Codespace and commit and push your changes once you're done.

Environment Variables

Two env files drive the stack:

1. App + PocketBase config (.env.production) — copy from .env.production.example. Key variables:

   • VITE_POCKETBASE_URL — base URL the frontend calls (defaults to http://localhost:8090).
   • POCKETBASE_ADMIN_EMAIL, POCKETBASE_ADMIN_PASSWORD — bootstrap credentials for the PocketBase admin UI (change these immediately in production).
   • POCKETBASE_PUBLIC_URL — externally reachable PocketBase URL used in password reset links.
   • Optional overrides: APP_PORT, IMAGE_NAME, POCKETBASE_IMAGE, POCKETBASE_PORT, POCKETBASE_VERSION, WEB_PULL_POLICY.

2. Runtime-only overrides — for SMTP or other secrets you don't want in git, inject them via your deployment platform (Portainer, GitHub Actions secrets, etc.). The Compose files expect the variables above to exist but won't break if additional PocketBase options are provided at runtime.

When running npm run dev, copy .env.production to .env.local so Vite picks up the same values. Docker Compose loads .env.production for both the web container and PocketBase service, and the GitHub Actions workflow expects the same variables as repository secrets when building in CI.

What technologies are used for this project?

This project is built with:

• Vite
• TypeScript
• React
• shadcn-ui
• Tailwind CSS

How can I deploy this project?

Option 1: Lovable publish

Open Lovable and click Share → Publish for an instant hosted preview.

Option 2: Local Docker Compose

1. Copy the environment template:

   cp .env.production.example .env.production

   Update the PocketBase admin email/password before exposing the stack to anyone else.
2. Launch the app and PocketBase locally:

   docker compose up --build

3. Visit the sites:
   • Web app: http://localhost:8080 (override via APP_PORT).
   • PocketBase admin UI: http://localhost:8090/_/ (override via POCKETBASE_PORT).
4. On first boot PocketBase will create pocketbase/pb_data/ and load any collection exports placed under pocketbase/collections/. Use the admin UI to configure SMTP or import data, then export the schema back into pocketbase/collections/ so future deployments stay in sync.
5. The compose file builds PocketBase from the official release archive (docker/pocketbase.Dockerfile). Adjust POCKETBASE_VERSION in your .env.production if you need a different release; Portainer and local Compose will rebuild automatically.

Option 3: Portainer Stack + GitHub Actions

1. Build & push via CI
   • Configure GitHub repository secrets: VITE_POCKETBASE_URL, POCKETBASE_ADMIN_EMAIL, POCKETBASE_ADMIN_PASSWORD, POCKETBASE_PUBLIC_URL, and (optionally) PORTAINER_URL, PORTAINER_STACK_ID, PORTAINER_API_KEY, IMAGE_NAME.
   • Push to main (or trigger the workflow manually) to publish the Docker image to GitHub Container Registry (ghcr.io/puttrix/star-cookie-math-78310) with both commit-SHA and latest tags.
   • Important: Run the workflow at least once before setting up Portainer so the latest image exists in GHCR.
2. Create/Update the Portainer stack (Repository mode)
   • In Portainer, choose Stacks → + Add stack → Repository and point to https://github.com/Puttrix/star-cookie-math-78310.git.
   • Set the compose path to docker-compose.portainer.yml and select the branch you want to deploy (usually main).
   • Under Environment variables, add these required entries:
     • VITE_POCKETBASE_URL — frontend's PocketBase endpoint (e.g., http://your-server:8090)
     • POCKETBASE_ADMIN_EMAIL — admin email for PocketBase
     • POCKETBASE_ADMIN_PASSWORD — admin password for PocketBase
     • POCKETBASE_PUBLIC_URL — externally reachable PocketBase URL
   • Optional overrides: APP_PORT (default 8080), POCKETBASE_PORT (default 8090), POCKETBASE_VERSION (default 0.21.5), IMAGE_NAME (if using a custom registry).
   • Deploy: Portainer will clone the repo, build PocketBase from docker/pocketbase.Dockerfile (requires internet access to GitHub releases), and pull the pre-built web image from GHCR.
   • After the stack comes up, visit http://<your-host>:8090/_/ with the admin credentials to verify PocketBase is healthy.
3. Automate redeploys (optional)
   • Store PORTAINER_URL, PORTAINER_STACK_ID, and PORTAINER_API_KEY as GitHub secrets so the workflow can trigger .../api/stacks/{id}/redeploy after each image build.
   • Portainer will pull the updated latest image and restart the stack automatically.

Build & Test

Local

• Install dependencies and produce the production bundle:

  npm ci
  npm run build

• Validate the docker compose files render correctly with your current environment overrides:

  VITE_POCKETBASE_URL=http://localhost:8090 \
  POCKETBASE_ADMIN_EMAIL=admin@example.com \
  POCKETBASE_ADMIN_PASSWORD=changeme \
  POCKETBASE_PUBLIC_URL=http://localhost:8090 \
  docker compose config > /dev/null

Continuous Integration

• .github/workflows/ci.yml runs on pushes/PRs, installing dependencies, executing npm run build, and validating docker-compose.yml. Provide dummy PocketBase values (VITE_POCKETBASE_URL, POCKETBASE_ADMIN_EMAIL, POCKETBASE_ADMIN_PASSWORD, POCKETBASE_PUBLIC_URL) via workflow env vars so the build step succeeds without external secrets.

PocketBase architecture overview

The app now runs entirely on PocketBase for auth and persistence:

• players (auth collection) stores each child profile, star totals, cookie balances, and the daily reset timestamp.
• progress captures practice stats per operation/table so we can unlock harder challenges over time.
• quiz_results logs every quiz attempt, powering leaderboards and mastery checks.
• Future enhancements (reward audit trails, parent dashboards) can add collections alongside these core records.

PocketBase runs as a single container alongside the web frontend. Data lives in pocketbase/pb_data/; back it up regularly (copy the SQLite file) and export collection definitions to pocketbase/collections/ whenever you tweak schema or rules.

Can I connect a custom domain to my Lovable project?

Yes, you can!

To connect a domain, navigate to Project > Settings > Domains and click Connect Domain.

Read more here: Setting up a custom domain