Reward - Chore & Reward Management System

A family-friendly application for managing chores, tasks, and rewards for children.

🏗️ Architecture

• Backend: Flask (Python) with TinyDB for data persistence
• Frontend: Vue 3 (TypeScript) with real-time SSE updates
• Deployment: Docker with nginx reverse proxy

🚀 Getting Started

Backend

cd backend
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
python -m flask run --host=0.0.0.0 --port=5000

Frontend

cd frontend/vue-app
npm install
npm run dev

🔧 Configuration

Environment Variables

Variable	Description	Default
ACCOUNT_DELETION_THRESHOLD_HOURS	Hours to wait before deleting marked accounts	720 (30 days)
DB_ENV	Database environment (prod or test)	prod
DATA_ENV	Data directory environment (prod or test)	prod

Account Deletion Scheduler

The application includes an automated account deletion scheduler that removes user accounts marked for deletion after a configurable threshold period.

Key Features:

• Runs every hour checking for accounts due for deletion
• Configurable threshold between 24 hours (minimum) and 720 hours (maximum)
• Automatic retry on failure (max 3 attempts)
• Restart-safe: recovers from interruptions during deletion

Deletion Process: When an account is marked for deletion, the scheduler will automatically:

1. Remove all pending rewards for the user's children
2. Remove all children belonging to the user
3. Remove all user-created tasks
4. Remove all user-created rewards
5. Remove uploaded images from database
6. Delete user's image directory from filesystem
7. Remove the user account

Configuration: Set the deletion threshold via environment variable:

export ACCOUNT_DELETION_THRESHOLD_HOURS=168  # 7 days

Monitoring:

• Logs are written to logs/account_deletion.log with rotation (10MB max, 5 backups)
• Check logs for deletion summaries and any errors

🔌 API Endpoints

Admin Endpoints

All admin endpoints require JWT authentication and admin role.

Note: Admin users must be created manually or via the provided script (backend/scripts/create_admin.py). The admin role cannot be assigned through the signup API for security reasons.

Creating an Admin User:

cd backend
python scripts/create_admin.py

Account Deletion Management

• GET /api/admin/deletion-queue - View users pending deletion
• GET /api/admin/deletion-threshold - Get current deletion threshold
• PUT /api/admin/deletion-threshold - Update deletion threshold (24-720 hours)
• POST /api/admin/deletion-queue/trigger - Manually trigger deletion scheduler

User Endpoints

• POST /api/user/mark-for-deletion - Mark current user's account for deletion
• GET /api/me - Get current user info
• POST /api/login - User login
• POST /api/logout - User logout

🧪 Testing

Backend Tests

cd backend
pytest tests/

Frontend Tests

cd frontend/vue-app
npm run test

📝 Features

• ✅ User authentication with JWT tokens
• ✅ Child profile management
• ✅ Task assignment and tracking
• ✅ Reward system
• ✅ Real-time updates via SSE
• ✅ Image upload and management
• ✅ Account deletion with grace period
• ✅ Automated cleanup scheduler

🔒 Security

• JWT tokens stored in HttpOnly, Secure, SameSite=Strict cookies
• Role-Based Access Control (RBAC): Admin endpoints protected by admin role validation
• Admin users can only be created via direct database manipulation or provided script
• Regular users cannot escalate privileges to admin
• Account deletion requires email confirmation
• Marked accounts blocked from login immediately

📁 Project Structure

.
├── backend/
│   ├── api/              # REST API endpoints
│   ├── config/           # Configuration files
│   ├── db/               # TinyDB setup
│   ├── events/           # SSE event system
│   ├── models/           # Data models
│   ├── tests/            # Backend tests
│   └── utils/            # Utilities (scheduler, etc)
├── frontend/
│   └── vue-app/
│       └── src/
│           ├── common/   # Shared utilities
│           ├── components/ # Vue components
│           └── layout/   # Layout components
└── .github/
    └── specs/            # Feature specifications

🛠️ Development

For detailed development patterns and conventions, see .github/copilot-instructions.md.

📚 References

• Reset flow (token validation, JWT invalidation, cross-tab logout sync): docs/reset-password-reference.md

📄 License

Private project - All rights reserved.