pokemon-inventory/.github/copilot-instructions.md

GitHub Copilot Coding Instructions

Language and framework

• Use Vue 3, Vite, modern JavaScript, and the latest stable ECMAScript supported by the project.
• Prefer Composition API and reusable atomic components.
• Do not introduce TypeScript unless a concrete technical justification is documented.
• Use Vue Router for routing.
• Use Pinia only for genuinely shared client state; do not create stores for every component.
• Use Node.js and Fastify for the API.
• Use Drizzle ORM for PostgreSQL access.

Frontend layering

Component → Composable → API Service → REST API

Components should focus on presentation and user interaction. Composables hold reusable UI behavior. API services encapsulate HTTP access.

Backend layering

Route → Validation → Application Service → Domain Logic → Repository → PostgreSQL

• Routes translate HTTP requests/responses.
• Schemas validate requests and responses.
• Services coordinate use cases.
• Domain logic owns business rules.
• Repositories own persistence.
• Provider adapters own external APIs.
• Workers own asynchronous jobs.

Data and financial rules

• Use integer minor units for money.
• Never use floating-point arithmetic for financial values.
• Store/calculation currency is USD unless a documented exception exists.
• Use purpose-built public and admin DTOs.
• Never serialize database models directly as public responses.

External integrations

• Pricing providers implement a common provider interface.
• Currency conversion is behind a service/provider abstraction.
• Image storage is behind a storage interface.
• Provider-specific behavior must stay inside provider adapters.

Search

Use the shared SearchService. Do not implement separate search algorithms for public and admin unless their data visibility requirements require separate query construction.

Accessibility

Target WCAG 2.2 AA:

• semantic HTML
• keyboard operation
• visible focus
• accessible forms/errors
• meaningful alt text
• no color-only meaning
• accessible dynamic content
• proper focus management for dialogs/galleries

Testing

Every meaningful feature should include appropriate unit, integration, component, E2E, and/or accessibility tests.

Do not disable tests merely to make CI pass.

Code quality

Prefer:

• clear names
• small functions
• explicit dependencies
• reusable components
• predictable error handling
• minimal coupling
• comments only where they explain non-obvious decisions

Avoid:

• duplicated business rules
• giant components
• giant service classes
• magic financial calculations
• direct database access from routes
• hidden global state