Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. For people, the same map with diagrams is docs/ARCHITECTURE.md.
What this is
openGym is a self-hosted gym and body-weight tracker. Two containers (api + web) plus a
./data folder the user owns: no third-party account, no telemetry. Passkey (WebAuthn) login,
installable as a PWA, and Capacitor apps for Android and iPhone (with an Apple Watch app and
widgets) that work on their own or synced to a server. License: AGPL-3.0-or-later; the exercise
media are licensed separately (NOTICE.md).
Project layout
frontend/ React 19 + Vite app (src/views, src/components, src/store, src/lib, src/sheets.jsx).
android/ + ios/ are the Capacitor shells (docs/MOBILE.md); ios/ also holds the watch
app (Watch, WatchCore, WatchWidgets), the widgets and the animation-pack downloader.
api/ Backend: server.js (plain node:http) plus small testable modules beside it.
coach/ is the optional AI coach; coach/core/ is shared with the phone apps.
openapi.yaml documents every route.
web/ Multi-stage Dockerfile (builds frontend, adds catalogue/media, serves with nginx) and
nginx.conf.template (serves the app, proxies /api).
catalogue/ The exercise database: exercises/<id>.json, i18n/, licensed 180 px media/.
mcp/ Optional stdio MCP server: reads DATA_DIR, and its one write tool (log_workout)
saves through the api. Not in the Docker build.
scripts/ Build, CI and release helpers (scripts/README.md).
website/ opengym.ch, plain HTML/CSS/JS, deployed separately.
helm/, kubernetes/, contrib/nix/ Other ways to deploy.
docs/ Guides indexed in docs/README.md; docs/dev/ holds feature design notes.
Commands
# Local stack (api + web, prebuilt or built from source)
cp .env.example .env
docker compose up -d --build
# Frontend dev server (hot reload), proxies /api to :3000
cd frontend && npm install && npm run dev
# Tests (Node 22, the version CI and the Dockerfiles use)
cd frontend && npm test # vitest run, the whole suite
cd frontend && npx vitest run src/lib/progression.test.js # one file
cd frontend && npx vitest run -t "some test name" # one test by name
cd api && npm test # node --test
cd mcp && npm test
# Checks CI runs besides the suites (run `npm ci` in the repo root once, for js-yaml)
cd frontend && node scripts/check-locales.mjs && node scripts/check-source-strings.mjs --strict
node scripts/catalogue/build.mjs --check
node scripts/build-coach-assets.mjs --check
node scripts/build-api-docs.mjs --check
# Builds
cd frontend && npm run build
cd frontend && npm run build:mobile # VITE_MOBILE build + 180 px media from catalogue/media + cap sync
There is no linter/formatter config and no TypeScript; match the existing style by hand.
GitHub (github.com/DuarteSantos8/openGym) is the home of the project; .github/workflows/mirror.yml
pushes main and v* tags to the GitLab mirror (fast-forward only, never push or merge there).
Pull requests are gated by .github/workflows/test.yml; ios.yml compiles the iPhone app on a Mac
runner. Release packages (APK, Play bundle, App Store IPA) are built and signed on the release
machine, never in CI (see "Exercise media" below and docs/APP_STORES.md).
Architecture
Frontend (frontend/src)
store/useStore.js: a single Zustand store holding the client-side app state (S), persisted tolocalStorage(gym_state_v1) and debounce-pushed to the server when signed in (pushState, seelib/api.js). On the phones it is also mirrored to a file vialib/mobile.js(nativeSave), since WebView storage can be evicted.store/useUI.jsholds ephemeral UI state (modals, active sheet, rest timer) separately from persisted data.lib/: pure, framework-free helpers, each paired with a same-directory*.test.js. The domain logic lives here, most importantly:progression.js: the progression-rule engine (linear, Greyskull LP, double and triple progression, time-based). Rules implement a shared policy interface.onerm.js: estimated 1RM from logged sets (several formulas).finish-workout.js: reduces a completed session back into state (weights advance, PRs).recovery.js/recovery-view.js: the fatigue and muscle-recovery model.workout-model.js,supersetFlow.js: the in-session workout state machine.sync-merge.js: the field-by-field merge behind the 409 retry (see "Sync" below).exercises.js/exercises-data.js: the exercise library (5,632 catalogue exercises plus user-defined ones).exercises-data.js,instr/,exercise-names/andexercise-desc/are generated fromcatalogue/byscripts/catalogue/build.mjs; never edit them by hand.api.js: the only place that talks to the backend (fetchwrapper, session flows).- Native bridges:
mobile.js(theMOBILEflag, file persistence, notifications),channel.js(APK or store build),watch-sync.js,widgets.js,health-sync.js,anim-quality.js/anim-packs.js(animation sizes in the store apps). - CONTRIBUTING.md is explicit: anything that decides what you lift next, or reads a logged session back, is a pure helper here with a unit test beside it.
- Body measurements (
lib/measurements.js,views/Measurements.jsx): one check-in per day. Built-in circumferences and legacy custom fields store cm and follow the profile's cm/in display. Custom definitions may specifyunit: 'cm' | 'in' | '%' | 'kg' | 'lb' | 'none'; that display choice stays fixed when the profile switches kg/lb. Custom values store canonical cm, kg (to 0.001 kg so a tenth of a pound round-trips), percent (0 to 100) or a plain number. Each custom reading also carries its unit, preserving its meaning in backups without definitions. Once values exist, the unit selector permits cm/in or kg/lb conversions within the recorded type; a different type needs a new field. The body CSV names a custom column with its unit, "Muscle ratio (%)", and the importer reads those columns back (only from our own header). views/: one file per screen, routed byreact-router-domfromApp.jsx.sheets.jsx: the bottom sheets (exercise picker, exercise config, workout detail, plan import...). It is large; a new sheet can go intocomponents/as its own file.components/: shared UI (charts, modals, timers, media).locales/: one i18n pack per language, keyed by the English string (lib/i18n.js,i18n-core.js). A newt()string goes into every pack; pt-BR inherits from pt and has a fingerprint test (scripts/pt-br-inheritance-fingerprint.mjs).
API (api/server.js)
Plain node:http, no framework. Requests are dispatched through a routes object keyed by
'METHOD /path' (e.g. routes['GET /api/health']); add an endpoint by adding a key and its entry
in openapi.yaml (openapi-routes.test.js compares them). State is JSON under DATA_DIR:
db.json (users, credentials, push subscriptions, invites) and state-<uid>.json per user,
written temp-then-rename (durable.js). Custom-exercise photos and videos live in
DATA_DIR/uploads (media.js). Auth is WebAuthn passkeys (@simplewebauthn/server), an optional
password, and a signed session cookie (HMAC with DATA_DIR/secret); paired phones get the same
session as a bearer token. Optional pieces are gated by env vars: ADMIN_UIDS, INVITE_ONLY,
ALLOW_GUEST, PASSWORD_LOGIN, AUDIT_*. Web Push (web-push, VAPID keys in data/vapid.json)
drives rest-timer and reminder notifications.
Sync
Each profile is one document with a server revision. A device PUTs with the revision it last saw;
if another device wrote in between, the server answers 409 with the current document and the
client merges (lib/sync-merge.js) and retries. Every change carries its own stamp, per setting
and per field, so the newest edit of each wins and deletions stay deleted.
Code that exists twice on purpose
The API image cannot import the frontend, so some rules are hand-copied. Change both sides
together: lib/sync-merge.js and api/sync-stamps.js (parity test), lib/glyphs.js and
api/coach/core/glyphs.js (parity test), lib/nudge.js and api/nudge.js, lib/queue.js and
api/queue.js (mirrored test cases only, nothing compares the code). The other way round,
lib/coach-local.js imports api/coach/core/ directly so the phones run the same coach pipeline.
MCP server (mcp/src)
Stdio MCP bridge (@modelcontextprotocol/sdk) that reads one user's data straight from
DATA_DIR. state.js loads and derives the data, tools.js defines the read tools (zod schemas),
labels.js maps keys to readable labels, index.js wires it together. The one write tool,
log_workout (write-tools.js), never writes the file: it builds the workout with
frontend/src/lib/log-workout.js and saves it with PUT /api/data over a paired-session token
(api-client.js, scripts/pair.mjs), the way a device syncs. See mcp/README.md.
Passkeys and self-hosting constraints
WebAuthn passkeys are bound to an exact hostname (RP_ID) and need HTTPS (localhost excepted).
Read docs/SELF_HOSTING.md before touching auth, session or notification code; it documents the
env-var contract (RP_ID, ORIGIN, PORT, WEB_PORT, NGINX_PORT, BACKEND, SESSION_DAYS,
ADMIN_UIDS, INVITE_ONLY, ALLOW_GUEST, AUDIT_*, VAPID_SUBJECT) that real deployments
depend on.
Docker / deploy
docker-compose.yml has two services, api and web. The web image builds frontend/, copies
catalogue/media into it as /exercise-media/, and nginx proxies /api to the api (one origin,
which passkeys require). web/nginx.conf.template is rendered from env vars at start
(NGINX_PORT, BACKEND, PORT), so remapping works against prebuilt images.
Exercise media (licence, read before touching media)
The stills and animations are licensed from Gym visual, not AGPL. Only 180 px files may be in the
repository, CI, the web image, the demo or a self-hosted server (scripts/catalogue/check-media.mjs
enforces it). Larger sizes exist only inside the APK and store packages, built on the release
machine, or as Apple-hosted / Play asset packs. Never commit, upload or serve anything larger, and
never feed the media to an AI tool.
Guidelines from CONTRIBUTING.md worth knowing before changing code
- Dependency-light is a hard constraint. Frontend: React + Router + Zustand (plus Capacitor
plugins).
api/: three dependencies. New dependencies are a hard sell either side. - Don't commit
data/. Don't add or replace anything incatalogue/media/. - Training-logic changes (progression, 1RM, session read-back) need a unit test in
src/libbeside the code. - User-facing text: plain and human, no em dashes. CHANGELOG.md is written at release time.