Frontend overview
Read this when you start frontend work and need to find the right application, package or command.
frontend/ is a single pnpm workspace: applications live in frontend/apps/ and shared packages in frontend/packages/.
| Application | Purpose | Stack | Design system |
|---|---|---|---|
| webv2 | Main site: logs, contests, leaderboards, profiles, blog and CMS pages | Next.js 13 | ui (legacy) |
| webv3 | Unpublished homepage foundation with read-only development data and a local immersion goal | TanStack Start, Router, Query and Form | paper-ui (Paper) |
| authv2 | Account app: login, registration, recovery and Settings | TanStack Start, Router, Query and Form | paper-ui (Paper) |
| admin | Administration: CMS content, users, languages, feature access | Next.js 13 | ui (legacy) |
| paper-styleguide | Catalogue for paper-ui | Vite, React Router | paper-ui (Paper) |
| paper-playground | Unpublished Paper application study with sample data | Vite, React Router | paper-ui (Paper) |
| styleguide | Reference for the ui components | Next.js 13 | ui (legacy) |
frontend/packages/uiis the legacy design system: React components, Tailwind configuration and global CSS. The Next.js apps compile it from source throughtranspilePackages.frontend/packages/paper-uiis the Paper design system: framework-neutral controls, typed design tokens and the Tailwind CSS theme generated from them, icons, an ESLint plugin and the catalogue registry. Paper styling explains how Paper code is styled. Consumers import the tsup build indist/, which each Paper app'spredevscript rebuilds.
frontend/paper-boundaries.json marks each application as legacy or paper. pnpm check:paper-boundaries rejects paper-ui in legacy applications, and rejects ui, Next.js and Headless UI in Paper code.
Commands
Always use pnpm, never npm. From frontend/:
pnpm install --frozen-lockfile
pnpm webv2 # also webv3, authv2, admin, styleguide, paper-styleguide, paper-playground
pnpm --filter <app> lint
pnpm --filter <app> test # when the app defines it
pnpm build # runs build in every workspace package that defines it
pnpm check:paper-boundaries
The Next.js apps have no typecheck script, so use pnpm --filter <app> exec tsc --noEmit. The Paper apps have pnpm --filter <app> typecheck. Each application page lists its own commands.
To run webv2, webv3, authv2 or admin against the shared development backend, use dev-cli as described in Development environment.
Conventions
Legacy apps build on ui components and forms use react-hook-form; the rules are in Frontend conventions. Paper apps use paper-ui and follow Paper composition.