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

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

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

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.
Never call tools in parallel — always wait for one tool call to complete before calling the next. This includes file reads, searches, and terminal commands.
Every implementation task must end with: npm run build, npm run test:cov, and npm run lint all passing. npm run test:cov enforces coverage thresholds (100% lines/functions/statements, 90% branches for packages/api and packages/shared). Do not use npm run test alone -- always use test:cov to catch coverage regressions.

All domain types and Zod schemas live in packages/shared — never duplicate types across packages.
Every data query must filter by householdId — this is the multi-tenancy boundary.
Use Server Components by default in Next.js — only add 'use client' when interactivity is needed.
Use the repository pattern in Fastify — routes → services → repositories (Awilix DI).
Use .lean().exec() on all Mongoose read queries.
No any types — use unknown and validate with Zod if the type is truly unknown.
Cursor-based pagination — never use skip() for large collections.
ESM everywhere — "type": "module", .js extensions on imports, import type for type-only imports.
Zod v4 — import from 'zod/v4', use z.enum() for enums, z.email() / z.url() as top-level.
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).