calcount/IMPLEMENTATION_PLAN.md

# CalCount — Implementation Plan

Ordered tickets for delegation. Each ticket is one coherent API surface or UI
flow, sized for a single work session. Acceptance criteria are phrased to be
verifiable with curl/pytest (backend) or a browser (frontend). Dependencies are
sequential unless noted — do them in order.

Milestones:
- **M1 — Manual calorie tracker** (tickets 001–005): app is usable for manual food entry and daily logging.
- **M2 — Barcode scanning & OFF integration** (ticket 006).
- **M3 — Meals** (ticket 007).
- **M4 — Food library management** (ticket 008).

Definition of done for every ticket (spec §8.4): `pytest` green for backend
changes; scanner/log changes additionally need the real-phone checklist.

---

# TICKET-001: Foods CRUD (create, read, update, soft-delete)

**Milestone:** M1
**Depends on:** none (scaffold only)
**Spec references:** §2.1 (foods table), §3.1 (API), §8.1 rules 1–3, 5, 7, 11

## Goal

Complete the foods write path so a food can be created, read, updated, and soft-deleted via the API. After this ticket, all endpoints in spec §3.1 work except `restore` (which ships with the food library ticket).

## Acceptance criteria

- `POST /api/foods` creates a food and returns it (201). Validates per §8.1 rule 11: `calories_per_unit` required when `is_meal=false`, `unit_type`/`source` constrained, quantities positive. Invalid bodies get a 422 with a useful error.
- `GET /api/foods/{id}` returns a single food, including soft-deleted ones (historical log rendering depends on this — §2.1). 404 for unknown id.
- `GET /api/foods` supports `q` (matches name **and** brand), `barcode` (exact match), `limit`/`offset` (defaults 50/0), and `include_deleted=true`. Soft-deleted foods are excluded by default (§8.1 rule 7).
- `PUT /api/foods/{id}` updates editable fields (name, brand, serving info, nutrition, etc.) and bumps `updated_at`. 404 for unknown id.
- `DELETE /api/foods/{id}` sets `deleted_at` (soft-delete — never hard-delete, §2.1). The food then disappears from search but is still returned by `GET /api/foods/{id}`.
- Barcode uniqueness is respected: creating a food with a barcode that already exists (on a live food) fails with a 409, not a 500.
- ORM objects never leave the service layer; handlers stay thin (§8.1 rules 2–3).
- `pytest` green, including new tests covering: create + read round-trip, validation failures, soft-delete hidden from search but visible by id, barcode conflict.

## Implementation notes

- `FoodCreate` schema exists in `schemas.py` but is incomplete — extend it and add update/read variants as needed. The schema is the contract (§8.3 rule 1): change it first, then the code.
- Soft-delete filtering should be a shared query helper, not per-endpoint filter clauses (§8.1 rule 7) — this is the first real consumer of that pattern, so set it up properly.
- `GET /api/foods/{id}` for meals should eventually include computed nutrition/components — **don't build that here**; return the flat food row and leave meal resolution for the meals ticket.
- `barcode` unique-when-set: SQLite treats NULLs as distinct, so the existing UNIQUE column already allows multiple barcode-less foods. The restore-on-rescan rule (§3.1) is out of scope here — it belongs to the scanning ticket.
- No OFF interaction in this ticket. `source="manual"` is the expected path; don't special-case `"meal"` foods beyond letting the CHECK constraint do its job.
- Router prefix/structure is already in place in `routers/foods.py`; the existing `list_foods` endpoint is a scaffold and can be replaced.

## Out of scope

- Meals (`is_meal=true`) component handling, cycle checks
- `POST /api/foods/{id}/restore` and the restore-on-rescan flow
- `GET /api/foods/recent`
- Any frontend work

## Verify

```bash
cd backend && uv run pytest
# plus a manual smoke test with curl against POST/PUT/DELETE on a dev server
```

---

# TICKET-002: Targets CRUD

**Milestone:** M1
**Depends on:** none (independent of 001; do after it for consistency)
**Spec references:** §2.4 (targets table), §3.4 (API), §8.1 rules 2, 3, 11

## Goal

Users can set and update their daily nutritional targets, with history preserved. After this ticket, `GET /api/targets/current` stops 404ing and the dashboard has something to compare against.

## Acceptance criteria

- `POST /api/targets` creates a new target and auto-closes the previous one (sets its `end_date`). Exactly one row has `end_date IS NULL` at any time — enforced in application logic (§2.4).
- `GET /api/targets` lists all targets (history), ordered by `start_date`.
- `GET /api/targets/current` returns the active target; 404 if none exists.
- `PUT /api/targets/{id}` updates a target (values and/or date range). The single-active-target invariant still holds after any update.
- Validation per §8.1 rule 11: `calories` positive integer, macros non-negative, dates parse, `end_date` after `start_date` when set.
- The auto-close on create happens in one transaction — no window with zero or two active targets.
- `pytest` green, including tests for: create → current round-trip, auto-close of previous target, invariant maintained after updates, validation failures.

## Implementation notes

- Routers stay thin; the single-active-target invariant lives in the service layer (§8.1 rules 2, 6).
- What "auto-close" means for `end_date` (same day vs. day before the new `start_date`) is a judgement call — pick one, document it in the service docstring, and make sure historical lookup by date range stays unambiguous.
- `start_date` is client-supplied `YYYY-MM-DD` like all dates (§8.1 rule 8).
- Historical lookup ("target whose range contains a given log date", §2.4) is needed by the summary ticket — expose it as a service function even if no endpoint uses it yet.

## Out of scope

- Additional macro fields beyond the existing columns (fiber etc. — §2.4 notes)
- Any frontend work

## Verify

```bash
cd backend && uv run pytest
# curl: create two targets, confirm the first is closed and /current returns the second
```

---

# TICKET-003: Daily log write path

**Milestone:** M1
**Depends on:** TICKET-001 (log entries reference foods)
**Spec references:** §2.3 (daily_log table), §3.3 (API), §8.1 rules 2, 3, 6, 8, 11

## Goal

Foods can be logged to a day, edited, and removed. After this ticket the core daily-logging loop works end to end at the API level.

## Acceptance criteria

- `POST /api/log` adds an entry `{ food_id, quantity, meal_slot?, date }` and returns it (201). `quantity` must be positive; `meal_slot` constrained to the four slots; `date` is client-supplied `YYYY-MM-DD` (§8.1 rule 8). 404/422 for unknown `food_id` (including soft-deleted foods — you can't log what you can't search).
- `PUT /api/log/{id}` updates `quantity`, `meal_slot`, and `sort_order`. 404 for unknown id.
- `DELETE /api/log/{id}` removes an entry (hard delete is fine here — §2.3 has no soft-delete). 404 for unknown id.
- `GET /api/log?date=` returns entries for the day ordered by `sort_order`, then id, each with the referenced food embedded (name, brand, unit_type, serving info) so the frontend doesn't need N+1 lookups. Soft-deleted foods still render here (§2.1).
- Meal entries (a `food_id` pointing at an `is_meal` food) are accepted by all of the above — full meal explosion is the meals ticket, but logging a meal must not break.
- `pytest` green, including tests for: add/update/delete round-trip, validation failures, ordering, embedded food data present, soft-deleted food still renders in history.

## Implementation notes

- `LogEntryCreate`/`LogEntryRead` schemas exist but `LogEntryRead` needs the embedded food — design that shape now since the frontend will mirror it (§8.3 rule 1).
- `sort_order` defaulting for new entries (e.g. append to end of day/slot) is a service-layer decision — keep it simple and document it.
- Logging a food with `unit_type="count"` vs `"weight"` needs no special handling at this layer — `quantity` interpretation is the nutrition service's job (§2.1).

## Out of scope

- Computed nutrition in log responses (ticket 004)
- Meal explosion/nesting in responses (ticket 007)
- `GET /api/foods/recent` (uses daily_log, but belongs with the search/scan UX in ticket 006)
- Any frontend work

## Verify

```bash
cd backend && uv run pytest
# curl: create a food, log it to a date, update quantity, delete it
```

---

# TICKET-004: Day summary endpoint (totals vs. target)

**Milestone:** M1
**Depends on:** TICKET-002 (targets), TICKET-003 (log entries)
**Spec references:** §2.1 (quantity interpretation), §3.3 (`/api/log/summary`), §8.1 rule 1

## Goal

`GET /api/log/summary?date=` returns the day's computed nutrition totals alongside the target in effect for that date. This is the first real consumer of the nutrition service.

## Acceptance criteria

- Response includes: summed calories (and protein/carbs/fat at minimum — the other columns are cheap, include them if convenient) across all entries for the date, plus the applicable target (the one whose date range contains the log date — §2.4), or null if none.
- `quantity` is resolved per food context (§2.1): grams/100 for weight-type, per-item for count-type. This math lives only in `services/nutrition.py` (§8.1 rule 1).
- Foods with null nutrition fields contribute 0 for those fields, not an error.
- Meal entries in the log: **temporarily** contribute their flat `calories_per_unit`-style values only if present (they'll be null per the CHECK constraint — so meals contribute 0 for now). Add a clearly-marked TODO; real meal nutrition lands in ticket 007. Do not half-implement meal recursion here.
- Works for arbitrary past/future dates, using the historical target lookup from ticket 002.
- `pytest` green, with tests that are the start of the "test the math" suite (§8.4): weight-type scaling, count-type scaling, mixed entries, null nutrition fields, correct target selected for historical dates, no-target case.

## Implementation notes

- The response shape is a new schema — design it as the contract the frontend ProgressBar will consume (§8.3 rule 1). Remaining-vs-target arithmetic: compute it server-side or leave it to the frontend, but pick one and document it.
- This ticket should grow `services/nutrition.py`, not put math in the router or a summary-specific helper (§8.1 rule 1).

## Out of scope

- Meal nutrition derivation (ticket 007)
- Any frontend work

## Verify

```bash
cd backend && uv run pytest
# curl: seed a target + a few log entries, check totals and target selection for a past date
```

---

# TICKET-005: Frontend daily view (dashboard, progress bar, log entries, manual add)

**Milestone:** M1 — after this ticket the app is usable for manual tracking
**Depends on:** TICKET-003, TICKET-004 (TICKET-001 transitively)
**Spec references:** §4.5 (manual food creation), §4.6 (dashboard), §8.2 (all frontend rules)

## Goal

The main screen shows today's progress against the target and the day's entries, and the user can create a food manually and log it — the full manual-tracking loop in the UI.

## Acceptance criteria

- Dashboard shows: progress bar (consumed vs. target calories, remaining), entries grouped loosely by `meal_slot`, each entry showing food name, quantity (serving-aware where set), and calories.
- Entries can be edited (quantity, meal slot) and deleted from the UI.
- "Add Food" flow: manual creation form (name, brand, calories per unit, unit type, serving info, optional macros — §4.5) that saves and is immediately loggable.
- Logging flow: from search results of local foods (a simple search box hitting `GET /api/foods?q=` is enough — full search UX is ticket 006), pick a food, edit quantity (defaulting to the food's serving where set), confirm → logged to the current date.
- Date navigation: view previous/next days, not just today. Dates are `YYYY-MM-DD` strings throughout (§8.3 rule 4).
- All async views handle loading / error / empty states (§8.2 rule 4). Backend unreachable → clear error, not a blank page.
- All HTTP through `lib/api.js`; shared state (current date, today's log, current target) in stores; mutation flow component → api → store (§8.2 rules 1, 3).
- Formatting via `lib/format.js` only (§8.2 rule 7); Svelte 5 runes style (§8.2 rule 8).
- Mobile-first layout (§8.2 rule 5) — check it at phone width in devtools at minimum.
- Backend never re-derives nutrition in the frontend beyond the permitted live-preview exception (§8.2 rule 2).

## Implementation notes

- Placeholder components exist for Dashboard, ProgressBar, LogEntry, FoodEditor, FoodSearch — fill these in rather than inventing new structure. App.svelte currently has a trivial health check; replace with real layout/routing (simple conditional view switching is fine; no router library needed yet).
- Wire up the `api.js` methods that already exist; add the missing ones (update entry, create target if you surface targets UI — optional here).
- Setting the initial target needs *some* UI or the progress bar has nothing to compare against — a minimal target form is acceptable; polish is not required.
- Live quantity preview while editing is the one place frontend math is allowed (§8.2 rule 2) — display only.

## Out of scope

- Barcode scanning, OFF integration, recent foods (ticket 006)
- Meals: creation, unpacking, collapsible meal rows (ticket 007)
- Food library management view (ticket 008)
- Component tests (none in v1 — §8.4); extend vitest only if stores/format grow real logic

## Verify

```bash
cd backend && uv run pytest   # still green
cd frontend && npm test && npm run build
# manual: run both servers, do the full loop — set target, add food, log it,
# edit quantity, delete it, navigate dates — at desktop and phone widths
```

---

# TICKET-006: OFF normalization + barcode scan & search flows

**Milestone:** M2
**Depends on:** TICKET-005 (uses FoodEditor/FoodSearch UI and the foods write path)
**Spec references:** §3.5 (OFF proxy), §4.1 (scan flow), §4.2 (search flow), §8.1 rule 10, §8.2 rules 4–6, §8.4 (phone checklist)

## Goal

The primary input flow works: scan a barcode (or search OFF by text), get a pre-filled editable form, confirm → food saved locally and logged. Camera permission failure degrades gracefully to manual barcode entry.

## Acceptance criteria

**Backend:**
- OFF responses are normalized to our `foods` schema shape in exactly one module (§8.1 rule 10), including kcal-vs-kJ mapping. No local DB write on lookup — the frontend confirms first (§3.5).
- `GET /api/off/product/{barcode}` returns normalized data or a clean not-found; `GET /api/off/search?q=` returns normalized results. User-Agent and timeouts in place (already scaffolded).
- Restore-on-rescan rule (§3.1): saving a food whose barcode belongs to a soft-deleted food clears `deleted_at` and updates that row instead of inserting a duplicate.
- `POST /api/off/refresh/{food_id}` re-fetches by stored barcode and updates the local row (§3.5). Sensible behaviour when the food has no barcode or OFF no longer has it.
- OFF proxy tests mock at the httpx boundary — never hit the real API (§8.4).

**Frontend:**
- BarcodeScanner component: camera via `getUserMedia`, native `BarcodeDetector` where available, zxing-wasm fallback (§1), decode loop throttled ~3–5 fps.
- Scan flow per §4.1: local DB check first → found: confirm + log (with optional "Refresh from OpenFoodFacts"); not found: OFF lookup → pre-filled FoodEditor → confirm saves + logs; OFF miss: clear "not found" + manual entry / text search offered.
- Permission denied / no camera / decode failure → clear message + manual barcode text input fallback (§4.1, §8.2 rule 4).
- Camera stream and decode loop stop on component destroy; re-entering the scanner works (§8.2 rule 6).
- Free-text search per §4.2: local results first, OFF fallback offered when local is empty.
- `GET /api/foods/recent` implemented (backend) and surfaced in the UI — it's part of making logging fast (§3.1).

## Implementation notes

- Decide the OFF→foods field mapping once, in the normalization module, with tests pinning the kcal/kJ behaviour on real-shaped (recorded, not live) OFF responses.
- zxing-wasm is already installed; keep the WASM loading lazy so the native path never pays for it.
- `lib/scanner.js` is a documented stub — implement behind a clean `startScanner(videoEl, callbacks) → stop()` style interface so the component stays thin.
- HTTPS is required for camera on a phone — coordinate with the user for Caddy access before the manual checklist; the checklist (§8.4) is part of done.

## Out of scope

- Meals (ticket 007)
- Food library management (ticket 008)

## Verify

```bash
cd backend && uv run pytest        # incl. mocked-httpx OFF tests
cd frontend && npm test && npm run build
# real-phone checklist from §8.4 (permission granted/denied, Android Chrome,
# iOS Safari, EAN-13 + UPC-A) — requires Caddy HTTPS in place
```

---

# TICKET-007: Meals (components, from-log, unpack, editing)

**Milestone:** M3
**Depends on:** TICKET-005 (log UI exists), TICKET-004 (summary must learn real meal nutrition)
**Spec references:** §2.2 (meal_components), §3.2 (API), §4.3 (create), §4.4 (unpack), §8.1 rule 6, §8.4 (test the money paths)

## Goal

Users can save a set of log entries as a reusable meal, log meals, unpack them back into individual entries, and edit a meal's components. Meal nutrition is derived live from components everywhere it appears.

## Acceptance criteria

**Backend:**
- `POST /api/meals/from-log` runs as one transaction (§8.1 rule 6): creates the meal food + components, deletes the source entries, inserts one replacement entry. Rolls back entirely on failure.
- `POST /api/meals/{meal_id}/unpack` (transactional): replaces a logged meal entry with component entries, each component quantity × the original entry's scaling factor (§3.2), resolving nested meals recursively.
- `PUT /api/meals/{meal_id}/components` replaces the component list wholesale, cycle-checked (§2.2).
- Meal nutrition is computed by recursive component summation in `services/nutrition.py` (§8.1 rule 1), with cycle detection. Summary (ticket 004), `GET /api/foods/{id}`, and `GET /api/log` responses all show real derived meal nutrition; log responses include meal components nested for the collapsible UI (§3.3).
- The ticket-004 TODO (meals contributing 0) is removed.
- Cycle attempts (meal containing itself, directly or transitively) are rejected with a 422.
- `pytest` green with the §8.4 "money path" suite: recursion depth, nested meals, cycle rejection, from-log/unpack happy paths, and **rollback on failure** for both transactional endpoints.

## Acceptance criteria (frontend)

- "Save as Meal" flow per §4.3: multi-select today's entries, name prompt, confirm → entries replaced by the meal.
- Meal log rows render collapsible: collapsed = meal name + total calories; expanded = components with quantities (§3.3).
- "Unpack" action per §4.4 on a logged meal entry.
- Meal component editing (add/remove/change quantities) exposed from the food editor for `is_meal` foods (§4.7).

## Implementation notes

- This is the highest-complexity ticket — the recursion, cycle detection, and transaction boundaries are the spec's named testing priorities. Build the service layer first with direct unit tests, then wire routers.
- Nested meals can contain meals: resolution must be recursive with a visited-set, both for nutrition and for cycle checks on write.
- Unpack quantity scaling (§3.2) is easy to get wrong — pin it with a dedicated test (1.5× meal → 1.5× each component).
- Editing a component food retroactively changes historical meals (§2.1) — that's intended; don't snapshot.

## Out of scope

- Food library browse/restore UI (ticket 008) — though meal editing shares its editor

## Verify

```bash
cd backend && uv run pytest   # full suite incl. rollback tests
# manual: build a meal from today's entries, log it, unpack it at 1.5×,
# try to create a cycle, confirm summary totals update throughout
```

---

# TICKET-008: Food library management view + restore

**Milestone:** M4
**Depends on:** TICKET-001 (soft-delete), TICKET-007 (meal editing uses the same editor)
**Spec references:** §4.7 (manage food library), §3.1 (restore endpoint, include_deleted)

## Goal

A "Foods" nav view where the user browses, searches, edits, deletes, and restores their local food database.

## Acceptance criteria

- `POST /api/foods/{id}/restore` clears `deleted_at` (backend; §3.1). 404 for unknown id, sensible response if the food isn't deleted.
- Frontend "Foods" view: paginated, searchable list of all local foods using `GET /api/foods` with `limit`/`offset`; each row shows name, brand, calories, edit + delete buttons (§4.7).
- Edit opens the same FoodEditor used in scan/search flows; meals expose component editing (already built in ticket 007).
- Delete confirms first, then soft-deletes — the row disappears from the default list.
- A toggle shows soft-deleted foods (`include_deleted=true`); deleted rows are visually distinct and offer restore.
- Loading/error/empty states throughout (§8.2 rule 4); mobile-first (§8.2 rule 5).
- `pytest` green with restore tests (restore clears flag, food reappears in search, history intact).

## Implementation notes

- This is the last v1 surface — reuse, don't rebuild: FoodEditor, api.js patterns, stores.
- Pagination UI can be minimal (prev/next + count is fine).
- If ticket 006's restore-on-rescan left any edge cases (e.g. restoring a food whose barcode now conflicts), surface and resolve them here.

## Out of scope

- CSV export, bulk operations (§5 — deferred)
- OFF refresh from the library view (already available via ticket 006's endpoint; wiring a button here is optional polish)

## Verify

```bash
cd backend && uv run pytest
# manual: browse/search/paginate, edit a food, delete it, toggle deleted view,
# restore it, confirm it renders in old log entries throughout
```

---

## After v1 (not ticketed)

Deferred items from spec §5: deployment method, CSV export, fiber/sat-fat/sugar/sodium in UI, PWA manifest. Revisit SPEC.md once M1–M4 ship.