# 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

## 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.