Tectonic

Tectonic is a barbell strength-training tracker. An account logs workouts; a workout holds sets of an exercise at a weight and a rep count, in the order they are lifted. All weights are integer pounds.

What makes it more than a list is that a session is written before it is lifted. A program expands into ordinary set rows — warmup ramp included, every weight rounded to something a bar can actually be loaded to — so lifting is tapping through a list that already knows what comes next, and each row keeps the prescription beside what was actually done. An MCP endpoint exposes the same data to an LLM as a connector, which is the second half of this file.

The stack is Roda and Sequel on Postgres, with Rodauth for accounts and rodauth-oauth for the OAuth 2.1 authorization server the MCP endpoint authenticates against. Views are ERB with Tailwind from a CDN, and htmx for the parts of the session screen that have to change without a page load. It deploys to Render.

What it does

• Session view (/workouts/:id/session) — the gym-floor screen, as distinct from /workouts/:id, which is the record of one. A progress bar across the top, sets grouped by lift with warmups dimmed, the per-side plate breakdown under each weight ("per side 1×25 1×10"), and a Done button per set that toggles, so a mis-tap is undone by tapping again. A set lifted differently is entered inline and the row turns amber rather than lime, because done-as-written and done-differently have to read differently. The whole session gets an RPE rating, with a bar-speed guide for choosing one.
• Exercises — 54 built-in barbell movements shared by every account, plus any you add yourself. A built-in exercise is visible to everyone but the sets shown under it are only ever your own.
• Workouts — list, record view, reschedule, delete.
• Programs — the engine below. Authored in Ruby and run from rake; there is no UI for editing one yet.
• Accounts — Rodauth login, account creation, logout, remember-me.
• MCP — audited, per-account tools over an OAuth 2.1-authenticated endpoint at /mcp.

Getting started

You need Ruby at the version in .ruby-version (the Gemfile reads the same file, so the two cannot drift), a local Postgres, and — only for the browser specs — Firefox with geckodriver.

bundle install
npm install        # only for the stylesheet; see below

Environment

dotenv loads .env when the app is required, and .env-example is a file to copy: cp .env-example .env gives a working development setup, pointed at the tectonic_development database rake db:create makes below. The keys that are secrets in a deployment are commented out there rather than left blank, each with the command that generates it, because a blank is worse than an absence here — dotenv sets the name to the empty string, every fallback in this project tests for nil, and an empty DATABASE_URL reaches Sequel.connect and raises rather than falling back to a default.

The MCP and OAuth variables are all optional in development and are documented in the table further down.

Database

bundle exec rake db:create          # createuser tectonic, then the development and test databases
bundle exec rake db:migrate         # applies migrate/001_schema.rb against DATABASE_URL
bundle exec rake library:exercises  # loads the 54 built-in movements, idempotent on name

db:create shells out to createuser -U postgres and createdb -U postgres -O tectonic, so it assumes a superuser role named postgres and gives the databases to a tectonic role. If your Postgres has neither, createdb tectonic_development by hand and go straight to db:migrate, which only needs DATABASE_URL to point somewhere it can connect.

The schema is one squashed baseline. db:migrate stamps a database that already carries the tables rather than trying to rebuild or roll it back, so an existing database from before the squash adopts the baseline instead of breaking on it.

Running it

bundle exec rackup config.ru        # http://localhost:9292

config.ru mounts two apps side by side under Rack::URLMap: the MCP endpoint at /mcp, which has its own bearer-token auth and never touches Roda's sessions or CSRF, and the Roda app at everything else. / redirects to /welcome until you are logged in, so start by signing up at /create-account.

The stylesheet

npm run build:css   # assets/css/app.css -> assets/css/styles.css

assets/css/styles.css is compiled from assets/css/app.css and committed, so nothing but a stylesheet edit needs Node at all — bundle install and a database are enough to run the app and the suite.

Rebuild it after adding a Tailwind class that was not already in use. CI rebuilds and fails on a difference, so a stale file is caught before it ships rather than after: a purged class breaks nothing anywhere except on the page it was meant to style, in production, silently.

tailwind.config.js scans app.rb and lib/**/*.rb as well as the templates, because button_style, rpe_style, row_style and the calendar's STYLES table build class names in Ruby and appear in no template.

It used to be <script src="https://cdn.tailwindcss.com"> — the Play CDN, which compiles in the browser. That meant no CSS at all with JavaScript off, and a third party on every page including the consent screen.

Running the tests

bundle exec rake test                            # the whole suite
bundle exec ruby -Ispec spec/set_scheme_spec.rb  # one file

Neither variable has to be passed in. spec_helper sets RACK_ENV and then names the database itself — TEST_DATABASE_URL when a run wants one of its own, and postgres:///tectonic_test otherwise — whatever the shell, a .env or the Rakefile had already chosen. That matters more than it looks: spec_helper empties every table after every test, so a suite pointed at your development database would not seed it, it would clear it. The built-in exercise library is the one thing kept, because a deployed database holds it before anybody signs up. rake 'db:reset[name]' still rebuilds a database whose schema has gone wrong, but a run no longer leaves rows behind for it to clear away.

Two prerequisites, neither obvious from the failure you get without them: