# AGENTS.md

## Purpose

This file is a quick handover for future agents working on `D:\www\Nutrio`.
It describes what the project is, what is already implemented, and what still needs work.

## Project Summary

- Project name: `Nutrio`
- Goal: meal planning + nutrition tracking + daily diary totals.
- Backend: PHP (`tpsoft/apilite`, `tpsoft/dbmodel`)
- Frontend: Vue 3 + Vite + TypeScript
- Monorepo layout:
  - `backend/`
  - `frontend/`

## Current State (as of 2026-02-11)

- `README.md` already contains product specification in Slovak and English.
- Backend DB migrations exist in `backend/src/Maintenance.php` up to version `7`.
- Backend API routes are not implemented yet:
  - `backend/src/API.php` extends `APIlite` but has no endpoints.
- Frontend is still template-level:
  - `frontend/src/App.vue` has placeholder content.
  - `frontend/src/router/index.ts` has empty `routes: []`.
- `backend/data.json` contains sample meal data (not currently wired into DB/API flow).

## Backend Architecture

- Entry point: `backend/public/API.php`
- Bootstrap and DB init: `backend/src/Init.php`
- Configuration: `backend/config/Configuration.php`
  - Supports `mysql` and `sqlite`
  - Loads override config files from `backend/config/*.php` (except the base file itself)
- Migration logic: `backend/src/Maintenance.php`

## Database Schema Snapshot

Migration creates these tables:

- `options` (`key`, `value`) for internal settings, including DB version.
- `users` (`user_id`, `email`, `password_hash`, `created_at`).
- `ingredients`:
  - `ingredient_id`, `user_id`, `name`
  - per-100g values: `protein_g_100`, `carbs_g_100`, `sugar_g_100`, `fat_g_100`, `fiber_g_100`, `kcal_100`
- `meals`:
  - `meal_id`, `user_id`, `name`, `meal_type` (`breakfast|lunch|dinner`)
- `meal_items`:
  - `meal_item_id`, `meal_id`, `ingredient_id`, `grams`, `position`
- `diary_days`:
  - `diary_day_id`, `user_id`, `day_date`
  - unique: `(user_id, day_date)`
- `diary_entries`:
  - `diary_entry_id`, `diary_day_id`, `meal_type`, `meal_id`
  - unique: `(diary_day_id, meal_type)`

## Known Pitfalls and Notes

- The historical FK issue in `meal_items` should reference `meals(meal_id)`.  
  Current file already uses the correct FK.
- If someone ran migrations before FK fix, old MySQL state may still be broken.  
  In that case reset affected table(s) or rebuild DB from clean state.
- Some comments in `Maintenance.php` show encoding artifacts, but SQL structure is valid.

## Local Runbook

Backend:

- `cd backend`
- `composer install`
- configure DB via `backend/config/*.php` override
- serve `backend/public` through web server/PHP runtime
- first API hit triggers `Maintenance->database()` migration flow

Frontend:

- `cd frontend`
- `npm install`
- `npm run dev`
- optional checks: `npm run type-check`, `npm run build`, `npm run lint`

## Product Behavior Target (what to build next)

- CRUD for ingredients with per-100g nutrition values.
- CRUD for meals grouped by day part (`breakfast`, `lunch`, `dinner`).
- Add meal items by ingredient + grams.
- Compute per-item nutrition and calories from grams.
- Compute totals for full meal.
- Diary day view: assign one meal per day part and compute whole-day totals.

## Practical Conventions

- Keep IDs as `BIGINT UNSIGNED` and use `*_id` naming consistently.
- Keep MySQL + SQLite compatibility in SQL where possible (project supports both).
- When changing schema, always bump DB version in `Maintenance.php` with forward-only migration steps.