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
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`
`USE_MONGODB`	Use MongoDB (`true`/`false`)	`true`
`MONGO_URI`	MongoDB connection URI (required when `USE_MONGODB=true`)	—
`MONGO_DB_NAME`	MongoDB database name (optional)	Parsed from `MONGO_URI`, or `chore_db`/`chore_db_test`/`chore_db_e2e` based on `DB_ENV`

Database Backend

The application supports two persistence backends:

MongoDB (default): Set MONGO_URI (and optionally MONGO_DB_NAME). This is the recommended backend for production and managed hosting (e.g., MongoDB Atlas).
TinyDB: JSON-file storage in backend/data/db/ (or backend/test_data/db/ for test/e2e). Opt in by setting USE_MONGODB=false.

Migrating from TinyDB to MongoDB

cd backend
# Dry run to preview what will be migrated
python -m scripts.migrate_to_mongodb --dry-run

# Run the migration (backs up TinyDB files first)
python -m scripts.migrate_to_mongodb

The migration script reads the existing TinyDB JSON files and inserts each record into the matching MongoDB collection, skipping records that already exist. Original TinyDB files are backed up to backend/data/db/backups/<timestamp>/.

Rolling Back to TinyDB

Set USE_MONGODB=false. The original JSON files remain in place.

Gunicorn / Docker

When running multiple Gunicorn workers, each worker must create its own MongoDB client after forking. This is handled automatically by backend/gunicorn.conf.py, which is loaded by backend/Dockerfile via -c gunicorn.conf.py.

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:

Remove all pending rewards for the user's children
Remove all children belonging to the user
Remove all user-created tasks
Remove all user-created rewards
Remove uploaded images from database
Delete user's image directory from filesystem
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
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 / MongoDB persistence layer
│   ├── events/           # SSE event system
│   ├── models/           # Data models
│   ├── tests/            # Backend tests
│   └── utils/            # Utilities (scheduler, etc)
├── frontend/
│   └── 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

README.md

Reward - Chore & Reward Management System

🏗️ Architecture

🚀 Getting Started

Backend