Home workouts built with TanStack Start, React, and Go/Echo. Choose 30–120 minutes and one of five levels. New plans need only floor space and a wall.
The landing page is /; the signed-in app is /app. Signup leads through a welcome, default level choice, and workout setup. Plans save to Postgres. You can browse, follow, and print them. After you work out, mark the plan complete. The plan then shows when you last completed it, and the dashboard shows completed workouts, active days, four weeks of activity, and milestones. Light, dark, and system themes are available. Billing and cloud media storage are deferred.
Prerequisites: Docker (running), Node.js 26.10.0 (nvm install), Bun 1.4.2, Python 3 for repository checks, and Go with automatic toolchain downloads enabled. Make targets use nvm's Node 26.10.0 by themselves, so you do not need nvm use. The backend and Go linter use Go 1.27.1 without changing your global Go installation.
Install the Clerk CLI and sign in once per machine:
npm install -g clerk
clerk auth loginThen start the app in any checkout or worktree:
make devOpen Endorphins. The Go API listens on 127.0.0.1:8088. The frontend proxies /api to Go, keeping browser requests on the same origin. The exercise files are loaded and validated when Go starts.
make dev installs dependencies and pulls Clerk development keys into ignored frontend/.env.local if that file is missing. Then it starts Postgres on loopback port 5548, applies migrations, and starts both servers. In the Claude desktop app, start endorphins from the Browser pane's Dev servers menu. It runs make dev from .claude/launch.json.
Get keys with clerk env pull only. clerk init rewrites frontend/app/start.ts.
The dev server shows TanStack Devtools at the bottom right, with Router and Query panels; release builds leave them out. Sentry error reporting is optional and off until a DSN is set; see Configure Sentry.
The Make targets use Bun’s CLI to load .env.example defaults and frontend/.env.local, then run Go directly. Exported variables take precedence.
For separate terminals, run make db-up, make migrate, then make api and make web. Export DATABASE_URL to use a different database. Set APP_ORIGINS to comma-separated frontend origins when changing the frontend address; if changing API_ADDRESS, update API_ORIGIN too. make db-stop preserves your local database volume.
Select Get started to create your first app account. Then run make seed to give every local account with no saved plans five weeks of plans, completions and activity. make seed SUBJECT=user_... seeds one Clerk user. The seed refuses non-pk_test_ Clerk keys and never adds to an account that has plans. Signing in to the Clerk CLI only authenticates the CLI; it does not sign you into Endorphins. Your account menu provides profile and sign-out controls, and Saved workouts reopens saved plans. After working out, select Mark complete at the end of the plan or the exercise view. A completed plan shows its last completion date and offers Start again; finishing it again counts as another workout. Use New workout for a different plan.
The checked-in Codex environment installs Go/Bun dependencies and Playwright Chromium when Codex sets up a new worktree. Its toolbar actions call the root Make targets: Run app, API, Frontend, Start Postgres, Migrate, Seed, Stop Postgres, Check, and E2E.
Actions that need Node use npx to select the version in .nvmrc. This caches the project version without changing your global Node default. npm/npx, Bun, Go, Python 3, and Docker must already be installed; Docker must run for the app and database tests.
Sign in to the Clerk CLI once, as shown above. Run app pulls keys into ignored frontend/.env.local in each new checkout; setup does not copy credentials or start services. Run app uses ports 3100, 8088, and 5548, so run one local development stack at a time. E2E uses disposable services on random ports and needs no Clerk credentials.
make check # formatting, boundaries, lint, React Doctor, race and frontend tests,
# API types, TypeScript, and both production builds
make browsers # install pinned Chromium once
make e2e # hermetic desktop/mobile browser tests on dynamic ports
make e2e-clerk # real Clerk sign-up and sign-in against make dev
# (add URL=https://... to target a preview)
make seed # five weeks of plans and completions for local accounts
make migration-check # upgrade a database seeded by origin/master to this checkout
make format # apply Go and frontend formatting
cd frontend && bun run doctor # full React Doctor scan; errors and warnings failmake test runs real Postgres tests and needs Docker. make e2e runs desktop/mobile journeys against disposable Postgres, Go API, and Bun frontend containers. Only the external Clerk UI/session adapter is replaced. make e2e-clerk covers real Clerk sign-up and sessions with @clerk/testing; webhook delivery still needs a separate check. See browser tests and artifacts. make smoke is an alias for make e2e. Do not run a frontend build while E2E images are building; both use frontend/build.
make migration-check starts a throwaway Postgres container. It migrates and seeds it with origin/master (or BASE=<ref>), then migrates it with this checkout, reads every account back and seeds a new one. Last, it compares the upgraded columns and indexes with a fresh migration of this checkout. It catches schema changes that break or drift only in a populated database: a new NOT NULL column without a default, a column tightened to NOT NULL, a removed field whose column remains, or a changed index. Run it after you change repository models; CI runs it on pull requests.
Each pull request also gets a Railway preview environment with its own seeded Postgres, and master deploys to a persistent Railway production. Both are reachable only over Tailscale. See Railway production and previews.
For a production-mode local preview, run these in separate terminals after make check:
make api
cd frontend && bun run startThe second command also serves on port 3100. Run make db-up and make migrate first. Run the API from backend/, or set EXERCISE_DIR to the catalogue’s absolute path. Deployment must include the exercises/ directory beside the backend; it is not embedded in the binary.
The Bun server compresses built JavaScript and CSS once at startup and serves cached gzip variants to clients that accept them. Responses include Vary: Accept-Encoding; clients can still request uncompressed assets. Restart the production server after rebuilding assets.
- Paper design system and desktop/mobile studies
- Design decisions and Mobbin references
- Accounts, sessions, and workout data model
- Architecture
- Engineering practices
- OpenAPI contract
- Deployment runbook
- Railway production and PR previews, private over Tailscale
- History: dated reviews, research, and decision records
Open /design-system in development to inspect the shared controls. /app/account provides an authenticated JSON data export.
Go uses explicit constructor injection and layers for domains, services, repositories, handlers, and server setup. services/workout owns generation, services/library owns saved workouts, and services/account maps Clerk identities to internal users. Concrete stores live under repositories/catalogue and repositories/postgres. Frontend routes compose pages and components independently of the backend packages.
The generator retains the script’s difficulty-based time estimates, three body-area blocks, and repetition/interval prescriptions. It fixes the level range, duration overshoot, duplicate choices, and lost warm-up time. The Go catalogue filters out weights, chair dips, and handstands at levels 1–2. It leaves the original exercise files intact. Times remain estimates; exercise demonstrations are not included.
The original script, its sample PDFs, and its Make targets are in legacy/. It reads the shared exercises/ catalogue at the repository root. The Python path is separate from the web app:
cd legacy
python3 -m pip install -r requirements.txt
mkdir -p workouts
python3 main.py 45 2 0This creates a workout PDF in legacy/workouts/ using the original algorithm. In legacy/, make workout also runs the original repository update script before generation.