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.
JavaScript apple-watchbodyweightdockerfitnessfitness-trackergymhealthiosmcpnodejspasskeysprogressive-web-applicationspwareactself-hostedself-hostingvitewebauthnweightliftingworkout-tracker
docs: architecture overview with diagrams, and an index of scripts/
Duarte Santos3ac0bcc4c4c4
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdnew file mode 100644index 000000000..ef411547b--- /dev/null+++ b/docs/ARCHITECTURE.md@@ -0,0 +1,185 @@+# How openGym fits together++A map of the code for people about to change it. For running an instance, read+[SELF_HOSTING.md](SELF_HOSTING.md); for the phone apps, [MOBILE.md](MOBILE.md) and+[APP_STORES.md](APP_STORES.md).++## The big picture++One React app runs everywhere: in a browser against your server, inside the Android and iPhone+apps (Capacitor), and as the browser-only demo. The server is small on purpose: plain `node:http`,+JSON files on disk, passkeys for sign-in.++```mermaid+flowchart LR+ subgraph Devices+ B[Browser / PWA]+ A[Android app<br/>APK or Google Play]+ I[iPhone app]+ W[Apple Watch]+ WG[Widgets and<br/>Live Activity]+ end++ subgraph Server["Your server (docker compose)"]+ N["web: nginx<br/>app files, 180 px media"]+ API["api: node:http<br/>server.js"]+ D[("./data<br/>db.json, state-<user>.json,<br/>uploads/, audit.log")]+ end++ B -- HTTPS, cookie --> N+ A -- HTTPS, bearer token --> N+ I -- HTTPS, bearer token --> N+ N -- /api --> API+ API --> D+ W <-- WatchConnectivity --> I+ I -- App Group snapshot --> WG++ MCP["mcp/ (optional)<br/>stdio, read-only"] -.reads.-> D+ AI["AI provider<br/>(optional Coach)"]+ API -.Coach jobs.-> AI+ I -.on-device Coach.-> AI+ A -.on-device Coach.-> AI+```++The phone apps also work with no server at all. Then the phone is the account and the state lives+in a file in the app's private storage (MOBILE.md explains the modes).++## The repository++| Path | What lives there |+|---|---|+| `frontend/src/` | The app. `App.jsx` routes to `views/` (one file per screen), `sheets.jsx` holds the bottom sheets, `components/` the shared UI, `store/` the two Zustand stores, `lib/` the logic |+| `frontend/src/lib/` | Pure helpers, each with a `*.test.js` beside it: progression, 1RM, recovery, sync merge, imports, media, the native bridges |+| `frontend/src/locales/` | One pack per language. The key is the English text, English itself has no pack |+| `frontend/src/{instr,exercise-names,exercise-desc}/`, `lib/exercises-data.js` | Generated from `catalogue/` by `scripts/catalogue/build.mjs`. Don't edit by hand |+| `frontend/android/`, `frontend/ios/` | The Capacitor shells and the native plugins (rest alarm, Health Connect, Apple Health, watch, widgets, animation packs) |+| `api/` | `server.js` (routes, sessions, storage), plus small modules split out so they can be tested alone: `media.js`, `sync-stamps.js`, `queue.js`, `nudge.js`, `rate-limit.js`, `durable.js`, `password.js`, `passkeys-store.js`, `device-link.js` |+| `api/coach/` | The optional AI Coach. `core/` has no server state and is shared with the phone apps |+| `web/` | The nginx image: builds the frontend, adds `catalogue/media`, proxies `/api` |+| `catalogue/` | The exercise database: one JSON per exercise, translations, the licensed 180 px media |+| `mcp/` | Optional MCP server, read-only, for AI clients on the same machine |+| `scripts/` | Build and release helpers, see [scripts/README.md](../scripts/README.md) |+| `website/` | opengym.ch, plain HTML |+| `helm/`, `kubernetes/`, `contrib/nix/` | Other ways to deploy |++## Frontend++```mermaid+flowchart TB+ V["views/ and sheets.jsx<br/>(screens and bottom sheets)"] --> S["store/useStore.js<br/>persisted state S"]+ V --> U["store/useUI.js<br/>modals, toasts, timers"]+ V --> L["lib/ (pure logic)"]+ S --> L+ S -- "debounced push, pull, merge" --> API["lib/api.js<br/>the only fetch wrapper"]+ S -- "file mirror" --> M["lib/mobile.js<br/>Capacitor Filesystem"]+ L -. "native bridges" .-> P["Capacitor plugins<br/>android/ and ios/"]+```++- **State.** `useStore.js` holds everything a profile owns (`S`): routines, workouts, weigh-ins,+ settings. It is saved to `localStorage`, mirrored to a file on the phones (WebView storage can be+ evicted), and pushed to the server when signed in. `useUI.js` is everything that should not+ survive a reload.+- **Logic in `lib/`.** Anything that decides what you lift next, or reads a logged session back, is+ a pure function with a test beside it. Views stay thin.+- **Platform switches.** `lib/mobile.js` (`MOBILE`), `lib/channel.js` (APK or store build) and the+ `VITE_DEMO` flag for the demo. Native code is only reached through Capacitor plugins.++## Sync++Each profile is one JSON document with a server revision. A device sends the revision it last+saw; if someone else wrote in between, the server answers 409 with the current document, and the+device merges and tries again.++```mermaid+sequenceDiagram+ participant P as Phone+ participant S as Server+ participant L as Laptop+ P->>S: PUT /api/data (baseRev 7)+ S-->>P: 200, rev 8+ L->>S: PUT /api/data (baseRev 7)+ S-->>L: 409 + document at rev 8+ L->>L: merge field by field (lib/sync-merge.js)+ L->>S: PUT /api/data (baseRev 8)+ S-->>L: 200, rev 9+```++Every change carries its own timestamp, down to one setting or one field of a routine, so the merge+keeps the newest edit of each and a deletion stays deleted. The server applies the same rules for+writers that don't stamp (older apps, API scripts) in `api/sync-stamps.js`.++## Code that exists twice on purpose++The API image only contains `api/`, so a few rules are hand-copied from the frontend instead of+imported. When you change one side, change the other in the same pull request:++| Frontend | Server | Held together by |+|---|---|---|+| `lib/sync-merge.js` | `api/sync-stamps.js` | `lib/sync-stamps-parity.test.js` runs both on the same cases |+| `lib/glyphs.js` | `api/coach/core/glyphs.js` | `lib/coach-parity.test.js` |+| `lib/nudge.js` | `api/nudge.js` | mirrored cases in `lib/nudge.test.js` and `api/test/nudge.test.js` |+| `lib/queue.js` | `api/queue.js` | mirrored cases in `lib/queue.test.js` and `api/test/queue.test.js` |++The last two have no test that compares the code itself, so a change on one side only is not+caught automatically.++The Coach goes the other way: `frontend/src/lib/coach-local.js` imports `api/coach/core/` directly,+so the phone apps run the same prompts and validation as the server. That is why the web image+copies `api/coach/core/` into its build stage.++## Server++`api/server.js` is a single `node:http` server. Routes are keys of one object+(`routes['GET /api/health']`), matched on method and path. Storage is two kinds of JSON file under+`DATA_DIR`: `db.json` for users, passkeys, invites and push subscriptions,+and one `state-<uid>.json` per profile. Every write goes to a temp file first and is renamed over+the old one (`durable.js`), so a crash never leaves half a file.++Sign-in is a passkey (`@simplewebauthn/server`), optionally a password, plus a signed session+cookie. Phones get the same signed session as a bearer token, made by pairing with a one-time code+(`device-link.js`). Every route is listed in `api/openapi.yaml`, and `openapi-routes.test.js` fails+when the two disagree.++## Exercise media++The animations are licensed from Gym visual and not covered by the AGPL (NOTICE.md). The licence+decides where each size may go, and the build follows it:++```mermaid+flowchart LR+ C["catalogue/media<br/>180 px stills + clips"] --> WEB["web image, demo, self-hosted"]+ C --> CI["CI builds (iOS simulator, tests)"]+ Q["private quality folders<br/>240 to 1080 px<br/>(release machine only)"] --> APK["APK: built in"]+ Q --> AAB["Google Play: built in + Play asset packs"]+ Q --> IPA["App Store: built in + Apple-hosted packs"]+```++Nothing larger than 180 px is ever committed, served by a server, or uploaded to CI. The store+packages are put together and signed on the release machine (`scripts/android/build-release.sh`,+`scripts/ios/finish-ipa.sh`).++## Native extras (iPhone)++- **Apple Watch** (`ios/App/Watch`, logic in the `WatchCore` Swift package with its own tests):+ the phone sends a snapshot of the running workout (`lib/watch-sync.js` →+ `WatchBridgePlugin.swift`), the watch runs the session on its own, and sends back small events+ ("set done") that the phone applies through the workout screen's own actions.+- **Widgets and the Live Activity** (`ios/App/OpenGymWidgets`): the page writes a small snapshot to+ the App Group (`lib/widgets.js` → `WidgetBridgePlugin.swift`), the widgets read it.+- **Animation packs** (`ios/App/AnimationPacksDownloader`, `AnimationPacksPlugin.swift`): the+ sharper animation sizes as Apple-hosted Background Assets.++## CI and releases++```mermaid+flowchart LR+ PR[Pull request] --> T["GitHub Actions<br/>test.yml, catalogue.yml, ios.yml"]+ T --> MAIN[main]+ MAIN --> MIR["mirror.yml"] --> GL["GitLab mirror CI<br/>tests, image checks, scans, SBOMs"]+ MAIN --> PG["pages.yml<br/>demo"]+ REL[Published release] --> DP["docker-publish.yml<br/>GHCR images"]+ RM["Release machine"] --> ART["APK, AAB, IPA<br/>signed locally"]+```++GitHub is the home of the project. GitLab is a fast-forward-only mirror. Release steps are in+[APP_STORES.md](APP_STORES.md) and the [changelog](../CHANGELOG.md) format is described at its top.diff --git a/scripts/README.md b/scripts/README.mdnew file mode 100644index 000000000..e04cec12c--- /dev/null+++ b/scripts/README.md@@ -0,0 +1,54 @@+# scripts/++Build and release helpers. Each script explains itself at the top; this page says which one you+want. Run them from the repository root with Node 22 unless noted.++## Run by CI (keep them working)++| Script | What it does |+|---|---|+| `build-api-docs.mjs` | `website/api.html` from `api/openapi.yaml`. `--check` fails when it is stale |+| `build-coach-assets.mjs` | `api/coach/core/library-data.js` and `prompts.js`, the Coach's copy of the catalogue and its prompts. `--check` in CI |+| `build-coach-library.mjs` | Old name of the one above, only forwards to it |+| `catalogue/validate.mjs` | Checks every entry in `catalogue/` (fields, words, ids) |+| `catalogue/build.mjs` | Builds the app's exercise files from `catalogue/`. `--check` fails when they are out of date |+| `catalogue/check-media.mjs` | Fails on any media file over 180 px (the licence) or in a format the app can't show |+| `catalogue/stage-media.mjs` | Copies the stills and animations next to a built app (`npm run build:mobile`, the demo) |+| `ci/fork-mr-pipelines.py` | GitLab mirror only: starts pipelines for merge requests from forks |++## Used when you change something++| Script | When |+|---|---|+| `build-hevy-id-map.mjs` | Regenerates `frontend/src/lib/hevy-id-map.js` after Hevy adds templates (needs a Hevy API key) |+| `de-name-rules.mjs` | The German exercise-name rules. `frontend/src/lib/exercise-names.test.js` holds every German name to them |+| `catalogue/migration-check.mjs` | Before a catalogue change ships: compares old and new catalogue on copies of real profiles |++Frontend-only helpers (locale checks, bundle size, the service worker stamp) live in+`frontend/scripts/`, and the API's in `api/scripts/`.++## Release machine only++These touch the licensed full-size animations, which never go into the repository or CI. They+run on the maintainer's machine against the private media archive.++| Script | What it does |+|---|---|+| `android/build-release.sh` | Builds and signs the APK and the Google Play bundle |+| `android/make-asset-packs.mjs` | Adds the Play asset packs to the Android project for one build, and removes them again |+| `ios/finish-ipa.sh` | Puts the app's animations into the unsigned IPA from CI and signs it for the App Store |+| `media/make-pack-manifests.mjs` | Plans the Apple-hosted animation packs from file names alone |+| `media/build-media.py` | Turns the Gym visual pack into the files openGym ships (ffmpeg only) |+| `media/build-app-webp.py` | The phone apps' animated WebP animations |++## Kept for the record++One-off scripts from building the v1.4.0 exercise database. Nothing calls them any more; they show+how `catalogue/` was put together.++| Script | What it did |+|---|---|+| `catalogue/import-legacy.mjs` | Wrote `catalogue/` from the exercise data up to v1.3.x |+| `catalogue/drafts-from-pack.py` | Listed the Gym visual exercises the catalogue did not have yet |+| `catalogue/import-drafts.mjs` | Folded those drafts into `catalogue/` |+| `catalogue/import-names.mjs` | Folded the name translations into `catalogue/i18n/` |diff --git a/scripts/de-name-rules.mjs b/scripts/de-name-rules.mjsindex e9ce6d58e..291f4da78 100644--- a/scripts/de-name-rules.mjs+++ b/scripts/de-name-rules.mjs@@ -1,7 +1,7 @@-// The German exercise-name rules, in one place. Imported by translate-de-exercise-names.mjs,-// which checks every batch during translation and sends violations back to the model as a-// correction, and by frontend/src/lib/exercise-names.test.js, which fails the build. The two-// callers share this definition deliberately: inline copies are how a rule drifts unseen.+// The German exercise-name rules, in one place. frontend/src/lib/exercise-names.test.js imports+// them and fails the build on a name that breaks one. (The translation script that also checked+// every batch against them went with v1.4.0; the rules stay here so any future tool shares this+// one definition instead of an inline copy that drifts unseen.)//// Every `fix` quotes the offending word. A generic instruction ("use the German term") is// ignored by a small model often enough to stall a stage; naming the text is what lands.