Skip to content

README.md

Latest commit

 

History

History
166 lines (118 loc) · 5.92 KB

README.md

File metadata and controls

166 lines (118 loc) · 5.92 KB
Raw

Respondeo

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.

📚 Documentation

Complete documentation is available at: docs.respondeo.app

Quick links:

Features

  • 🎯 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

Tech Stack

  • Monorepo: pnpm workspaces + Turborepo
  • Framework: Next.js 16 (App Router, Turbopack)
  • Runtime: Node.js (>= 20)
  • Database: PostgreSQL with Drizzle ORM (via postgres.js)
  • Cache: Valkey/Redis (optional, via ioredis)
  • Auth: BetterAuth with OIDC + API Key plugins
  • UI: shadcn/ui (Base UI - Nova), Lucide Icons
  • Validation: Zod
  • Tooling: oxlint + ESLint, oxfmt, Stylelint, Vitest
  • AI: AI SDK with multi-provider support
  • Images: Unsplash API integration

Quick Start

The fastest way to get started is create-respondeo-app:

# Using pnpm (recommended)
pnpm create respondeo-app my-quiz-app

# Or with npm
npx create-respondeo-app my-quiz-app

This downloads the latest template, installs dependencies, sets up environment files, and prints the next steps. Then:

cd my-quiz-app
# Configure .env.local with your database and OIDC settings
pnpm db:migrate    # Run database migrations
pnpm dev           # Start development server

Open http://localhost:3000.

To work on Respondeo itself rather than scaffold an app from it, see CONTRIBUTING.md.

Prerequisites

  • Node.js >= 20
  • pnpm >= 11
  • A PostgreSQL database
  • An OIDC provider (e.g. Keycloak, Auth0, Okta, Pocket ID)

Configuration

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_app

See the Configuration Guide for all available options.

API

Respondeo provides a REST API authenticated with API keys:

  1. Create an API key at /settings (admin only)
  2. Send it in the x-api-key header
  3. Explore the endpoints in the API Reference

Interactive API documentation is available at /docs when running the app, powered by Scalar — full endpoint reference, "try it" requests, and code snippets.

Scopes

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

Rate limiting

API keys are rate-limited to 100 requests per minute by default. When rate-limited, the API returns 429 Too Many Requests.

Error responses

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

Deployment

The app can be deployed to:

  • Vercel — Easiest, with a managed Postgres provider
  • Docker — Use the compose.yaml in apps/web/
  • VPS — Any server with Node.js and PostgreSQL
  • Railway, Fly.io — Docker-based platforms

See the Deployment Guide for detailed instructions.

Contributing

See CONTRIBUTING.md for the development setup, project structure, scripts, and release process.

License

MIT

Support