MeshiTrack/.github/copilot-instructions.md

MeshiTrack — Copilot Instructions

This is a nutrition management application built as a TypeScript monorepo.

Project Documentation

Before writing code, always consult the relevant documentation in the docs/ directory:

• docs/PLAN.md — Project overview, tech stack, and phase roadmap
• docs/architecture.md — Architecture Decision Records (ADRs)
• docs/cross-cutting.md — API versioning, pagination, error handling, security, observability

Phase Specifications

Each phase has a detailed spec with schemas, endpoints, and business logic:

• docs/phases/phase-0-foundation.md — Monorepo setup, Docker, Keycloak, auth
• docs/phases/phase-1-product-library.md — Product CRUD, barcode lookup, LLM interface
• docs/phases/phase-2-recipes.md — Recipes, nutrition calculation, LLM import
• docs/phases/phase-3-pantry.md — Pantry tracking, freshness, notifications
• docs/phases/phase-4-meal-planning.md — Meal plans, nutrition targets, suggestion engine
• docs/phases/phase-5-grocery.md — Shopping lists, price tracking, store comparison
• docs/phases/phase-6-llm.md — LLM provider implementations, NLP parsing

Coding Instructions (MUST READ)

The docs/instructions/ directory contains best practices and conventions that must be followed:

• docs/instructions/conventions.md — Naming, formatting, linting, git conventions
• docs/instructions/fastify.md — Fastify plugin structure, Awilix DI, validation, hooks, repository pattern
• docs/instructions/nextjs.md — App Router, Server/Client Components, data fetching, forms
• docs/instructions/mongodb.md — Schema design, indexing, queries, pagination
• docs/instructions/typescript-zod.md — Type design, Zod schemas, shared package rules
• docs/instructions/turborepo.md — Monorepo workspace config, build pipelines, dependencies
• docs/instructions/docker.md — Compose services, Dockerfiles, env vars, health checks
• docs/instructions/keycloak.md — Auth integration, JWT claims, guards, token refresh
• docs/instructions/testing.md — Vitest unit/integration/E2E test patterns, coverage targets

Tool Usage Rules

• Always use read_file to read file contents — never use terminal commands like Get-Content, cat, head, or tail to read files. These will be denied.
• Always use grep_search or file_search to find files and patterns — never use Select-String, grep, find, or rg in terminal commands.
• Run scripts only via npm run <script> — never use npx, and never add flags like 2>&1, pipes (|), or Select-Object to npm run commands.
• Use execution_subagent for build/test/lint commands — it runs npm run build, npm run test, and npm run lint and returns relevant output without piping.
• Every implementation task must end with: npm run build, npm run test, and npm run lint all passing.

Key Rules

1. All domain types and Zod schemas live in packages/shared — never duplicate types across packages.
2. Every data query must filter by householdId — this is the multi-tenancy boundary.
3. Use Server Components by default in Next.js — only add 'use client' when interactivity is needed.
4. Use the repository pattern in Fastify — routes → services → repositories (Awilix DI).
5. Use .lean().exec() on all Mongoose read queries.
6. No any types — use unknown and validate with Zod if the type is truly unknown.
7. Cursor-based pagination — never use skip() for large collections.
8. ESM everywhere — "type": "module", .js extensions on imports, import type for type-only imports.
9. Zod v4 — import from 'zod/v4', use z.enum() for enums, z.email() / z.url() as top-level.
10. No .js extensions on @/ imports in packages/web — Next.js resolves TypeScript files directly; .js extensions on @/ path-alias imports break Turbopack and webpack. Only use .js extensions in packages/api and packages/shared (Node ESM).