Skip to content

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.

docs: architecture overview with diagrams, and an index of scripts/

Duarte Santos3ac0bcc4c4c4
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 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-&lt;user&gt;.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.md
new file mode 100644
index 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.mjs
index 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.