calcount/SPEC.md

CalCount — Specification & Decisions

A personal, self-hosted calorie counter web app with barcode scanning via phone camera and OpenFoodFacts lookup.

---

1. Tech Stack

Layer	Decision	Version	Notes
Language	Python	≥3.12
Backend framework	FastAPI	≥0.115, <1.0	Lightweight, async-native, excellent Pydantic integration
ASGI server	uvicorn	≥0.30	Dev via uv run uvicorn main:app --reload
Data validation	Pydantic	≥2.7, <3	Request/response schemas; defined separately from ORM models
Database	SQLite	Bundled with Python	Single-file, zero-config, perfect for single-user personal use
ORM	SQLAlchemy	≥2.0, <2.1	Plays well with Pydantic; define DB models + Pydantic schemas separately, FastAPI bridges them
HTTP client (OFF calls)	httpx	≥0.27	Used by the OFF proxy; mocked at this boundary in tests
Testing	pytest	≥8	See Testing Strategy (§8.4)
Package management	uv	latest	Fast Python package manager; uv.lock holds the exact pins
Frontend	Svelte 5 (runes) + Vite	Svelte ^5, Vite ^7, Node ≥22.12	SPA talking to the FastAPI backend via fetch(). Component-based reactivity, but still a fully decoupled static frontend — the backend never renders HTML. package-lock.json holds the exact pins. Build plugin: @sveltejs/vite-plugin-svelte ^6.
Frontend test runner	Vitest	^4	Only for stores/format logic — no component tests in v1 (§8.4)
Barcode scanning	Custom scanner component	zxing-wasm ^3	Native BarcodeDetector API where available (Chromium/Android), falling back to zxing-wasm (actively maintained ZXing-C++ WASM build) for Safari/Firefox. Camera via getUserMedia; decode loop throttled to ~3-5 fps. Avoids html5-qrcode, which is unmaintained.
Food data	OpenFoodFacts API proxied through backend	API v2	GET /api/off/product/{barcode} and GET /api/off/search?q=.... All OFF calls go through the backend so there's one source of truth and caching is possible.
Auth	None	—	Personal single-user; no login, no sessions, no multi-tenancy
Deployment	Self-hosted	—	Exact method TBD (Docker, systemd, etc.)

Version numbers are floors/ceilings; exact pins live in uv.lock and package-lock.json. Update this table when bumping a major version or adding a dependency (rule §8.3.3).

---

2. Data Model

2.1 foods table

The canonical food database. Grows over time as products are scanned/searched and meals are saved.

Column	Type	Notes
id	int (PK)
name	text	Display name
brand	text	nullable
barcode	text	nullable, unique when set; the EAN-13/UPC from OFF
source	text	"openfoodfacts", "manual", or "meal"
is_meal	bool	true if this is a composed meal template
unit_type	text	"weight" (nutrition per 100g) or "count" (nutrition per 1 item). Default "weight".
calories_per_unit	real	nullable. Mandatory for non-meal foods — per 100g for weight-type, per 1 item for count-type. Null for meals (nutrition derived from components). Invariant enforced with a CHECK constraint: is_meal = 1 OR calories_per_unit IS NOT NULL.
protein_per_unit	real	nullable
carbs_per_unit	real	nullable
fat_per_unit	real	nullable
fiber_per_unit	real	nullable
saturated_fat_per_unit	real	nullable
sugars_per_unit	real	nullable
sodium_per_unit	real	nullable
serving_size_g	real	Default serving size in grams. Nullable — null for count-type foods (e.g. "1 apple") where the concept of grams doesn't apply.
serving_name	text	Human label for the default serving, e.g. "1 slice (28g)", "1 apple", "100g". Can be edited by user.
off_data	text	Full OpenFoodFacts product JSON blob, salted away for future use. Null for manual/meal foods. (Stored as TEXT — SQLite has no native JSON type.)
deleted_at	datetime	nullable; soft-delete timestamp. Foods with deleted_at IS NOT NULL are hidden from search/recent but still renderable in historical log entries.
created_at	datetime
updated_at	datetime

Key design choices:

• Nutrition stored as individual nullable columns (not JSON). Only calories_per_unit is mandatory, and only for non-meal foods — meal nutrition is always derived from components (2.2), never stored. This gives type safety, SQL queryability, and clean SQLAlchemy/Pydantic mapping. Extra nutrients can be added later via migration without touching the others.
• quantity — one field, interpreted by context. There is no quantity_grams column anywhere. Instead, a single quantity field changes meaning based on what it's attached to:
  • unit_type = "weight": quantity is grams. Nutrition = (quantity / 100) × nutrition_per_unit.
  • unit_type = "count": quantity is an item count. Nutrition = quantity × nutrition_per_unit.
  • Meal (logged via daily_log): quantity is a scaling factor (1.0 = one full meal, 1.5 = 1.5×).
  • This avoids misleading column names that lie for count-type foods or meal scaling. The nutrition service is the single place that resolves context.
• unit_type determines the nutrition base and quantity interpretation (see above). Two values are sufficient for v1:
  • "weight": Default. Covers most OFF products, manual entries, and liquids (ml ≈ g; error is negligible for beverages and small oil quantities — measure by weight if precision matters).
  • "count": For foods where per-item nutrition is the natural unit (eggs, apples, protein bars).
  • The "both per-100g and per-item" case (e.g. a chocolate bar) is handled by the serving mechanism, not a third unit_type. The food is weight-type with serving_size_g = 55, serving_name = "1 bar (55g)". The UI presents "1 bar" as the default serving but the user can always enter raw grams. No third unit type needed.
• is_meal flag distinguishes atomic foods from composed meals. Both live in the same table so they're equally searchable.
• Meal nutrition is derived from its components (not stored redundantly — see 2.2). Editing a component food retroactively changes all historical meals referencing it. Acceptable tradeoff for a personal app (fix data once).
• serving_size_g and serving_name are editable per food. The UI presents the serving as the default logging amount, but the user can always override the quantity.
• Soft-delete: Foods are never hard-deleted. DELETE /api/foods/{id} sets deleted_at. Deleted foods are excluded from search/recent but remain available for rendering historical log entries that reference them.

2.2 meal_components table

Defines what goes into a meal. Only rows where foods.is_meal = true have entries here.

Column	Type	Notes
id	int (PK)
meal_id	int (FK → foods.id)	The meal this component belongs to
food_id	int (FK → foods.id)	The component food (can itself be a meal — nesting allowed)
quantity	real	Amount of this component. Interpreted per the component food's unit_type (grams for weight-type, count for count-type).

Deriving meal nutrition: When a meal is queried, compute nutrition by summing each component's nutrition scaled to quantity, then normalize back to per-unit and total serving. This is computed, not stored — so if a component food's nutrition is updated, the meal automatically reflects the change.

Nesting resolution: Meals can contain other meals. Resolve recursively at query time to avoid cycles. Insertion should check for cycles.

2.3 daily_log table

Each row is a food/meal entry logged on a specific date with a specific quantity.

Column	Type	Notes
id	int (PK)
date	date	The day this entry belongs to
food_id	int (FK → foods.id)	The food or meal logged
quantity	real	How much was consumed. Interpreted per the food's unit_type: grams for weight-type, item count for count-type, scaling factor for meals (1.0 = one full meal).
meal_slot	text	nullable; "breakfast", "lunch", "dinner", "snack" — loosely coupled, used for grouping in UI
sort_order	int	Position within the day/meal-slot for display ordering
created_at	datetime

Notes:

• No separate "meal log" table. When a meal is logged, the entry references the meal food. The UI can optionally "explode" it to show components, or keep it collapsed. For target math: always sum the exploded nutrition.
• meal_slot is advisory — changing or removing it later should be trivial.

2.4 targets table

User's nutritional targets, which can change over time.

Column	Type	Notes
id	int (PK)
start_date	date	When this target became active
end_date	date	nullable; null = currently active
calories	int	Daily calorie target
protein_g	real	nullable
carbs_g	real	nullable
fat_g	real	nullable

Notes:

• Only one row has end_date IS NULL at a time (the current target). Enforced in application logic.
• Historical views use the target whose date range contains the log date.
• Additional macro fields (fiber, saturated fat, etc.) can be added later as optional columns.

---

3. API Design Sketch

All endpoints return JSON. No HTML rendering from the backend.

3.1 Foods

GET    /api/foods/recent             — most recently logged foods (query param `limit`, default 10). Returns foods ordered by most recent appearance in daily_log, deduplicated.
GET    /api/foods                    — search foods (query params: `q` for name+brand; `barcode=` for exact lookup; `limit`/`offset` for pagination, default 50/0)
GET    /api/foods/{id}               — get single food with computed nutrition (for meals: includes nested components)
POST   /api/foods                    — create manual food
PUT    /api/foods/{id}               — update food (name, serving, nutrition, etc.)
DELETE /api/foods/{id}               — soft-delete (sets `deleted_at`; food hidden from search/recent but preserved for historical logs)
POST   /api/foods/{id}/restore       — clear `deleted_at` (used by the food management view; `GET /api/foods` takes `include_deleted=true` to list deleted foods)

Note: scanning a barcode that belongs to a soft-deleted food restores that food (clears deleted_at) rather than creating a duplicate — barcode uniqueness makes a fresh insert fail otherwise, and history stays attached to one row.

3.2 Meals

POST   /api/meals/from-log           — create a meal from selected daily_log entries
       Body: { name, entry_ids: [...], date }
       Runs in a transaction: creates the meal food + components, deletes the source log entries,
       inserts a single replacement log entry. Rolls back entirely on any failure.
POST   /api/meals/{meal_id}/unpack   — on a given date, replace a logged meal entry with its component entries
       Body: { date }
       Runs in a transaction: deletes the meal log entry, inserts individual log entries for each
       component (resolved recursively if nested). Each new entry's quantity = component quantity
       × the original entry's quantity (so unpacking a 1.5× meal yields 1.5× each component).
       Rolls back entirely on any failure.
PUT    /api/meals/{meal_id}/components — replace a meal's component list (for editing recipes)
       Body: { components: [{ food_id, quantity }, ...] } — full replacement, cycle-checked.

3.3 Daily Log

GET    /api/log?date=YYYY-MM-DD      — get all entries for a date.
       Response includes meals with their components nested, so the
       frontend can render a collapsible row (collapsed by default,
       showing the meal name + total calories; expand to see
       individual components with their quantities).
POST   /api/log                      — add an entry: { food_id, quantity, meal_slot?, date }
PUT    /api/log/{id}                 — update quantity, meal_slot, etc.
DELETE /api/log/{id}                 — remove an entry
GET    /api/log/summary?date=YYYY-MM-DD — computed totals for the day vs. target

3.4 Targets

GET    /api/targets                  — list all targets (history)
GET    /api/targets/current          — current active target
POST   /api/targets                  — create a new target (auto-closes previous)
PUT    /api/targets/{id}             — update a target

3.5 OpenFoodFacts proxy

All OpenFoodFacts requests go through the backend. The frontend never calls OFF directly.

GET    /api/off/search?q=...         — proxy search to OFF
GET    /api/off/product/{barcode}    — proxy product lookup by barcode
POST   /api/off/refresh/{food_id}    — re-fetch a food's data from OFF (by its stored barcode) and update the local food row

OFF data is returned to the frontend as a normalized JSON object matching our foods schema (nutrition fields mapped to our column names). No local DB write happens at this stage — the frontend receives the data, the user can edit it, and only on confirm does POST /api/foods save it.

---

4. User Flows

4.1 Scan barcode

1. User taps "Scan" button
2. Camera opens (html5-qrcode)
3. If camera permission denied: show clear message — "Camera access needed for barcode scanning. Check your browser settings." — alongside a manual barcode text input as fallback.
4. User points at barcode → barcode captured
5. Backend called: GET /api/foods?barcode=... first checks local DB
6. If found locally → return food with serving info. User can optionally tap "Refresh from OpenFoodFacts" to pull latest data from OFF (useful if product formulation changed). User edits quantity → confirm → logged.
7. If not found locally → GET /api/off/product/{barcode} → return OFF data pre-filled into editable form
8. If OFF not found → tell user "not found", offer manual entry or free-text search
9. User confirms → food saved to local DB (on confirm, not on scan) + logged to today

Manual barcode fallback: If the camera is unavailable (denied, unsupported, or user just prefers typing), a small text input accepts a barcode number. On submit, the flow jumps to step 5 above. This is a secondary path — the primary flow is camera scanning.

4.2 Free-text search

1. User types in search bar
2. GET /api/foods?q=... — searches local DB name+brand
3. If no results, optionally fall back to /api/off/search?q=...
4. Results shown as list; user selects one
5. User edits serving size/quantity → confirm → logged to today

4.3 Create a meal from today's entries

1. User views today's log
2. Selects multiple entries (checkboxes)
3. Taps "Save as Meal"
4. Prompted for a name (no auto-suggest)
5. System: creates new foods row with is_meal=true and meal_components rows from selected entries
6. System: replaces selected log entries with a single entry referencing the new meal
7. Future: the meal appears in food search results

4.4 Unpack a meal

1. User views today's log, sees a meal entry
2. Taps "Unpack" on that entry
3. System: deletes the meal log entry, inserts individual entries for each component (resolved recursively if nested), with each component's quantity multiplied by the original entry's scaling factor
4. User can now tweak individual amounts

4.5 Manual food creation

1. User taps "Add Food" (without scanning)
2. Fills in: name, brand (optional), calories per unit (per 100g or per item depending on unit_type), serving info, optional macros
3. Saved to local DB
4. Immediately available for logging

4.7 Manage food library

1. User taps "Foods" nav item
2. Browsable, searchable, paginated list of all local foods (uses GET /api/foods)
3. Each row: name, brand, calories, edit and delete buttons
4. Edit opens the same food editor used in scan/search flows; meals additionally expose component editing (add/remove/change quantities)
5. Toggle shows soft-deleted foods; deleted rows can be restored

4.6 Dashboard / daily view

1. User lands on today's log
2. Progress bar at top: current calories / target calories, with remaining
3. Below: entries grouped loosely by meal_slot
4. Each entry shows: food name, quantity, calories, mini edit/delete buttons
5. "Scan" and "Search" buttons prominent

---

5. Open Decisions / Deferred

Item	Status	Notes
Frontend framework	Decided	Svelte (Vite + Svelte) from the start. Vanilla JS would become unwieldy with collapsible meal rows, scanner integration, and multi-view state.
Exact deployment method	Deferred	Docker vs bare systemd vs something else. Decide when the app runs locally.
OFF search fallback	Confirmed	All OFF requests proxied through backend. Frontend never calls OFF directly.
OFF data refresh	Confirmed	When viewing a food that came from OFF, a "Refresh from OpenFoodFacts" button re-fetches the product data and updates the local food.
Camera permission handling	Confirmed	Permission denied → clear message + manual barcode text input as fallback (section 4.1).
HTTPS for camera	Confirmed	getUserMedia requires a secure context — plain LAN HTTP won't open the camera. Handled via existing Caddy reverse proxy on the homeserver (TLS). Must be in place before scanner testing on a phone.
Fiber/saturated fat/sugar/sodium in UI	Deferred	Columns exist in the foods table. UI shows only PCF+calories initially. Add to UI later.
Soft-delete vs hard-delete for foods	Decided	Soft-delete. deleted_at column added; deleted foods hidden from search/recent but preserved for historical log rendering.
Import/export	Deferred	SQLite file is fine for backup. A CSV export button could be added later.
Body weight tracking	Not planned	Out of scope for v1.
Nutrition derivation: live vs snapshotted	Decided	Live derivation. Editing a food retroactively changes historical meal entries. Acceptable tradeoff for a personal app.

---

6. Non-Goals (v1)

• User authentication / multi-user
• Body weight / measurement tracking
• Barcode scanning from desktop (phone only)
• Native app / PWA (though PWA manifest could be added cheaply later for "add to home screen")
• Social features, sharing
• AI-powered food recognition from photos
• Nutrition goals per meal-slot (only daily totals)
• Complex unit conversion (stick to grams + per-item counting)

---

7. Project Structure (Proposed)

calcount/
├── backend/
│   ├── main.py              # FastAPI app entry
│   ├── models.py            # SQLAlchemy models
│   ├── schemas.py           # Pydantic request/response schemas
│   ├── database.py          # DB connection, session management
│   ├── routers/
│   │   ├── foods.py
│   │   ├── log.py
│   │   ├── targets.py
│   │   └── off.py           # OpenFoodFacts proxy
│   ├── services/            # Business logic (meal resolution, nutrition math)
│   │   ├── nutrition.py
│   │   └── meals.py
│   └── pyproject.toml       # uv project config
├── frontend/
│   ├── index.html            # Vite entry point
│   ├── package.json
│   ├── vite.config.js
│   ├── src/
│   │   ├── main.js           # Svelte mount point
│   │   ├── App.svelte        # Root component, routing
│   │   ├── lib/
│   │   │   ├── api.js        # fetch() wrappers
│   │   │   ├── scanner.js    # camera + BarcodeDetector / zxing-wasm fallback
│   │   │   └── stores.js     # Svelte stores (shared state)
│   │   ├── components/
│   │   │   ├── Dashboard.svelte
│   │   │   ├── FoodSearch.svelte
│   │   │   ├── FoodEditor.svelte
│   │   │   ├── FoodLibrary.svelte
│   │   │   ├── BarcodeScanner.svelte
│   │   │   ├── MealBuilder.svelte
│   │   │   ├── LogEntry.svelte
│   │   │   └── ProgressBar.svelte
│   │   └── assets/
│   └── public/

└── SPEC.md                   # This file

---

8. Development Best Practices

Rules of the road for anyone (human or AI) working on this codebase. Each rule exists because violating it is easy and painful. Follow them by default; when a rule is deliberately changed, update this section and the changelog.

8.1 Backend

1. Nutrition math lives in exactly one place: services/nutrition.py. Routers never compute nutrition; the frontend never re-derives it. This is the rule most likely to erode — guard it.
2. Routers are thin. Parse/validate via Pydantic → call a service → return a schema. No business logic, no SQL in routers. A handler growing past ~15 lines is the smell.
3. ORM objects never leave the service layer. Services convert SQLAlchemy models → Pydantic schemas (from_attributes=True) before returning. Prevents lazy-loading surprises and leaky abstractions.
4. Sync def endpoints, not async def. FastAPI runs sync handlers in a threadpool — the sane way to use SQLite + SQLAlchemy. No async DB layer at this scale.
5. One DB session per request, via Depends(get_db). No global sessions, no ad-hoc sessions inside services.
6. Multi-write operations are transactions owned by the service. from-log and unpack commit once at the end or roll back entirely — never partial writes.
7. Soft-delete discipline. Every search/recent query filters deleted_at IS NULL; historical log rendering never does. Implement as shared query helpers, not per-endpoint filter clauses — this gets copy-pasted wrong otherwise. Related rule: scanning a soft-deleted food's barcode restores it (clears deleted_at) instead of inserting a duplicate (§3.1).
8. All datetimes UTC; all dates are client-supplied YYYY-MM-DD. The server never decides what "today" is.
9. Migrations from day one. Numbered SQL files in backend/migrations/, applied in order at startup, tracked in a schema_migrations table. Never hand-edit the database; every schema change is a new numbered file — including the initial schema.
10. OFF normalization happens in exactly one module. A descriptive User-Agent header on every OFF call (their API etiquette requires it), timeouts set, and the kcal-vs-kJ field mapping handled there and nowhere else.
11. Pydantic validates at the boundary. Quantities positive; unit_type/source/meal_slot as Literal enums; dates parsed. Bad data never reaches a service.

8.2 Frontend

1. All HTTP goes through lib/api.js. No raw fetch() in components. One place for base URL, error handling, and any future cross-cutting concern.
2. The server is the source of truth for nutrition. The frontend renders computed values from API responses; it never reimplements meal explosion or unit-type resolution. Sole exception: simple linear scaling (quantity × per_unit) for a live preview while editing a quantity — display only, never persisted.
3. Shared state lives in stores, not prop-drilling. Current date, today's log, and current target are stores. Mutation flow: component → api.js → update store from the response.
4. Every async view handles loading / error / empty states. Non-negotiable for the scanner (permission denied, no camera, decode failure) — it's the primary flow.
5. Mobile-first, tested on a real phone. Touch targets, one-hand use, exercised over the LAN via Caddy HTTPS — not just desktop devtools' device emulator.
6. Scanner lifecycle discipline. Stop the camera stream and decode loop on component destroy. A leaked stream drains battery and breaks re-entry to the scanner view.
7. Formatting in one place (lib/format.js): kcal rounding (whole numbers displayed, full precision stored), grams, dates. No scattered Math.round call sites.
8. Svelte 5 runes style only. No legacy $: reactive statements in new code — one reactivity paradigm.

8.3 Cross-cutting

1. schemas.py is the contract. When an endpoint shape changes, the Pydantic schema changes first, then both sides. The shapes in api.js mirror it.
2. SPEC.md stays current. Any decision that changes gets edited here with the changelog updated. The spec is a living document, not a historical artifact.
3. New dependencies require a spec entry. §1 is the dependency registry — nothing enters pyproject.toml/package.json without a row there. This is how library decisions stay deliberate.
4. Dates flow as YYYY-MM-DD strings end-to-end. No Date objects crossing the API boundary, no timezone math anywhere.

8.4 Testing Strategy

Backend (pytest, backend/tests/):

• Focus on the code where correctness actually matters:
  • services/nutrition.py — unit_type resolution, meal recursion, cycle detection, unpack quantity scaling
  • The two transactional endpoints (from-log, unpack) — including rollback on failure
  • Soft-delete query helpers — deleted foods hidden from search/recent, visible in history
• FastAPI TestClient with a fresh temp-file SQLite DB per test session; seed data via fixtures.
• OFF proxy tests mock at the httpx boundary — never hit the real OFF API in tests.
• No coverage targets. Test the math and the money paths; skip CRUD trivia.
• pytest must be green before committing backend changes.

Frontend:

• v1 has no component test suite — it rots fast in a solo project, and the scanner can't be meaningfully unit-tested anyway.
• Vitest only if a store or format.js grows real logic worth pinning down.
• Scanner and camera flows are verified manually on a real phone (requires Caddy HTTPS in place). Checklist:
  • Permission granted → scan works
  • Permission denied → message + manual barcode fallback (flow 4.1)
  • Android Chrome (native BarcodeDetector path)
  • iOS Safari (zxing-wasm fallback path)
  • EAN-13 and UPC-A barcodes both decode

Definition of done: backend changes = pytest green; scanner/log changes = pytest green + real-phone checklist pass.

---

Last updated: 2026-07-26 — Revision #2: nullable calories_per_unit for meals (derived nutrition), unpack quantity scaling, food management view + restore endpoint, meal component editing. Revision #3: dev best practices + testing strategy (§8), version constraints (§1), restore-on-rescan rule (§3.1). Revision dates corrected to 2026. Revision #4: initial project scaffold; uvicorn + Vitest registered in §1.