A modern, full-stack quiz application built with Next.js 16, featuring OIDC authentication, real-time leaderboards, and a comprehensive REST API with API key authentication.
Complete documentation is available at: /docs or online at https://quiz-app-docs.example.com
Quick links:
- 🎯 Quiz Management — Create, edit, and delete quizzes with multiple-choice questions
- ✨ AI Generated Content — Use AI to help generate questions and answers
- 🔎 Image Browser — Browse and select images via Unsplash API integration
- 🔐 OIDC Authentication — Secure sign-in via OpenID Connect (configurable provider)
- 👑 Role-Based Access — Admin permissions based on OIDC groups claim
- 🏆 Leaderboards — Per-quiz and global leaderboards with rankings
- ⏱️ Timed Quizzes — Optional time limits with timeout tracking
- 🔄 Randomization — Shuffle questions for each attempt
- 🔑 API Keys — Programmatic access with scoped permissions and rate limiting
- 📖 OpenAPI Docs — Interactive API documentation with Scalar
- 🌓 Dark Mode — System-aware theme switching
- Monorepo: Bun workspaces + Turborepo 2.4+
- Framework: Next.js 16 (App Router, Turbopack)
- Runtime: Bun
- Database: PostgreSQL with Drizzle ORM (via
bun:sql) - Cache: Valkey/Redis (optional, via Bun native client)
- Auth: BetterAuth with OIDC + API Key plugins
- UI: shadcn/ui (Base UI - Nova), Lucide Icons
- Validation: Zod
- AI: AI SDK with multi-provider support
- Images: Unsplash API integration
The fastest way to get started is using create-respondeo-app:
# Using Bun (recommended)
bun create respondeo-app my-quiz-app
# Or with npm
npx create-respondeo-app my-quiz-app
# Or with pnpm
pnpm create respondeo-app my-quiz-appThis will:
- Download the latest template
- Install dependencies
- Set up environment files
- Show you the next steps
Then:
cd my-quiz-app
# Configure .env.local with your database and OIDC settings
bun run db:migrate # Run database migrations
bun run dev # Start development serverIf you prefer to clone the repository directly:
- Bun >= 1.3.8
- PostgreSQL database
- An OIDC provider (e.g., Keycloak, Auth0, Okta, Pocket ID)
# Clone and install
git clone <repository-url>
cd quiz-app
bun install
# Start database
docker compose up -d
# Configure environment
cp apps/web/.env.example apps/web/.env.local
# Edit apps/web/.env.local with your settings
# Run migrations
bun run db:migrate
# Start development server
bun run devOpen http://localhost:3000 in your browser.
See Installation Guide for detailed setup instructions.
Minimum required environment variables:
# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Auth
BETTER_AUTH_SECRET=your-32-character-secret
BETTER_AUTH_URL=http://localhost:3000
# OIDC Provider
OIDC_ISSUER=https://your-oidc-provider.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/quiz_appSee Configuration Guide for all available options.
bun run dev # Start development server
bun run build # Build for production
bun run start # Start production server
bun run tsc # Type checking
bun run lint # Run ESLint
bun run format # Format code
bun run db:migrate # Run database migrations
bun run db:studio # Open Drizzle Studio
bun test # Run testsSee Scripts Reference for all available commands.
quiz-app/
├── apps/
│ ├── web/ # Main Next.js application
│ └── docs/ # Fumadocs documentation site
├── docs/ # Documentation source (MDX files)
├── package.json # Workspace root
└── turbo.json # Turborepo configuration
See Architecture Guide for detailed system architecture.
Respondeo provides a comprehensive REST API. Get started:
- Create an API key at
/settings(admin only) - Include it in the
x-api-keyheader - Explore endpoints in the API Reference
Interactive API documentation available at /docs when running the app.
The app can be deployed to:
- Vercel — Easiest, with Vercel Postgres
- Docker — Use included
compose.yaml - VPS — Any server with Bun and PostgreSQL
- Railway, Fly.io — Docker-based platforms
See Deployment Guide for detailed instructions.
This repository includes a Fumadocs-powered documentation site in apps/docs/.
To run the docs locally:
bun run dev --filter=docsVisit http://localhost:3001
All documentation source files are in the /docs directory at the repository root.
MIT
- Documentation: Complete docs
- GitHub Issues: Report bugs
- Discussions: Ask questions
- Troubleshooting: Common issues
| Scope | Description |
|---|---|
quizzes:read |
List and view quizzes, view leaderboards |
quizzes:write |
Create, update, and delete quizzes (requires admin role) |
attempts:read |
View quiz attempts |
attempts:write |
Submit quiz attempts |
API keys are rate-limited to 100 requests per minute by default. When rate-limited, the API returns a 429 Too Many Requests response.
Interactive API documentation is available at /docs powered by Scalar. The documentation includes:
- 📋 Full endpoint reference with request/response schemas
- 🧪 "Try it" functionality to test endpoints directly in the browser
- 📦 Code snippets in multiple languages (JavaScript, Python, cURL, etc.)
- 🔐 Authentication setup for API key configuration
All endpoints return consistent error responses:
{
"error": "Error message describing what went wrong"
}| Status Code | Description |
|---|---|
400 |
Bad Request — Invalid input data |
401 |
Unauthorized — Missing or invalid API key |
403 |
Forbidden — Insufficient permissions |
404 |
Not Found — Resource doesn't exist |
429 |
Too Many Requests — Rate limit exceeded |
500 |
Internal Server Error — Something went wrong |
| Command | Description |
|---|---|
bun --bun run dev |
Start development server |
bun --bun run build |
Build for production |
bun --bun run start |
Start production server |
bun --bun run tsc |
TypeScript type checking |
bun --bun run lint |
Run ESLint |
bun --bun run format |
Format code with Prettier |
bun --bun run format:check |
Check code formatting with Prettier |
bun --bun run stylelint |
Run Stylelint for CSS files |
bun --bun run db:push |
Push schema changes to database |
bun --bun run db:generate |
Generate migration files |
bun --bun run db:migrate |
Run migrations |
bun --bun run db:studio |
Open Drizzle Studio |
bun test |
Run tests |
MIT
