# 🏠 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
---
## 📸 Screenshots
Click to view screenshots
### Dashboard
*Main dashboard showing task overview, streaks, and quick stats*
### Rooms & Tasks
*Room view with task health bars and completion tracking*
### Leaderboard
*Family competition with weekly/monthly rankings*
### Rewards
*Reward catalog and redemption system*
### Achievements
*Unlock badges for completing milestones*
---
## 🚀 Quick Start
### Prerequisites
- Docker & Docker Compose
- 100MB disk space
- Port 3020 available
### Installation
**Choose your deployment method:**
#### Option A: Docker Hub Image (Recommended)
Fastest way to get started using pre-built multi-platform image:
1. **Create project directory**
```bash
mkdir tidyquest && cd tidyquest
```
2. **Create docker-compose.yml**
```yaml
services:
tidyquest:
image: mellowfox/tidyquest:latest
container_name: tidyquest
ports:
- "3020:3000"
environment:
- NODE_ENV=production
- JWT_SECRET=CHANGE_THIS_TO_SECURE_RANDOM_STRING_MIN_32_CHARS
volumes:
- ./data:/app/data
restart: unless-stopped
```
3. **Generate secure JWT_SECRET**
```bash
openssl rand -base64 32
# Copy output and replace JWT_SECRET in docker-compose.yml
```
4. **Launch**
```bash
docker compose up -d
```
Access at **http://localhost:3020**
#### Option B: Build from Source
For development or customization:
1. **Clone the repository**
```bash
git clone https://github.com/mellow-fox/TidyQuest.git
cd TidyQuest
```
2. **Configure environment**
```bash
cp .env.example .env
# Edit .env and set a secure JWT_SECRET
# Generate one: openssl rand -base64 32
```
3. **Build and launch**
```bash
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](https://t.me/botfather)
2. Get your chat ID via [@userinfobot](https://t.me/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
### Using Docker Hub Image
```bash
docker compose pull
docker compose up -d
```
### Using Source Build
```bash
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
```bash
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 ` (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](https://fonts.google.com/specimen/Nunito) font (bundled locally)
---
## 📞 Support
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/mellow-fox/TidyQuest/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/mellow-fox/TidyQuest/discussions)
- 🔒 **Security Issues**: See `SECURITY.md` for responsible disclosure
---
Made with ❤️ for families everywhere