Sportfest

A multi-platform suite for running school sport festivals with cognitive and physical tests:

• web/ — SvelteKit web app: admin dashboard, public leaderboards, per-activity kiosk, and the REST API backend
• EvgymSport/ — Android tablet app for cognitive tests
• sensors/ — Go (Fyne) desktop station for physical-activity timing via RS-232 light barriers

The tablet and sensor apps talk to the web API using a Bearer API key.

Web app

All commands run from web/.

Prerequisites

• Node.js + pnpm
• A web/.env file (gitignored). Minimum:

  DATABASE_URL=file:local.db
  EMAIL_HOST=localhost
  EMAIL_PORT=587
  EMAIL_AUTH_USER=user@example.com
  EMAIL_AUTH_PASS=changeme
  COOKIE_SECRET=any-long-random-string
  

  The EMAIL_* values are required for the build to succeed (used for OTP email verification). COOKIE_SECRET signs all cookies (HS256); in dev it falls back to an insecure constant with a warning, but in production pnpm start throws if it is unset. EMAIL_FROM is optional and defaults to EMAIL_AUTH_USER (it must be an address the SMTP user is allowed to send from).

Develop

pnpm install
pnpm run db:push   # create the SQLite tables (run once / after schema changes)
pnpm run dev

If pnpm install skips native build scripts (better-sqlite3 / esbuild), run it once with pnpm install --config.dangerouslyAllowAllBuilds=true.

Production

pnpm install
pnpm run build
ORIGIN=http://your-host:3000 pnpm start   # serves the build + the leaderboard WebSocket server
# or: pnpm run preview   (preview without the WebSocket server)

pnpm start requires ORIGIN (the public origin, e.g. http://your-host:3000): CSRF origin checking is enabled, and without ORIGIN every form-action POST (login, admin, kiosk) is rejected 403 Cross-site POST form submissions are forbidden. COOKIE_SECRET must also be set (the server throws without it). CSRF is skipped in dev, so pnpm run dev needs neither.

Useful commands

pnpm test            # unit tests (vitest + @testing-library/svelte)
pnpm run check       # type-check (svelte-check)
pnpm run db:studio   # browse the database (drizzle studio)

Android app (EvgymSport/)

Build/test from EvgymSport/ with a JDK 21 (the Android Studio JBR). Set JAVA_HOME, then:

./gradlew testDebugUnitTest        # JVM unit tests
./gradlew assembleDebug            # debug APK

Release signing/versioning and tablet-fleet distribution are documented in EvgymSport/RELEASE.md.

Sensors station (sensors/)

Go (Fyne) desktop app. Build/test from sensors/:

go test -race ./internal/...       # unit tests (pure logic; serial + UI are I/O shells)
go run .                           # run the station

Documentation

• AGENTS.md — architecture, conventions, and setup notes for contributors and coding agents
• DESIGN.md — design system / brand spec
• docs/superpowers/ — design specs and implementation plans