Refactor code structure for improved readability and maintainability

.github/specs/plan-achievements.md

@@ -0,0 +1,70 @@
+## Plan: Achievements Feature Design
+
+Published to Gitea wiki page: Achievements
+
+Design an achievements system that starts with low-risk, high-fun rules using existing tracking data, then expands to streak and behavior achievements. This approach gives fast player-visible value without major schema risk, while leaving room for deeper gamification.
+Status: Approved by user for implementation kickoff.
+
+**Steps**
+
+1. Phase 1: Define achievement taxonomy and product goals
+2. Define families: points progression, consistency/streaks, reward habits, task diversity, check-in/engagement, social/funny outcomes.
+3. Define unlock semantics: one-time unlocks vs repeatable milestones, per-child scope, optional parent aggregate view. Depends on step 2.
+4. Define badge rarity tiers (common, rare, epic, legendary) and naming/tone guide so achievements feel playful, not punitive.
+5. Phase 2: MVP achievement set (no new raw telemetry)
+6. Use existing TrackingEvent and PendingConfirmation signals to launch 20-30 achievements immediately. Depends on phase 1.
+7. Include serious progression set: first points earned, 100/500/1000 lifetime points, best day records, no-miss week, kindness count milestones.
+8. Include funny set: zero points 7 days, last-minute legend (frequent late confirmations), window shopper (many reward requests without redemption), tiny spender (chooses low-cost rewards repeatedly).
+9. Include non-point set: reward loyalty (same reward redeemed N times), variety collector (N distinct chores completed), daily checker (opened/triggered chores on N consecutive days), comeback kid (returns after inactivity).
+10. Phase 3: Data model and evaluation architecture
+11. Add achievement definition catalog (static or DB-backed) and child achievement progress/unlock records. Depends on phase 2.
+12. Evaluate on mutation events (tracking event creation, chore confirmation, reward request/redeem), with idempotent unlock logic and timezone-aware daily boundaries.
+13. Emit achievement unlocked SSE events for real-time UI celebration and maintain API for achievement list/progress.
+14. Phase 4: UX and rollout
+15. Parent view: child achievement timeline, rarity filters, and progress-to-next badge.
+16. Child view: badge cabinet, streak flame, and lightweight celebration effects.
+17. Roll out behind feature flag, start with read-only earned badges, then add near-miss/progress indicators. Depends on phase 3.
+18. Phase 5: Validation and balancing
+19. Add unit tests for each rule family and timezone edge cases.
+20. Add end-to-end tests for unlock notifications and badge rendering.
+21. Run a balancing pass using anonymized historical events to ensure unlock pacing feels rewarding (not too sparse, not too noisy).
+22. Documentation deliverable: publish the final approved achievements plan to a new Gitea wiki page for the chore project as part of implementation handoff.
+
+**Relevant files**
+
+- /Users/ryan/Projects/chore/backend/models/tracking_event.py - existing event ledger for points/actions and occurred_at timestamps.
+- /Users/ryan/Projects/chore/backend/models/pending_confirmation.py - reward/chore confirmation states useful for request/approval achievements.
+- /Users/ryan/Projects/chore/backend/db/tracking.py - insertion/query leverage point for achievement evaluation trigger.
+- /Users/ryan/Projects/chore/backend/events/types/event_types.py - event taxonomy to extend with achievement unlock notifications.
+- /Users/ryan/Projects/chore/backend/api/child_api.py - existing child-facing data APIs to mirror for achievement endpoints.
+- /Users/ryan/Projects/chore/frontend/vue-app/src/common/models.ts - add Achievement interfaces (backend parity).
+- /Users/ryan/Projects/chore/frontend/vue-app/src/common/backendEvents.ts - frontend SSE subscriptions for unlock celebrations.
+- /Users/ryan/Projects/chore/frontend/vue-app/src/common/api.ts - API helpers for listing achievements and progress.
+
+**Verification**
+
+1. Rule correctness: seed deterministic tracking histories and verify each achievement unlock threshold exactly once.
+2. Timezone correctness: validate day/week achievements for users in at least three timezones and around midnight boundaries.
+3. Idempotency: replay the same event stream and verify no duplicate unlocks.
+4. UX behavior: confirm unlocked badges appear in parent and child views without manual refresh via SSE.
+5. Regression safety: run backend pytest suite and focused Playwright specs for parent/child dashboards.
+
+**Decisions**
+
+- Included in MVP: achievements derivable from existing signals (tracking events, pending confirmations, child points, reward history).
+- Data schema decision for wave 1: no new fields required on task/chore/reward models (no complexity/category requirement for initial launch).
+- Deliberately excluded from MVP: complex streak rules requiring schedule reinterpretation across every task mode; these are phase 2+ enhancements.
+- Scope model: per-child achievements first, optional parent-level achievements later.
+- Tone model: include playful/funny achievements but avoid shaming language; treat low-performance badges as light easter eggs.
+
+**Further Considerations**
+
+1. Modularity architecture recommendation: isolate all achievement logic into an Achievement Engine module with a rule interface (evaluate(event, context) -> unlocks) and a central registry so no existing chore/reward/business logic needs branching changes.
+2. Toggle recommendation: add a global feature flag plus optional per-user flag; when disabled, route through a no-op evaluator and suppress achievement APIs/SSE/UI sections without impacting core chore/reward flows.
+3. Editability recommendation: store initial achievement definitions in a versioned JSON or YAML catalog with schema validation at startup, stable ids, enabled flag, and threshold params so add/remove/edit is config-only for most rules.
+4. Progress UX recommendation: show top 3 near-unlock achievements to increase motivation without overwhelming the child dashboard.
+5. Seasonal/event achievements recommendation: add limited-time badges after baseline system proves stable.
+6. UI isolation recommendation: keep achievement state in a dedicated frontend store/module and render via isolated components; chore/reward screens should only publish domain events and never compute achievement rules directly.
+7. UI kill-switch behavior: when feature flag is off, hide achievement routes/cards/listeners behind one composition helper so no scattered conditional logic across pages.
+8. Backfill and migration recommendation: run one-time historical recompute job to award existing users fairly; mark job version so reruns are idempotent.
+9. Observability recommendation: emit achievement engine metrics (rules evaluated, unlock count, rule errors, evaluation latency) and add dead-letter logging for malformed catalog entries.

.vscode/mcp.json

@@ -9,7 +9,20 @@
         "--config=playwright.config.ts"
       ],
       "cwd": "frontend"
+    },
+    "gitea": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITEA_ACCESS_TOKEN=${env:GITEA_ACCESS_TOKEN}",
+        "-e",
+        "GITEA_HOST=https://git.ryankegel.com",
+        "docker.gitea.com/gitea-mcp-server"
+      ],
+      "type": "stdio"
     }
-  },
-  "inputs": []
+  }
 }