Chore Quest

A gamified household task manager — earn points, unlock achievements, and keep your streak alive.

Screenshots

Screenshots will be added soon. To see the app in action, follow the Quick Start below.

Features

• Task management with points — organize chores by category, each worth configurable points
• Streak system — maintain daily streaks to earn tier-based bonus multipliers
• Achievements — unlock badges for milestones (task counts, streaks, points, levels)
• Reward store — redeem earned points for custom rewards
• Statistics & activity feed — charts, heatmaps, leaderboard, and shared activity feed
• Calendar scheduling — assign tasks to specific weekdays with schedule overrides
• User management — admin, member, and child roles with permission-based access control
• Backup & restore — export/import full database as JSON with automatic pre-restore backup
• Push notifications — PWA notifications for task reminders with offline support
• Shared completions — complete tasks together for a teamwork bonus
• PIN-based auth — simple login with a 4-digit PIN, no email required
• Mobile-first PWA — responsive interface with install prompt and offline capability
• Self-hosted — Docker deployment with SQLite, no external database needed

Tech Stack

Technology	Purpose
Next.js 15	Full-stack React framework (App Router)
React 19	UI library
TypeScript	Type-safe JavaScript (strict mode)
Prisma + SQLite	Database ORM and storage
NextAuth.js	Authentication (credentials provider)
Tailwind CSS	Utility-first styling
shadcn/ui	Accessible UI components
Recharts	Charts and data visualization
Zod	Schema validation
OpenAPI	API documentation (generated from Zod schemas)
Vitest	Unit and integration testing
Playwright	End-to-end testing

Architecture

Frontend: Next.js App Router with a mix of Server and Client Components. UI built with Tailwind CSS and shadcn/ui. The app is a PWA with service worker for offline support, push notifications, and background sync.

API Layer: RESTful route handlers in app/api/ with role-based permission guards. All mutations validate input via Zod schemas and check authorization before touching the database. API endpoints are documented in an OpenAPI 3.1 spec, auto-generated from the Zod schemas.

Database: Prisma ORM with SQLite (via better-sqlite3 driver). 13 models covering users, tasks, completions, achievements, streaks, store items, and push subscriptions. Full backup/restore via JSON export with transactional imports.

Auth: NextAuth.js credentials provider with PIN-based login. Roles (admin/member/child) are embedded in the JWT and checked by a central permission system.

Deployment: Multi-stage Docker build published to GHCR. SQLite database persisted via volume mount. CI/CD pipeline runs tests, lints, builds, and pushes the image on every push to main.

Quick Start (Docker)

1. Create a project directory and a docker-compose.yml:

services:
  chore-quest:
    image: ghcr.io/frfrey98/chore-quest:latest
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - DATABASE_URL=file:/app/data/chore-quest.db
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
      - NEXTAUTH_URL=http://localhost:3000
    restart: unless-stopped

2. Create a .env file with a secret:

echo "NEXTAUTH_SECRET=$(openssl rand -base64 32)" > .env

3. Start the app:

docker compose up -d

4. Open http://localhost:3000 — the setup wizard will guide you through creating users and configuring the app.

Optional: Auto-updates with Watchtower

Add a Watchtower service to automatically pull new images:

  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ~/.docker/config.json:/config.json:ro
    environment:
      - WATCHTOWER_POLL_INTERVAL=300
      - WATCHTOWER_CLEANUP=true
    restart: unless-stopped

Note: If your registry requires authentication (e.g., GHCR with a private repo), make sure ~/.docker/config.json contains valid credentials.

Development Setup

git clone https://github.com/FrFrey98/chore-quest.git
cd chore-quest
npm install
cp .env.example .env
npx prisma migrate dev
npm run seed    # optional: load example data
npm run dev

Open http://localhost:3000 to see the app.

Project Structure

src/
  app/
    (app)/          # Main app pages (dashboard, tasks, store, stats, settings)
    (auth)/         # Login and setup wizard
    api/            # API routes (tasks, store, streak, achievements, backup, etc.)
  components/       # Reusable UI components
  lib/              # Core logic (auth, streak, points, achievements, permissions, backup)
  types/            # TypeScript type declarations
  middleware.ts     # Auth and setup redirect middleware
prisma/
  schema.prisma     # Database schema (13 models)
  seed.ts           # Development seed data

Configuration

All game settings (streak tiers, level thresholds, bonus multipliers) are configurable through the in-app Settings page — no config files to edit.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.