chore/.github/copilot-instructions.md

Reward Project: AI Coding Agent Instructions

🏗️ Architecture & Data Flow

• Stack: Flask (Python, backend) + Vue 3 (TypeScript, frontend) + TinyDB (JSON, thread-safe, see db/).
• API: RESTful endpoints in api/, grouped by entity (child, reward, task, user, image, etc). Each API file maps to a business domain.
• Models: Maintain strict 1:1 mapping between Python @dataclasses (models/) and TypeScript interfaces (web/vue-app/src/common/models.ts).
• Database: Use TinyDB with from_dict()/to_dict() for serialization. All logic should operate on model instances, not raw dicts.
• Events: Real-time updates via Server-Sent Events (SSE). Every mutation (add/edit/delete/trigger) must call send_event_for_current_user (see events/).
• Changes: Do not use comments to replace code. All changes must be reflected in both backend and frontend files as needed.

🧩 Key Patterns & Conventions

• Frontend Styling: Use only :root CSS variables from global.css for all colors, spacing, and tokens. Example: --btn-primary, --list-item-bg-good.
• Scoped Styles: All .vue files must use <style scoped>. Reference global variables for theme consistency.
• Rewards UI: If points >= cost, apply --item-card-ready-shadow and --item-card-ready-border.
• API Error Handling: Backend returns JSON with error and code (see api/error_codes.py). Frontend extracts { msg, code } using parseErrorResponse(res) from api.ts.
• Validation: Use isEmailValid and isPasswordStrong (min 8 chars, 1 letter, 1 number) from api.ts for all user input. Use sanitize_email() for directory names and unique IDs.
• JWT Auth: Tokens are stored in HttpOnly, Secure, SameSite=Strict cookies.

🚦 Frontend Logic & Event Bus

• SSE Event Management: Register listeners in onMounted, clean up in onUnmounted. Listen for events like child_task_triggered, child_reward_request, task_modified, etc. See web/vue-app/src/common/backendEvents.ts and components/BackendEventsListener.vue.
• UI Guardrails:
  • Before triggering a task, check for pending rewards. If found, prompt for cancellation before proceeding.
  • On EDIT, always refetch the full object from the API to ensure state integrity.
• Layout Hierarchy: Use ParentLayout for admin/management, ChildLayout for dashboard/focus views.

⚖️ Business Logic & Safeguards

• Points: Always enforce child.points = max(child.points, 0) after any mutation.
• Token Expiry: Verification tokens expire in 4 hours; password reset tokens in 10 minutes.
• Image Assets: Models use image_id for storage; frontend resolves to image_url for rendering.

🛠️ Developer Workflows

• Backend: Run Flask with python -m flask run --host=0.0.0.0 --port=5000 from project root. Main entry: main.py.
• Frontend: From web/vue-app/, run npm install then npm run dev.
• Tests: Run backend tests with pytest tests/. Frontend tests: npm run test in web/vue-app/.
• Debugging: Use VS Code launch configs or run Flask/Vue dev servers directly. For SSE, use browser dev tools to inspect event streams.

📁 Key Files & Directories

• api/ — Flask API endpoints (one file per entity)
• models/ — Python dataclasses (business logic, serialization)
• db/ — TinyDB setup and helpers
• events/ — SSE event types, broadcaster, payloads
• web/vue-app/ — Vue 3 frontend (see src/common/, src/components/, src/layout/)
• web/vue-app/src/common/models.ts — TypeScript interfaces (mirror Python models)
• web/vue-app/src/common/api.ts — API helpers, error parsing, validation
• web/vue-app/src/common/backendEvents.ts — SSE event types and handlers

🧠 Integration & Cross-Component Patterns

• Every backend mutation must trigger an SSE event for the current user.
• Frontend state is event-driven: always listen for and react to SSE events for real-time updates.
• Model changes require updating both Python and TypeScript definitions to maintain parity.

---

For any unclear or missing conventions, review the referenced files or ask for clarification. Keep this document concise and actionable for AI agents.