Fitness Tracking Web App
A calorie, macro, exercise, and weight tracking web app. Users log meals (via barcode scan, voice, or manual entry), track workouts, and follow a predicted-vs-actual weight trend based on their computed BMR/TDEE.
Stack
- Frontend (
Frontend/) — React 19 + Vite + TypeScript, Tailwind CSS v4, React Context, react-router-dom v7
- Backend (
Backend/) — NestJS 11 + Prisma + PostgreSQL (Supabase, database only)
- External APIs — Open Food Facts (barcode lookup, used as fallback behind a local Postgres product cache), USDA FoodData Central (food name lookup), Web Speech API (client-side voice input), Cloudinary (avatar uploads)
This is a monorepo, but Frontend and Backend deploy independently:
- Frontend → Vercel (root directory set to
Frontend/ in the Vercel dashboard; framework auto-detected, no committed manifest)
- Backend → Vercel, as its own project (root directory set to
Backend/; NestJS is auto-detected and runs as a single Vercel Function; env vars are managed in the Vercel dashboard, no committed manifest)
- Database → Supabase Postgres (database only — Supabase Auth, Storage and the Data API are not used). Local development and e2e use the Docker Postgres in
docker-compose.yml.
See docs/architecture.md for the full system design and docs/business-logic.md for the calorie/TDEE/prediction formulas.
Hosting history
The backend has run on two different hosts:
- Railway (free trial): the NestJS backend first ran on Railway as an always-on server. Its root directory was set to
Backend/ and its build, deploy and environment variables were managed in the Railway dashboard. Every feature up to October 2026 was built and shipped on it: auth with email OTP, food and exercise logging, barcode lookup, and profiles and avatars. This is where I learned to host a backend: connecting a monorepo subfolder, managing secrets on the platform, and wiring CORS between separately hosted frontend and backend.
- Vercel (current): when the free trial ended in October 2026, Railway stopped the service. I moved the backend to Vercel's free tier instead of paying. It now runs as a serverless Vercel Function, so it connects to the database through Supabase's transaction pooler. The reasons and trade-offs are recorded in
docs/adr/0011-backend-on-vercel-functions.md.
Getting started
Prerequisites
- Node.js 20+
- Docker, for the local Postgres (
docker compose up -d from the repo root)
- API keys: USDA FoodData Central, Google OAuth client credentials, SMTP credentials (e.g. a Gmail App Password), Cloudinary credentials
Backend setup
cd Backend
npm install
cp .env.example .env # DATABASE_URL already points at the local Docker DB; fill in ACCESS_TOKEN, REFRESH_TOKEN, USDA_API_KEY, etc.
npx prisma db push # applies the schema — this project uses `prisma db push`, not migrations
npx prisma generate
npx prisma db seed # loads the canonical food catalog (idempotent)
npm run start:dev # http://localhost:3000
Frontend setup
cd Frontend
npm install
cp .env.example .env # set VITE_API_BASE_URL and VITE_GOOGLE_CLIENT_ID
npm run dev # http://localhost:5173
Scripts
| Backend | Frontend |
|---|
| Dev server | npm run start:dev | npm run dev |
| Build | npm run build | npm run build |
| Unit tests | npm test | — |
| E2E tests | npm run test:e2e | — |
| Lint | npm run lint (auto-fixes) | npm run lint (no auto-fix) |
| Format | npm run format | npm run format |
Backend unit tests (npm test) run in CI on every PR (.github/workflows/ci.yml). Backend E2E tests are not run in CI — run them locally whenever backend behavior changes.
Project structure
Backend/ NestJS API — see Backend/README.md
Frontend/ React SPA — see Frontend/README.md
docs/ Architecture, business logic, and requirements docs
specs/ Per-feature specs (spec-kit workflow: spec.md → plan.md → tasks.md)
Environment variables
Real secrets are never committed — see each package's .env.example for the full list of required variables (Backend/.env.example, Frontend/.env.example).
Auth
JWTs are signed with HS256 using two symmetric secrets (ACCESS_TOKEN, REFRESH_TOKEN). Email/password signup requires verifying a 6-digit OTP sent by email before a session is issued. Google OAuth is also supported. Refresh tokens rotate on use (single-use, revoked on refresh).
