Katalume frontend

Practice machine learning into mastery.

Katalume is the training ground for machine learning — solve real ML problems in an in-browser judge, compete in contests, and climb to mastery. LeetCode rigor meets Kaggle depth.

The name combines kata, deliberate practice that forges mastery, with lume, light or illumination—the moment a hard problem clicks.

Built with Next.js 16 (App Router) and React 19.

Stack

• Next.js 16 (App Router) + React 19, TypeScript
• Tailwind CSS v4, next-themes (light/dark)
• Monaco editor (@monaco-editor/react) for the solve arena
• Sentry for error tracking + tracing
• Vitest + Testing Library (unit), Playwright (e2e)

Getting started

Requirements: Node 24.

npm install
cp .env.example .env.local     # then fill in as needed
npm run dev                    # http://localhost:3000

Out of the box the app runs in mock mode (see below), so it works fully with no backend running.

Environment

See .env.example for all variables. Key ones:

Variable	Purpose
NEXT_PUBLIC_API_MODE	mock (in-file data, default), live (real backend), or auto
BACKEND_API_URL	Server-only private backend base URL used by the same-origin BFF
NEXT_PUBLIC_SITE_URL	Canonical public HTTPS origin
NEXT_PUBLIC_API_FALLBACK_TO_MOCK	In live mode, fall back to mock on API error. Set false in production so failures surface
NEXT_PUBLIC_SENTRY_DSN / SENTRY_DSN	Sentry client / server DSNs (capture is off unless set)

Mock vs live: every data call goes through a switch in src/lib/api.ts. In mock mode it returns bundled sample data so the UI is fully usable offline. In live/auto mode it calls the same-origin /api BFF with Secure/HttpOnly cookies and, unless NEXT_PUBLIC_API_FALLBACK_TO_MOCK=false, falls back to mock data on error.

Scripts

Script	What it does
npm run dev	Dev server
npm run build	Production build
npm run start	Serve the production build
npm run lint	ESLint
npm run typecheck	tsc --noEmit
npm run test:unit	Vitest unit tests
npm run test:e2e	Playwright end-to-end tests

Project structure

src/
  app/                 App Router routes (dashboard, problems, arena, profile, ...)
    api/[...path]/      same-origin private-backend BFF
    problems/[slug]/   the solve "arena" (Monaco editor, run/submit, history)
    components/        shared UI (Navbar, Sidebar, ThemeSwitcher, ...)
  lib/api.ts           data layer with the mock/live switch
  context/AuthContext  auth state
  proxy.ts             route gating through backend Session validation

Testing

npm run test:unit      # Vitest
npm run test:e2e       # Playwright (installs browsers on first run)

CI (.github/workflows/ci.yml) runs lint, typecheck, unit tests, and build, then e2e against a production build.

Deploy

Optimized for Vercel. Set the production env vars (NEXT_PUBLIC_API_MODE=live, BACKEND_API_URL, NEXT_PUBLIC_SITE_URL, mock fallback disabled, and Sentry DSNs) in the project settings before deploying.