biteplan/CLAUDE.md

CLAUDE.md

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

Project Overview

BitePlan is a mobile-first Vue 3 PWA for meal planning, raw↔cooked weight conversion, and shopping list management. It targets Android via Capacitor and is designed for a 480px-max viewport. All UI strings and documentation are in Italian.

Commands

npm run dev          # Dev server at http://localhost:5173
npm run build        # Production build → dist/
npm run preview      # Preview built app

npm test             # Vitest unit + integration tests (watch mode)
npm run test:coverage  # Coverage report (v8 provider)
npm run test:e2e     # Playwright e2e (requires dev server running)
npm run test:e2e:ui  # Playwright interactive UI mode

# Single test file
npx vitest run tests/unit/conversion.test.js

# Android APK
bash docker/build.sh           # Debug APK
bash docker/build.sh --release # Signed release APK

E2E tests simulate iPhone 14 Pro viewport (393×852) with Italian locale.

Architecture

App.vue is the root router — it conditionally renders three pages based on a currentPage ref (meal, convert, shop) and hosts the portrait-lock transform, InfoPanel, and DocsPanel.

Three pages in src/pages/:

• MealPlanner.vue — 7-day plan (Mon–Sun), 3 meal slots each (colazione/pranzo/cena), per-day accordion via MealCard.vue, QR share, and "generate shopping list" export
• Converter.vue — real-time food search → select food+method → bidirectional raw↔cooked calculation using yield coefficients from src/data/conversions.json
• ShoppingList.vue — checklist with add/remove/check, importable from meal planner

State & persistence: No Pinia/Vuex — pages use Vue composables + direct localStorage via the wrappers in src/utils/storage.js (save(key, val) / load(key, default)).

Conversion logic lives entirely in src/utils/conversion.js:

rawToCooked(food, method, rawGrams, db) = rawGrams * db[food][method].yield
cookedToRaw(food, method, cookedGrams, db) = cookedGrams / db[food][method].yield

yield = cooked_weight / raw_weight. The database in src/data/conversions.json has 50+ foods × 1–4 cooking methods with coefficients sourced from CREA, SINU, USDA (see docs/conversioni.md).

CSS: Vanilla CSS only, no framework. Design tokens are CSS variables in :root in src/style.css (--color-primary: #2d6a4f, --nav-height: 64px, etc.). Buttons must be min 44px; layout is single-column.

Testing

• Unit (tests/unit/): Pure function tests for conversion.js and storage.js
• Integration (tests/integration/): Vue Test Utils component mounts with localStorage seeding
• E2E (tests/e2e/): Playwright against the running dev server

tests/setup.js clears localStorage before/after each test. Vitest uses happy-dom environment.

Android Build

The Docker pipeline in docker/ handles the full Android build:

1. npm run build → dist/
2. cap sync → copies dist into Android project
3. Gradle builds the APK; release APK is signed with docker/biteplan.jks (gitignored)

See docker/README.md for full APK build instructions.