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 (backend/models/) and TypeScript interfaces (frontend/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 backend/events/).
• Changes: Do not use comments to replace code. All changes must be reflected in both backend and frontend files as needed.
• Specs: If specs have a checklist, all items must be completed and marked done.

🧩 Key Patterns & Conventions

• Frontend Styling: Use only :root CSS variables from colors.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.
• API Error Handling: Backend returns JSON with error and code (see backend/api/error_codes.py). Frontend extracts { msg, code } using parseErrorResponse(res) from api.ts.
• JWT Auth: Tokens are stored in HttpOnly, Secure, SameSite=Strict cookies.
• Code Style:
  1. Follow PEP 8 for Python, and standard TypeScript conventions.
  2. Use type annotations everywhere in Python.
  3. Place python changes after imports. Place all imports at the top of the file.
  4. Vue files should specifically place <template>, <script>, then <style> in that order. Make sure to put ts code in <script> only.

🚦 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 frontend/vue-app/src/common/backendEvents.ts and components/BackendEventsListener.vue.
• Layout Hierarchy: Use ParentLayout for admin/management, ChildLayout for dashboard/focus views.

⚖️ Business Logic & Safeguards

• 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 the backend/ directory. Main entry: backend/main.py.
• Virtual Env: Python is running from a virtual environment located at backend/.venv/.
• Frontend: From frontend/vue-app/, run npm install then npm run dev.
• Tests: Run backend tests with pytest in backend/tests/. Frontend component tests: npm run test in frontend/vue-app/components/__tests__/.
• 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

• backend/api/ — Flask API endpoints (one file per entity)
• backend/models/ — Python dataclasses (business logic, serialization)
• backend/db/ — TinyDB setup and helpers
• backend/events/ — SSE event types, broadcaster, payloads
• frontend/vue-app/ — Vue 3 frontend (see src/common/, src/components/, src/layout/) - Where tests are run from
• frontend/vue-app/src/common/models.ts — TypeScript interfaces (mirror Python models)
• frontend/vue-app/src/common/api.ts — API helpers, error parsing, validation
• frontend/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.