FITR8 — AI fitness coach

Snap a photo of your meal → AI detects foods and portions → you confirm → calories and macros are logged against targets computed from your goal. A workout engine plans calorie-aware sessions, weekly check-ins adapt the plan, and an AI coach (a Claude agent with tools over your own data) answers questions and logs water, weigh-ins and meal drafts for you.

Stack: TypeScript everywhere · pnpm workspaces + Turborepo · NestJS 12 API (the only backend) · Next.js 16 PWA · Expo 57 app · PostgreSQL + Prisma 7 · Redis + BullMQ · S3-compatible storage · Claude (structured extraction + agent loop) · Vitest + Supertest · GitHub Actions · Docker.

             ┌──────────────┐ pages  ┌──────────────┐
  browser ──►│  apps/web    │ (SSR)  │              │──► PostgreSQL (Prisma)
     │       │  Next.js PWA │───────►│  apps/api    │──► Redis (jobs, locks)
     │       └──────────────┘        │  NestJS      │──► S3 / R2 / MinIO (photos)
     └──── /api/* (cookie) ─────────►│  the only    │──► Claude or OpenAI
  phone ──── /api/* (bearer) ───────►│  backend     │
             apps/mobile (Expo)      └──────────────┘  api.fitr8.com
                                        ▲ same image, APP_ROLE=worker
                                        └── queue consumers

Read docs/ARCHITECTURE.md before changing code — it defines module boundaries, layering, error handling, testing and how a module becomes its own microservice. UI follows docs/DESIGN.md.

Repository

apps/
  api/          NestJS service — HTTP API (main.ts) and queue worker (worker.ts), one image
    src/config      validated env (env.ts is the reference for every variable)
    src/common      auth guard + decorators, error filter, zod pipe, signing
    src/infra       Prisma, Redis, BullMQ JobQueue, S3 storage
    src/modules     bounded contexts: auth users plan meals foods water workouts progress coach ai health
    test/           e2e specs (real app + Postgres, mock AI)
  web/          Next.js PWA — UI only; calls the API directly (no API routes or proxy)
  mobile/       Expo app (iOS/Android/web) — UI only; EAS builds and OTA updates
packages/
  domain/       pure rules: nutrition, training engine, dates, formatting, barcode/label maths (+ tests)
  contracts/    zod request schemas, AI output schemas, coach stream events — shared by API and clients
  db/           Prisma schema, migrations, seed, generated client (API only)
  tsconfig/     shared compiler settings
docs/           ARCHITECTURE.md · DESIGN.md · DEPLOY.md
.claude/skills  fitr8-feature, fitr8-coach-tool — step-by-step workflows for future development

Getting started

Prereqs: Node 22 (nvm use), Docker, and for mobile Expo Go or an Android emulator. Full guide: docs/DEVELOPMENT.md (setup, daily commands, phone and emulator, Google sign-in locally, troubleshooting).

nvm use && corepack enable && pnpm install
pnpm bootstrap      # once: .env, Docker services, migrations, seed (safe to re-run)
pnpm start:all      # API + web + Android emulator + app, in one terminal
pnpm stop:all       # stop it all (data kept)

Locally nothing needs an account: "Sign in with email (dev)" on web and app, mock AI, MinIO for photos. Web runs at http://localhost:3000, the API at :4000.

Environments

APP_ENV says where the API runs; NODE_ENV only says how it's built. Templates: .env.example (local) and .env.production.example (deployed).

APP_ENV	Used by	Dev sign-in	Google	PUBLIC_URL	Reads .env
local	pnpm dev, the compose app profile	on	optional	http ok	yes
test	e2e tests (set automatically)	on	faked	http ok	no
staging, production	deployments	refused	required	https only	no

Unset, it follows NODE_ENV and fails safe: a production build without APP_ENV gets production rules.

Commands

Command	What it does
pnpm bootstrap	Set up or repair the local environment (idempotent)
pnpm start:all / stop:all	Start / stop the whole local stack incl. emulator and app
pnpm emulator	Create (once) and boot the "fitlens" Android emulator
pnpm dev / dev:api / dev:web / dev:mobile	Free the app's fixed ports, then run it in watch mode
pnpm check	Lint + typecheck + test for every workspace + repo scripts (= CI)
pnpm test	Unit + e2e tests (e2e needs Postgres; creates fitlens_test itself)
pnpm lint / typecheck / build	One task across the monorepo (Turborepo caches results)
pnpm format / format:check	Prettier
pnpm db:migrate -- --name <change>	Create + apply a migration after editing schema.prisma
pnpm db:seed / db:studio / db:deploy	Seed · Prisma Studio · apply migrations (prod)
pnpm infra:up / infra:down	Local Postgres, Redis, MinIO

Filter any task to one workspace: pnpm turbo run test --filter=@fitr8/api.

This is the beginning of the README. Read the rest at the original. Read the full README ↗