🏠 TidyQuest

Transform household chores into an epic family adventure

TidyQuest is a self-hosted web application that gamifies housework using RPG mechanics. Complete tasks, earn coins, unlock achievements, and compete with your family on the leaderboard.

---

✨ What is TidyQuest?

TidyQuest turns boring chores into quests:

• 🎯 Health Bars: Each task has a visual health indicator that decays over time
• 💰 Coins & Rewards: Earn coins by completing tasks, redeem for family rewards
• 🔥 Streaks: Build daily/weekly streaks to stay motivated
• 🏆 Leaderboard: Compete with family members for top position
• 🎖️ Achievements: Unlock badges for milestones (100 tasks, 30-day streak, etc.)
• 📅 Calendar View: See upcoming due dates at a glance
• 🌍 Multilingual: English, French, German, Spanish
• 📱 Telegram Notifications: Optional reminders for due tasks and rewards

Perfect for families who want to:

• Make chores fun for kids
• Track household responsibilities
• Encourage teamwork with gamification
• Build consistent cleaning habits

---

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• 100MB disk space
• Port 3020 available

Installation (3 steps)

1. Clone the repository

   git clone https://github.com/mellow-fox/TidyQuest.git
   cd TidyQuest
   

2. Configure environment

   cp .env.example .env
   # Edit .env and set a secure JWT_SECRET
   # Generate one: openssl rand -base64 32
   

3. Launch with Docker

   docker compose up -d --build
   

   Access at http://localhost:3020

First Login

On first launch, the database is empty. Create an admin account via the Register page.

---

🎮 Features

For Everyone

• ✅ Complete Tasks: Mark chores as done, earn coins
• 💎 Redeem Rewards: Request rewards like "Movie Night Pick" or "Extra Game Time"
• 📊 Track Progress: See your current streak, coins, and achievements
• 🏠 Room Management: Organize tasks by room (Kitchen, Bedroom, Bathroom, etc.)

For Admins

• 👥 User Management: Create family members (admin/member/child roles)
• 📝 Task CRUD: Create, edit, delete tasks with custom frequencies (1-365 days)
• 🎁 Reward System: Approve/reject reward requests, manage catalog
• ⚙️ Global Settings: Configure coins-per-effort, Telegram notifications
• 🏖️ Vacation Mode: Pause task health decay during family vacations
• 📤 Backup/Restore: Export full database as JSON

Built-in Defaults

• 8 Room Types: Kitchen, Bedroom, Bathroom, Living Room, Office, Garage, Laundry, Garden
• 60+ Predefined Tasks: Common household chores with realistic frequencies
• 10 Preset Rewards: Movie night, ice cream, stay up late, game time, etc.
• 12 Achievements: Unlocked automatically based on activity

---

🛠️ Tech Stack

Layer	Technology
Frontend	React 19 + Vite + TypeScript
Backend	Node.js + Express + TypeScript
Database	SQLite3 (with WAL mode)
Auth	JWT + bcrypt
Deployment	Docker (single container, ~300MB)
Routing	React Router v7
Styling	Custom CSS (no framework)

Zero external dependencies for core functionality. Optional Telegram integration for notifications.

---

📂 Project Structure

TidyQuest/
├── client/           # React frontend
│   ├── src/
│   │   ├── components/  # UI components
│   │   ├── hooks/       # useAuth, useApi, useTranslation
│   │   ├── i18n/        # Translation files (EN/FR/DE/ES)
│   │   └── App.tsx
│   └── package.json
├── server/           # Express backend
│   ├── src/
│   │   ├── routes/      # API endpoints
│   │   ├── middleware/  # JWT auth
│   │   ├── utils/       # Health calculation, notifications
│   │   └── database.ts  # SQLite setup
│   └── package.json
├── data/             # Persistent storage (Docker volume)
│   ├── tidyquest.db     # SQLite database
│   └── avatars/         # User-uploaded photos
├── Dockerfile        # Multi-stage build
├── docker-compose.yml
├── .env.example      # Configuration template
├── SECURITY.md       # Security best practices
└── API.md            # API documentation

---

🔧 Configuration

Environment Variables

See .env.example for all options. Key variables:

Variable	Required	Description
JWT_SECRET	Yes (prod)	Secret for signing JWT tokens (min 32 chars)
NODE_ENV	No	production or development
PORT	No	Server port (default: 3000)

Telegram Notifications (Optional)

1. Create a Telegram bot via @BotFather
2. Get your chat ID via @userinfobot
3. Configure in app Settings page (admin only)

Notification types:

• 🕐 Daily Due Tasks: Sent at configured time (default 09:00)
• 🎁 Reward Requests: Notify admin when child requests reward
• 🎖️ Achievements: Celebrate unlocked achievements

---

📖 Usage

Creating Rooms

1. Go to Rooms page
2. Click Add Room
3. Select room type (e.g., Kitchen)
4. Choose from 60+ default tasks or create custom ones

Completing Tasks

1. Open a room
2. Click ✅ on a task row
3. Earn coins (5-25 based on effort level 1-5)
4. Health bar resets to 100%

Redeeming Rewards

1. Go to Rewards page
2. Click Redeem on a reward (coins deducted immediately)
3. Admin approves/rejects request
4. If rejected, coins are refunded

Vacation Mode

Admin can enable in Settings to pause all health decay. Useful for family trips.

---

🔒 Security

Before exposing publicly, review SECURITY.md for:

• Setting strong JWT_SECRET
• Using HTTPS reverse proxy (Caddy/Nginx)
• Database backup strategy
• Telegram token protection

⚠️ Never expose TidyQuest directly to the internet over HTTP.

---

🔄 Updating

cd TidyQuest
git pull
docker compose down
docker compose up -d --build

Your data persists in the ./data volume.

---

🗄️ Backup & Restore

Manual Backup (via UI)

Admin → Settings → Export Data → Download JSON

File System Backup

cp data/tidyquest.db backups/tidyquest-$(date +%Y%m%d).db

Restore

Admin → Settings → Import Data → Upload JSON

---

🌐 API Documentation

See API.md for full endpoint documentation with examples.

Quick overview:

• Auth: /api/auth/register, /api/auth/login
• Rooms: /api/rooms (CRUD)
• Tasks: /api/rooms/:id/tasks (CRUD + complete)
• Dashboard: /api/dashboard (aggregated view)
• Leaderboard: /api/leaderboard?period=week|month|quarter|year
• Rewards: /api/rewards (CRUD + redeem)
• Achievements: /api/achievements

All endpoints require Authorization: Bearer <token> (except auth routes).

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

What this means:

• ✅ You can use, modify, and distribute TidyQuest freely
• ✅ You can run it commercially (for your business/family)
• ⚠️ If you modify and host TidyQuest as a service (even privately), you must share your source code
• ⚠️ Any derivative work must also be licensed under AGPL-3.0

Why AGPL? To ensure TidyQuest remains free and open-source forever, preventing proprietary SaaS forks.

See the LICENSE file for full details.

---

🙏 Acknowledgments

• Inspired by RPG mechanics from classic games
• Built with love for families who want to make chores fun
• Uses Nunito font (bundled locally)

---

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🔒 Security Issues: See SECURITY.md for responsible disclosure

---

Made with ❤️ for families everywhere