food-tracer/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Food Tracer je aplikace pro evidenci snědených jídel a útraty za jídlo. Czech-language UI. Full-stack TypeScript monorepo. Technologicky i vzhledově navazuje na sesterský projekt Luncher (../Luncher) — sdílí s ním stack, konvence i design systém.

Monorepo Structure

types/    → Shared OpenAPI-generated TypeScript types (source of truth: types/api.yml)
server/   → Express 5 backend (Node.js 22, ts-node)
client/   → React 19 frontend (Vite 7, React Bootstrap)

Package manager: Yarn Classic. Deployment: Dockerfile, compose.yml.

Development Commands

Initial setup

cd types && yarn install && yarn openapi-ts   # Generate API types first
cd ../server && yarn install
cd ../client && yarn install

Running dev environment

./run_dev.sh      # tmux (Linux/macOS)
.\run_dev.ps1     # dvě PowerShell okna (Windows)

# Nebo ručně:
cd server && NODE_ENV=development yarn startReload   # Port 3001
cd client && yarn start                              # Port 3000, proxies /api → 3001

Building & tests

cd types && yarn openapi-ts      # Regenerate types from api.yml
cd server && yarn build          # tsc → server/dist
cd server && yarn test           # Jest (in-memory storage)
cd server && yarn test meals     # Run one file by name
cd client && yarn build          # tsc --noEmit + vite build → client/dist

Architecture

API Types (types/)

• OpenAPI 3.0 spec in types/api.yml — thin aggregator, endpoint specs in types/paths/<domain>/*.yml, shared schemas in types/schemas/_index.yml
• yarn openapi-ts generates types/gen/ (client.gen.ts, sdk.gen.ts, types.gen.ts)
• Both server and client import from these generated types
• When changing API contracts: update api.yml first, then regenerate

Server (server/src/)

• Entry: index.ts — Express app, auth middleware, error middleware
• Routes: routes/ — dayRoutes, mealRoutes, activityRoutes, workoutRoutes, statsRoutes, calorieRoutes, settingsRoutes, importRoutes
• Domain: meals.ts (jídlo), activities.ts (pohyb), workouts.ts (šablony tréninků), sleep.ts (spánek), profile.ts (tělesné údaje a výpočet BMR), dayOverview.ts (spojení dne a bilance), statsService.ts (agregace), luncherImport.ts (parsování exportů z Luncheru), settings.ts, calories.ts
• Auth: auth.ts — JWT + volitelná autentizace z hlavičky reverzní proxy
• Storage: storage/index.ts factory dle proměnné STORAGE; backendy: json.ts (soubor, vývoj), redis.ts (produkce), memory.ts (testy)
• Config: .env.development / .env.production (viz .env.template)

Client (client/src/)

• Entry: index.tsx → AppRoutes.tsx; Login.tsx je přihlašovací obrazovka
• Pages: pages/ — DayPage (přehled dne se záložkami Příjem/Výdej), TemplatesPage (šablony tréninků), ProfilePage (tělesné údaje a klidový výdej), StatsPage (statistiky + import)
• Components: components/ (Header, CalorieLookup) a components/modals/ (MealModal, ActivityModal, ApplyWorkoutModal, SettingsModal, ImportModal)
• Klientské enumy patří do enums.ts jako TypeScript enum s mapou popisků, ne jako inline union u komponenty (DayTab, StatsRange)
• Context: context/auth.tsx (JWT), context/settings.tsx (světlý/tmavý motiv)
• Routing: konstanty adres jsou v routes.ts, ne v AppRoutes.tsx — hlavička je potřebuje a kruhový import by je nechal nedefinované
• Styling: Bootstrap 5 + React Bootstrap + SCSS; design systém a proměnné --ft-* jsou v App.scss, stránkové styly co-located vedle komponent
• API: přes OpenAPI SDK z types/gen/

Data model

• Jídlo (MealEntry) patří jednomu dni a jednomu uživateli; klíč úložiště je meals:<login>:<YYYY-MM-DD> a hodnotou je pole záznamů dne.
• Ceny jsou všude celá čísla v haléřích — v úložišti, v API i mezi klientem a serverem. Na koruny se převádí až při zobrazení (formatPrice v Utils.tsx). Stejnou konvenci má Luncher, díky tomu se částky z importu přenesou beze ztráty.
• Kalorie jsou volitelné celé číslo v kcal. Jídla bez kalorií se do součtů nezapočítávají.
• Gramáž (weight, g) a jednotkové hodnoty (pricePer100g v haléřích za 100 g, caloriesPer100g v kcal) umožňují dopočet — viz níže.

Gramáž a kalorie

deriveAmounts v server/src/meals.ts je jediný zdroj pravdy pro dopočty:

1. gramáž = price / pricePer100g * 100, pokud není zadaná ručně
2. kalorie = weight / 100 * caloriesPer100g, jinak ručně zadaná hodnota

Ručně zadaná gramáž má vždy přednost — porci lze zvážit přesněji, než kolik řekne cena. Sazba je na každém záznamu zvlášť, takže hlavní jídlo za 44 Kč/100 g a salát s jiným cenováním můžou být ve stejném dni vedle sebe. Výchozí sazby podniků drží server/src/settings.ts (sourceRates) a klient jimi předvyplňuje pole, když uživatel vybere zdroj.

client/src/Utils.tsx má stejnojmennou funkci pro živý náhled ve formuláři. Když se změní jedna, musí se změnit i druhá — jinak klient ukazuje něco jiného, než server uloží.

Zdroje energetických hodnot

server/src/calorieProvider.ts definuje rozhraní CalorieProvider a jeho implementaci nad Open Food Facts. Poskytovatel je záměrně vyměnitelný za jeden soubor a nikdy nevyhazuje výjimku — při nedostupnosti vrací unavailable, takže hledání jen přijde o návrhy a nespadne. CALORIE_PROVIDER=none externí dotazy vypne (offline provoz, testy).

Poznámky ke zdrojům, ověřené v září 2026:

• KalorickéTabulky.cz nemají veřejné API. Jejich robots.txt zakazuje /*query.page (jejich vyhledávání) a smluvní podmínky omezují užití nad rámec zamýšleného účelu, takže se odtud nesmí scrapovat. Aplikace jen nabídne odkaz na jejich tabulku potravin a zkopíruje název jídla do schránky. Předvyplnit jejich hledání z URL nejde — běží v JavaScriptu a parametry v query stringu ignoruje (ověřeno porovnáním odpovědí).
• Open Food Facts: používá se search.openfoodfacts.org, ne hlavní world.openfoodfacts.org — tamní /cgi/search.pl i /api/v2/search vrací 503. Produkty bez energy-kcal_100g se odfiltrují.
• Vlastní knihovna (server/src/calories.ts) si pamatuje kcal/100 g pod znormalizovaným názvem jídla a řadí se před externí návrhy — na kantýnová jídla sedí líp než databáze balených potravin. Plní se sama při uložení jídla.

Pohyb a energetická bilance

Den má dvě strany a DayPage je dělí do záložek:

• Příjem — jídla (MealEntry), klíč meals:<login>:<datum>
• Výdej — pohyb (ActivityEntry), klíč activities:<login>:<datum>

Aktivita se měří v jednotce (ActivityUnit: KROKY, MINUTY, KM, OPAKOVANI) a kalorie se dopočtou jako getTotalQuantity(quantity, sets) / 100 * caloriesPer100Units. Sto jednotek, ne jedna — u kroků by sazba na jeden krok byla zlomek (~0,04 kcal) a aplikace všude pracuje s celými čísly. Stejná konvence jako u energie jídla na 100 g.

quantity je množství na jednu sérii, sets je počet sérií; celkové množství je jejich součin. Drží se odděleně schválně: 3 × 40 opakování s pauzami je jiný trénink než 120 v kuse, i když spálené kalorie vyjdou stejně. Jedna série je výchozí stav a neukládá se.

Opačný směr k použití šablony je createWorkoutTemplateFromActivities — z aktivit odcvičeného dne (všech, nebo vybraných) vznikne šablona. U jídla to umí createMealTemplateFromMeal, které navíc přepíše šablonu stejného názvu; opakované "uložit jako šablonu" u téhož jídla má dát jednu šablonu, ne několik stejných. Záznamy ve dni zůstanou v obou případech beze změny.

WorkoutTemplate (workouts.ts) je pojmenovaný seznam položek. Položka je buď cvik (kind: CVIK), nebo odkaz na jinou šablonu (kind: SABLONA), jejíž cviky se při použití rozbalí. Použitím vzniknou běžné aktivity s vazbou templateId — jsou samostatné, takže úprava založené položky šablonu nemění.

Zanoření je povolené jen na jednu úroveň a checkNesting to hlídá z obou stran: šablona nesmí odkazovat na takovou, která sama něco skládá, a zároveň nesmí začít skládat, pokud ji už někdo používá. Bez druhé kontroly by druhá úroveň vznikla oklikou přes úpravu. Smazat nelze šablonu, kterou skládá jiná — zůstal by odkaz do prázdna. Šablony uložené dřív, než skládání přibylo, nemají kind; withKind jim ho při načtení doplní na CVIK.

buildEnergyBalance v dayOverview.ts počítá: bilance = příjem − (klidový výdej + pohyb). Záporná hodnota je deficit. Bez nastaveného klidového výdeje porovnává bilance jen jídlo proti pohybu — to není skutečný deficit, proto se to přes hasBasal: false propisuje do UI, aby to číslo nikoho nemátlo.

Klidový výdej se bere z settings.effectiveBasalCalories: ručně zadaný basalCalories má přednost před hodnotou spočítanou z tělesných údajů (computeBasalCalories v profile.ts, rovnice Mifflin–St Jeor). Výpočet záměrně nenásobí koeficientem fyzické aktivity (PAL), jak to dělají kalkulačky TDEE — pohyb se eviduje zvlášť a přičítá se, takže vynásobení by ho započítalo dvakrát.

Spánek (sleep.ts, klíč sleep:<login>:<datum>) se eviduje jako kontext dne a do bilance nevstupuje. Klidový výdej je hodnota za celých 24 hodin včetně spánku a žádná ze standardních rovnic délku spánku jako proměnnou nemá — přičítat nebo odečítat za něj kalorie by bylo vymýšlení čísla. Test to hlídá: bilance se po zadání spánku nesmí změnit.

GET /api/day?date= vrací DayOverview se vším naráz (jídlo, pohyb, bilance), takže DayPage si vystačí s jedním voláním.

Šablony jídel

MealTemplate (mealTemplates.ts, klíč mealTemplates:<login>) je opakovaně jedené jídlo. Na rozdíl od šablon tréninků se neskládá z jiných — je to plochý záznam. Použitím vznikne běžný MealEntry přes addMeal, takže gramáž, cenu i kalorie dopočítá stejná logika jako u ručně zadaného jídla.

Šablona může nést buď calories (celá porce), nebo caloriesPer100g + weight. Obojí projde deriveAmounts, takže stačí vyplnit, co o jídle víte.

Pole note slouží i na postup přípravy u domácích jídel. Strukturované suroviny (recept jako seznam položek s množstvím) mohou přibýt později jako další volitelné pole, aniž by se muselo měnit cokoli stávajícího.

Kontrakt má vlastní MealTemplateInput, kde je id volitelné — MealTemplate ho vyžaduje a nešlo by jím posílat novou šablonu.

Import z Luncheru

server/src/luncherImport.ts čte měsíční přehled ze stránky statistik Luncheru ve všech třech formátech, které Luncher exportuje (XLSX, CSV, JSON — viz ../Luncher/server/src/userExport.ts).

• Sloupce se hledají podle názvu hlavičky, ne podle pozice.
• CSV má BOM, oddělovač ;, datum DD.MM.YYYY a desetinnou čárku (český Excel).
• XLSX má dva listy — čte se Přehled, list Souhrn se ignoruje.
• Řádky se zakládají jako oběd, pokud se neurčí jinak (Luncher řeší obědy).
• name = jídlo → poznámka → typ záznamu. U voleb "Budu objednávat" a "Rozhoduji se" bývá sloupec s jídlem prázdný a co se reálně jedlo stojí v poznámce ("Chefie - Těstovinový salát"), proto ten mezikrok. Poznámka, ze které se stal název, se už nekopíruje do note.
• source = obchod objednávky, jinak podnik. Stavy volby z NON_PLACE_TYPES ("Budu objednávat", "Rozhoduji se", "Objednávka", "Mám vlastní/neobědvám") nejsou místa, takže se jako zdroj nepoužijí a záznam zůstane bez zdroje.
• Duplicity řeší importKey složený z data, pořadí řádku v rámci dne, typu, jídla a částky — opakovaný import stejného měsíce nic nezduplikuje.
• Endpoint podporuje dryRun pro náhled před uložením; klient ho vždy použije.

Když se změní formát exportu v Luncheru, je potřeba upravit i tento parser a testy v server/src/tests/luncherImport.test.ts, které si export sestavují přesně tak, jak ho Luncher generuje.

Conventions

• Czech naming for domain variables and UI strings; English for infrastructure code
• TypeScript strict mode in both client and server
• Server module resolution: Node16; Client: ESNext/bundler
• Komentáře v češtině, u netriviálních míst vysvětlují proč, ne co