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.

🧩 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: Follow PEP 8 for Python, and standard TypeScript conventions. Use type annotations everywhere in Python. Place python changes after imports. Place all imports at the top of the file.

🚦 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/)
• 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.