🔑 Getting Started & Role Accounts
QR Chores uses secure email and password authentication with role-based permissions tailored for families.
| Role |
Who |
Permissions & Actions |
| Parent |
Mom and Dad (Separate accounts) |
Create/edit/delete chores, print QR code stickers, configure timing bonuses & achievements, review today board and photo completion history. |
| Child |
Daughter |
View scheduled chores on home board, scan QR code stickers to confirm completions, upload proof photos, earn points, and unlock achievements. |
💡
Logging In: Parents land directly on the live Today Board, while the child lands on her personalized Home Screen showing daily tasks and point streaks. Use the Log out button in the top navigation bar when sharing a phone.
👨👩👧 Parent Guide
1. Today Board Statuses
The Today Board provides a real-time snapshot of scheduled chores for the current local calendar day:
- Pending: Chore is scheduled for today but has not yet been completed.
- Done: Completed on-time or early.
- Late: Past due time + grace period (or completed after the grace period expired).
2. Creating and Managing Chores
Navigate to Chores → Add Chore to configure new household tasks:
| Field |
Description |
| Title & Description |
Clear task description (e.g. "Clean Kitchen Counter", "Feed Dog"). |
| Due Time |
Local wall-clock time in your family's timezone (e.g. 6:00 PM). |
| Schedule Days |
Which days of the week this chore repeats (e.g. Mon, Wed, Fri or Daily). |
| Base Points |
Base point reward awarded once per day upon completion. |
| Photo Policy |
Set to Required, Optional, or None. |
📌
Deactivate vs. Delete:
• Deactivate: Pauses the chore from appearing on today's list while keeping historical records.
• Delete: Permanently removes the chore, all completion logs, and associated proof photos from the system.
3. Configuring Rewards & Achievements
Under Rewards, parents control point multipliers and custom achievement badges:
- Timing Bonuses: Set extra points for completing chores Early, On-Time, or Late. These stack directly on top of base chore points.
- Achievement Criteria: Create badges triggered by 7-day streaks, total completions, photo uploads, or on-time milestones.
👧 Child Guide
Home & Daily List
When logged in as a child, your home screen shows your current point balance, active streaks, unlocked badges, and today's scheduled chores.
Completing a Chore
1
Scan QR Sticker: Scan the QR code sticker placed near the chore (or tap the chore card on Home).
2
Check Photo Rules: If a photo is required, tap to snap or upload proof from your phone camera.
3
Tap "I Did It!": Instantly trigger the celebration animation, collect your points, and check for new achievement badges!
🎉
Double Completion Rule: Each chore can only be completed once per calendar day. Scanning a second time will display an "Already Done" confirmation with your earlier completion timestamp.
⏱️ Timing Windows: Early, On-Time, & Late
Timing status is calculated based on the chore's due time and your family's local timezone settings.
| Status |
Default Time Window |
Example (Chore Due at 6:00 PM) |
| Early |
More than 60 minutes before due time |
Completed before 5:00 PM |
| On Time |
From 60 mins before due through due time + 15 min grace period |
Completed between 5:00 PM and 6:15 PM |
| Late |
After due time + 15 minutes grace period |
Completed after 6:15 PM (Same calendar day) |
*Note: Completing a chore late on the same day is still allowed and awards the base chore points plus any parent-configured late bonus!
📸 Photos & Security Protocol
QR Chores implements strict file inspection and secure streaming to keep your household photos safe:
- Magic-Byte Verification: All uploaded photos are inspected at the binary header level to confirm valid JPEG, PNG, or WebP formats.
- Encrypted Off-DB Storage: Image bytes live outside the database in local disk storage (dev) or Cloud Storage (prod). The database only stores reference keys.
- Authenticated Access Only: Proof photos can only be streamed via authenticated endpoints (
/photos/...) by logged-in family members. Public direct access is blocked.
🏆 Server-Side Points Ledger System
Point balances in QR Chores are stored in an append-only PointLedger table on the server. Point balances cannot be altered or spoofed by client requests.
| Point Source |
Calculation Rule |
| Chore Base Points |
Awarded once per day when chore is completed. |
| Timing Bonus |
Extra points added for Early, On-Time, or Late completion as defined in Parent Rewards. |
| Achievement Reward |
Bonus points credited instantly when milestone achievements unlock. |
📌 Permanent QR Stickers Printing Guide
One of QR Chores' core design highlights is permanent sticker codes:
🖨️
Sticker Printing Best Practices:
1. In the Parent menu, click Print Sticker Sheet.
2. Print on standard Avery or sticker label paper.
3. Affix stickers directly to physical chore locations (e.g. Dishwasher, Dog Food Bin, Trash Can, Desk).
4. Crucial invariant: Keep your public application domain (BASE_URL) stable after printing so printed stickers remain valid indefinitely.
🔧 Troubleshooting & FAQ
| Issue / Symptom |
Recommended Resolution |
| QR code opens wrong page or fails |
Verify that your application's BASE_URL environment setting matches your current web domain. Re-print sticker sheet if server address was modified. |
| "Wrong Account" error upon scanning |
Ensure the phone is logged in as the Child role before scanning the sticker code. |
| Cannot complete chore without photo |
Check if the parent set the chore's photo policy to Required. Ensure camera permissions are enabled for your mobile browser. |
| "Already Completed Today" message |
Each chore can only be completed once per calendar day. Check the history tab for earlier completion logs. |
| Logged out unexpectedly |
QR Chores uses HTTP-only secure cookie sessions. If the server secret key changes, users must re-authenticate. |
