tectonic plates

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 — 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:

• Postgres, migrated. app.rb connects at require time, so even the pure unit specs need a live database as soon as spec_helper loads the app.
• A real Firefox. spec/exercises_spec.rb, route_ownership_spec.rb, session_spec.rb, system_spec.rb and workouts_spec.rb drive a browser through Capybara and selenium, on a Puma server bound to port 9292. MOZ_HEADLESS=1 keeps windows from opening; CI sets it for the same reason.

The linters, both of which CI runs — these exact commands, not equivalents of them:

bundle exec rubocop

bundle exec rake lint:views

lint:views is a rake task rather than erb_lint with a glob because the glob had to be expanded by a shell, which reached only one directory deep and was refused outright in several sandboxed environments. The Rakefile builds the file list in Ruby, so the list is readable, recursive, and the same one in CI as on your machine.

The program engine

A program is a plan; workouts and sets are what it produces. Four tables hold the plan — programs, program_weeks, program_days, program_lifts — and generating a week turns them into ordinary workouts and sets rows with is_completed false. A planned session is not a separate kind of record: lifting a set as written only flips is_completed, while lifting it differently changes weight or reps and leaves planned_weight and planned_reps behind as the record of what was asked for.

• `programs` — the block: a name, a start_date, and two preferences the maths below reads: preferred_reps (the rep count main work should be expressed at) and is_ascending (whether working sets climb to the top weight or sit flat).
• `program_weeks` — a numbered week of the block, and is_deload. Dates are derived rather than stored: a week opens seven days after the one before it, counted from the block's start.
• `program_days` — a weekday, in Ruby's numbering where 1 is Monday, and a focus such as "Squat". A day is a weekday rather than a date, so the week it belongs to decides when it actually falls.
• `program_lifts` — an exercise at a position within the day, with sets, reps, is_barbell (whether it warms up off a bar and