Lean Bulk Tracker PWA

Lean Bulk Tracker is a compact personal PWA for tracking lean-bulk progress, top sets, bodyweight trends, and conservative calorie recommendations based on the values recorded so far. It runs without a paid backend or API key in local demo mode.

Project Overview

The app helps a lifter record daily bodyweight, training performance, and progress notes. It can run in a local demo mode from browser storage, or in Firebase mode with Google Authentication and Firestore. Recommendation logic is conservative: missing, weak, malformed, or inconsistent data never produces an actionable calorie change, and recommendations are never applied automatically.

Features

• Daily bodyweight and lean-bulk progress tracking.
• Top-set logging for strength progress.
• Versioned rolling calorie recommendations recalculated after every new entry.
• Visible data-quality score and adaptive TDEE range derived from recorded intake and weight trend.
• Lean-bulk targets of 0.05–0.25 % bodyweight per week with conservative 100/150 kcal adjustments.
• Editable energy profile with measured RMR, Cunningham, or Mifflin–St Jeor fallback.
• Protein and fat targets derived from bodyweight, with weekly calories distributed across training and rest days.
• Local demo mode backed by localStorage.
• Optional Firebase mode with Google Authentication, Firestore, offline persistence, and hosting.
• Automated tests for core data and recommendation behavior.
• PWA-oriented frontend built for a small personal workflow.

Tech Stack

• Frontend: React, TypeScript, Vite
• PWA: Vite PWA tooling and generated assets
• Data: local demo storage or Firebase Authentication and Firestore
• Testing: Vitest, Testing Library, Playwright, Firebase rules tests
• Tooling: pnpm, ESLint, GitHub Actions

Local Demo Mode

Copy .env.example to .env. The default VITE_USE_FIREBASE_EMULATORS=true enables local demo mode, which runs immediately from one localStorage record and does not require Firebase emulators or network access.

pnpm install
cp .env.example .env
pnpm dev

Useful commands:

pnpm lint
pnpm test
pnpm build

The committed .env.e2e file contains only fake/demo Firebase values for local end-to-end tests.

The tracker intentionally stores only total daily calories in its daily log. Daily macro ingestion and external nutrition-service synchronization are outside the current implementation.

Cloud / Firebase Mode

1. Create a Firebase project.
2. Enable Google Authentication and Firestore.
3. Copy the Firebase web app values into .env.
4. Set VITE_USE_FIREBASE_EMULATORS=false.
5. Deploy Firestore rules and hosting:

pnpm exec firebase deploy --only firestore:rules
pnpm build
pnpm exec firebase deploy --only hosting

All cloud data is stored below users/{uid} and Firestore persistence queues offline writes.

Testing

pnpm lint
pnpm test
pnpm build
pnpm test:rules
pnpm test:e2e

GitHub Actions installs dependencies, runs lint and unit tests, and builds the application. Firebase rules and Playwright tests are available locally when the required emulators/browsers are installed.

Security Notes and Limitations

This is a personal tracking tool, not a medical, nutrition, or production health platform. It should not be used as professional nutrition advice.

Do not commit real Firebase project credentials beyond public web-app config intended for client use. Keep private service account keys, production .env files, Firebase debug logs, database exports, and personal training data out of Git. If a real secret is ever committed, rotate it with the relevant provider because deleting it from the current tree does not remove it from Git history.

For reporting security concerns, see SECURITY.md.