# Reward - Chore & Reward Management System

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

## 🏗️ Architecture

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

## 🚀 Getting Started

### Backend

```bash
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

```bash
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

```bash
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:

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:

```bash
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:**

```bash
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

```bash
cd backend
pytest tests/
```

### Frontend Tests

```bash
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`](.github/copilot-instructions.md).

## 📚 References

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

## 📄 License

Private project - All rights reserved.