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: diagrams as images so they show in the GitHub app, Buy Me a Coffee button back

Duarte Santos8329189d5234
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2bc616312..90e73720e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -60,14 +60,12 @@ it in review.
## What CI does with your pull request
-```mermaid
-flowchart LR
- pr["Pull request<br/>on GitHub"] --> actions["GitHub Actions<br/>frontend, api, MCP tests<br/>+ build and boot both api images"]
- actions --> review["Review and merge<br/>into main"]
- review --> mirror["Mirror workflow<br/>pushes to GitLab"]
- mirror --> gitlab["GitLab CI<br/>signed APK, multi-arch images,<br/>SBOMs, release"]
- gitlab --> ghcr["GHCR images<br/>on release"]
-```
+<p align="center">
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/ci-dark.png">
+ <img src="docs/diagrams/ci.png" alt="CI path: pull request on GitHub, GitHub Actions tests and image builds, review and merge into main, mirror workflow pushes to GitLab, GitLab CI builds the signed APK, images and SBOMs, GHCR images on release." width="280">
+</picture>
+</p>
A pull request runs the three test suites and builds and boots both api image targets. The APK and
the published images come from GitLab CI on the mirror, built from `main` after the merge. If your
diff --git a/README.md b/README.md
index 0cb56b675..c000c2b3b 100644
--- a/README.md
+++ b/README.md
@@ -183,30 +183,12 @@ Details and build instructions: [docs/MOBILE.md](docs/MOBILE.md).
## How it works
-```mermaid
-flowchart LR
- phone["Phone or laptop<br/>browser or PWA"]
-
- subgraph host["Your server"]
- direction LR
- media["media<br/>one-shot download"]
- web["web<br/>nginx: serves the app,<br/>proxies /api"]
- api["api<br/>Node + WebAuthn"]
- data[("./data<br/>JSON files")]
- mcp["MCP server<br/>optional, read-only"]
- end
-
- upstream["Exercise media<br/>upstream dataset"]
- ai["AI provider<br/>optional, your key"]
-
- phone -- HTTPS --> web
- upstream -. first start .-> media
- media -- shared volume --> web
- web -- /api --> api
- api --> data
- data -.-> mcp
- api -. coach only .-> ai
-```
+<p align="center">
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/architecture-dark.png">
+ <img src="docs/diagrams/architecture.png" alt="Architecture: the phone talks HTTPS to nginx (web), which serves the app and proxies /api to the Node api; the api stores JSON in ./data. A one-shot media service downloads exercise media on first start; the AI coach and MCP server are optional." width="520">
+</picture>
+</p>
- **`frontend/`** is React 19 and Vite (React Router, Zustand), built to static files inside Docker.
- **`api/`** is plain `node:http` with two dependencies: `@simplewebauthn/server` for passkeys and
@@ -225,22 +207,12 @@ Each profile's data is one document with a server revision. A device sends the r
saw along with its changes; if another device wrote in between, the server refuses and returns the
current document so the device can merge and retry.
-```mermaid
-sequenceDiagram
- participant P as Phone
- participant S as Server
- participant L as Laptop
-
- P->>S: save (baseRev 7)
- S-->>P: ok, rev 8
- L->>S: save (baseRev 7)
- S-->>L: 409 conflict + current doc (rev 8)
- Note over L: merge local changes<br/>into rev 8
- L->>S: save (baseRev 8)
- S-->>L: ok, rev 9
- P->>S: poll
- S-->>P: rev 9
-```
+<p align="center">
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/sync-dark.png">
+ <img src="docs/diagrams/sync.png" alt="Sync: a device saves with the revision it last saw; if another device wrote in between, the server answers 409 with the current document, the device merges and saves again." width="560">
+</picture>
+</p>
Nothing that hasn't reached the server is discarded on disconnect or sign-out, and the app shows a
banner whenever it's working offline.
@@ -280,17 +252,15 @@ A release roughly every two weeks, each small and themed. The full plan is in
[ROADMAP.md](ROADMAP.md), and the issues sit in the
[GitHub milestones](https://github.com/DuarteSantos8/openGym/milestones).
-```mermaid
-timeline
- title Next releases
- v1.3.10 (Oct 2026) : Session queue and rotation
- v1.3.11 (Nov 2026) : Programmes and phases
- v1.3.12–13 (Nov–Dec 2026) : Progression engine (AMRAP, %1RM, 5/3/1)
- v1.3.14 (Dec 2026) : Cardio, alternatives, groups
- v1.4.0 (Jan 2027) : Database storage (the one compatibility break)
- v1.4.1–3 (Jan–Feb 2027) : Search, OIDC login, trainer role
- v1.4.4–7 (Mar–Apr 2027) : iOS app, Health Connect, catalogue, skins
-```
+| Release | Planned | Theme |
+|---|---|---|
+| v1.3.10 | Oct 2026 | Session queue and rotation |
+| v1.3.11 | Nov 2026 | Programmes and phases |
+| v1.3.12–13 | Nov–Dec 2026 | Progression engine: AMRAP, %1RM, 5/3/1 |
+| v1.3.14 | Dec 2026 | Cardio, exercise alternatives, groups |
+| v1.4.0 | Jan 2027 | Database storage (the one compatibility break) |
+| v1.4.1–3 | Jan–Feb 2027 | Search, OIDC login, trainer role |
+| v1.4.4–7 | Mar–Apr 2027 | iOS app, Health Connect, catalogue, skins |
## Community
@@ -341,9 +311,12 @@ the same way.
## Support
openGym is free and stays free: AGPL, no paid tier, nothing held back for sponsors. If it replaced a
-paid tracker for you and you'd like to chip in, there's
-[Buy Me a Coffee](https://buymeacoffee.com/duartesantos). A star, a bug report or a pull request
-helps just as much.
+paid tracker for you and you'd like to chip in, there's a coffee button below. A star, a bug report
+or a pull request helps just as much.
+
+<a href="https://buymeacoffee.com/duartesantos" target="_blank">
+ <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="60" width="217">
+</a>
[![Star History Chart](https://api.star-history.com/svg?repos=duartesantos8/opengym&type=Date)](https://star-history.com/#DuarteSantos8/openGym&Date)
diff --git a/docs/diagrams/architecture-dark.png b/docs/diagrams/architecture-dark.png
new file mode 100644
index 000000000..765198e9a
Binary files /dev/null and b/docs/diagrams/architecture-dark.png differ
diff --git a/docs/diagrams/architecture.mmd b/docs/diagrams/architecture.mmd
new file mode 100644
index 000000000..431a2eb8c
--- /dev/null
+++ b/docs/diagrams/architecture.mmd
@@ -0,0 +1,22 @@
+flowchart TB
+ phone["Phone or laptop<br/>browser or PWA"]
+
+ subgraph host["Your server"]
+ direction TB
+ media["media<br/>one-shot download"]
+ web["web<br/>nginx: serves the app,<br/>proxies /api"]
+ api["api<br/>Node + WebAuthn"]
+ data[("./data<br/>JSON files")]
+ mcp["MCP server<br/>optional, read-only"]
+ end
+
+ upstream["Exercise media<br/>upstream dataset"]
+ ai["AI provider<br/>optional, your key"]
+
+ phone -- HTTPS --> web
+ upstream -. first start .-> media
+ media -- shared volume --> web
+ web -- /api --> api
+ api --> data
+ data -.-> mcp
+ api -. coach only .-> ai
diff --git a/docs/diagrams/architecture.png b/docs/diagrams/architecture.png
new file mode 100644
index 000000000..770a86f79
Binary files /dev/null and b/docs/diagrams/architecture.png differ
diff --git a/docs/diagrams/ci-dark.png b/docs/diagrams/ci-dark.png
new file mode 100644
index 000000000..77fce344b
Binary files /dev/null and b/docs/diagrams/ci-dark.png differ
diff --git a/docs/diagrams/ci.mmd b/docs/diagrams/ci.mmd
new file mode 100644
index 000000000..10b1e07dd
--- /dev/null
+++ b/docs/diagrams/ci.mmd
@@ -0,0 +1,6 @@
+flowchart TB
+ pr["Pull request<br/>on GitHub"] --> actions["GitHub Actions<br/>frontend, api, MCP tests<br/>+ build and boot both api images"]
+ actions --> review["Review and merge<br/>into main"]
+ review --> mirror["Mirror workflow<br/>pushes to GitLab"]
+ mirror --> gitlab["GitLab CI<br/>signed APK, multi-arch images,<br/>SBOMs, release"]
+ gitlab --> ghcr["GHCR images<br/>on release"]
diff --git a/docs/diagrams/ci.png b/docs/diagrams/ci.png
new file mode 100644
index 000000000..776bcfc3b
Binary files /dev/null and b/docs/diagrams/ci.png differ
diff --git a/docs/diagrams/render.sh b/docs/diagrams/render.sh
new file mode 100644
index 000000000..3da614a10
--- /dev/null
+++ b/docs/diagrams/render.sh
@@ -0,0 +1,11 @@
+#!/bin/sh
+# Renders every *.mmd here to a light and a dark PNG. GitHub's mobile app shows ```mermaid
+# blocks as plain code, so the README embeds these images instead; edit the .mmd, then run this.
+# sh docs/diagrams/render.sh (needs Node; mermaid-cli downloads its own Chrome)
+set -e
+cd "$(dirname "$0")"
+for f in *.mmd; do
+ n=${f%.mmd}
+ npx -y -p @mermaid-js/mermaid-cli@11 mmdc ${PUPPETEER_CONFIG:+-p "$PUPPETEER_CONFIG"} -i "$f" -o "$n.png" -t default -b white -s 2
+ npx -y -p @mermaid-js/mermaid-cli@11 mmdc ${PUPPETEER_CONFIG:+-p "$PUPPETEER_CONFIG"} -i "$f" -o "$n-dark.png" -t dark -b '#0d1117' -s 2
+done
diff --git a/docs/diagrams/sync-dark.png b/docs/diagrams/sync-dark.png
new file mode 100644
index 000000000..945159de7
Binary files /dev/null and b/docs/diagrams/sync-dark.png differ
diff --git a/docs/diagrams/sync.mmd b/docs/diagrams/sync.mmd
new file mode 100644
index 000000000..9825bd412
--- /dev/null
+++ b/docs/diagrams/sync.mmd
@@ -0,0 +1,14 @@
+sequenceDiagram
+ participant P as Phone
+ participant S as Server
+ participant L as Laptop
+
+ P->>S: save (baseRev 7)
+ S-->>P: ok, rev 8
+ L->>S: save (baseRev 7)
+ S-->>L: 409 conflict + current doc (rev 8)
+ Note over L: merge local changes<br/>into rev 8
+ L->>S: save (baseRev 8)
+ S-->>L: ok, rev 9
+ P->>S: poll
+ S-->>P: rev 9
diff --git a/docs/diagrams/sync.png b/docs/diagrams/sync.png
new file mode 100644
index 000000000..26d4e0fee
Binary files /dev/null and b/docs/diagrams/sync.png differ