Architecture

Overview

Quiz Builder is a pnpm monorepo with Cloudflare-first deployment. Creators authenticate with Better Auth, manage quizzes from the web dashboard, and publish shareable links. Anonymous visitors complete published quizzes at /q/{permalink} with server-side scoring.

apps/
  api/         Hono Workers API (OpenAPI + Scalar + quiz routes)
  web/         React + Vite frontend (auth, creator UI, public take)
  docs/        Astro Starlight documentation (this site)
  storybook/   UI catalog + web feature stories with MSW
  e2e/         Playwright smoke and journey tests

packages/
  config/      Shared TypeScript presets
  types/       Shared Zod schemas and DTOs
  api-client/  Orval-generated hooks, MSW, and Faker
  ui/          shadcn/ui components and global styles

Apps

`apps/web`

React 19 + Vite + TanStack Router + Tailwind v4. Imports shared UI from @quiz-builder/ui and API hooks from @quiz-builder/api-client.

Routes:

Path	Purpose
`/`	Marketing home
`/login`, `/register`	Better Auth email/password
`/dashboard`	Authenticated quiz list + session
`/quizzes/$quizId`	Draft editor or published read-only view
`/q/$permalink`	Anonymous quiz taking + score

Deploy target: Cloudflare Pages.

`apps/api`

Hono on Cloudflare Workers with @hono/zod-openapi for route validation and OpenAPI generation. Interactive docs via Scalar at /scalar; raw spec at /doc.

Auth: Better Auth with email/password at /api/auth/*. Database: Drizzle ORM on Cloudflare D1 (SQLite). See Authentication.

`apps/storybook`

Storybook 10 for @quiz-builder/ui components. Deploy target: Cloudflare Pages.

`apps/docs`

Astro Starlight site (you are here). Deploy target: Cloudflare Pages.

Shared packages

Package	Role
`@quiz-builder/config`	`tsconfig` presets (`base`, `react`, `node`)
`@quiz-builder/types`	Zod schemas with `.openapi()` metadata
`@quiz-builder/api-client`	Orval TanStack Query hooks, MSW handlers, Faker
`@quiz-builder/ui`	shadcn/ui primitives, `globals.css`, `cn()` helper

shadcn/ui monorepo pattern

Components use Base UI primitives (@base-ui/react) with the base-nova style. Install or update components via the shadcn CLI from apps/web:

cd apps/web
pnpm dlx shadcn@latest add <component> -o -y

components.json in apps/web and packages/ui controls style and output paths. Apps import primitives through workspace package exports.

Installed primitives include: Button, Input, Label, Textarea, Checkbox, Radio Group, Select, Switch, Form, Card, Separator, Tabs, Dialog, Sheet, Alert, Dropdown Menu, Tooltip, Badge, Skeleton, Sonner, and Table.

Out of scope (for now)

Email verification, password-reset email, and outbound mail delivery are intentionally deferred — see Authentication. Production deploy jobs remain disabled in GitLab CI until Cloudflare credentials are configured.