Craig
83 lines
2.3 KiB
Markdown
83 lines
2.3 KiB
Markdown
# CalCount
|
|
|
|
A personal, self-hosted calorie counter web app with barcode scanning via phone
|
|
camera and OpenFoodFacts lookup. See [SPEC.md](SPEC.md) for the full spec,
|
|
data model, API design, and development rules (§8 — read it before writing code).
|
|
|
|
## Stack
|
|
|
|
- **Backend:** Python ≥3.12, FastAPI, SQLAlchemy 2, Pydantic 2, SQLite, httpx — managed with **uv**
|
|
- **Frontend:** Svelte 5 (runes) + Vite 7, zxing-wasm barcode fallback — managed with **npm** (Node ≥22.12)
|
|
|
|
## Project layout
|
|
|
|
```
|
|
backend/ FastAPI app (main.py), SQLAlchemy models, Pydantic schemas,
|
|
routers/, services/, migrations/, tests/
|
|
frontend/ Vite + Svelte SPA (src/), lib/ (api, stores, scanner, format),
|
|
components/
|
|
```
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
# Backend (uv creates .venv and installs from uv.lock)
|
|
cd backend
|
|
uv sync
|
|
|
|
# Frontend
|
|
cd frontend
|
|
npm install
|
|
```
|
|
|
|
## Run
|
|
|
|
Single command — starts both servers, cleans up on Ctrl+C:
|
|
|
|
```bash
|
|
./dev.sh
|
|
```
|
|
|
|
| Server | URL |
|
|
|----------|---------------------------|
|
|
| Backend | http://localhost:8000 |
|
|
| Frontend | http://localhost:5173 |
|
|
|
|
Or manually in two terminals:
|
|
|
|
```bash
|
|
# Terminal 1 — backend
|
|
cd backend && uv run uvicorn main:app --reload --host 0.0.0.0
|
|
|
|
# Terminal 2 — frontend (exposed on LAN for phone testing)
|
|
cd frontend && npm run dev:host
|
|
```
|
|
|
|
The SQLite database (`backend/calcount.db`) is created and migrated
|
|
automatically on backend startup (`backend/migrations/`).
|
|
|
|
The SQLite database (`backend/calcount.db`) is created and migrated
|
|
automatically on backend startup (`backend/migrations/`).
|
|
|
|
## Test
|
|
|
|
```bash
|
|
cd backend && uv run pytest # backend suite
|
|
cd frontend && npm test # frontend suite (vitest)
|
|
```
|
|
|
|
## Build
|
|
|
|
```bash
|
|
cd frontend && npm run build # production build to frontend/dist/
|
|
```
|
|
|
|
# Agentic dev
|
|
Defined subagents, idea is big strong agent tells the little ones what to do. I maybe have overkilled on the "small" agents, v4 pro is till pretty powerful. Play around with it and see what we can get away with.
|
|
|
|
|
|
# Future enhancements
|
|
- fully offline JS version (new project built out of this, i have some notes on this somewhere)
|
|
- download and use https://world.openfoodfacts.org/data
|
|
- have this version work offline (pwa or local storage or something)
|
|
- |