Petra
Petra is a minimalist, privacy-focused personal-trainer web app that generates
and tracks gym workouts. It plans a weekly schedule around the days you pick,
progresses weights and reps from your logged performance, and runs through a
complete mesocycle including deload weeks — for people who want guided
workouts rather than building their own programs.
Design stance, throughout:
- Private by construction. Anonymous passkey-only accounts — no email, no
password, nothing to identify you (see
ADR 0001). Full data export
and account deletion built in.
- Mobile-first, JavaScript-optional. A server-rendered Go MPA with
progressive enhancement; every flow works with JS disabled
(see ADR 0002).
- Deliberately small. Go standard library focus, SQLite, vanilla JS, no
frontend framework, no build system for assets.
Repository layout
The module is organised as a small platform/product monorepo:
internal/platform/ shared infrastructure, reusable by any app in the module
sqlitekit/ declarative SQLite migrator + Config-based NewDatabase (RO/RW split, optimizer, healthcheck)
auth/ passkey/WebAuthn handler, Store interface, auth.SchemaSQL
obs/ observability: logging, errorrecorder, flightrecorder, pprofserver
envstruct/ struct-tag environment-variable config
contexthelpers/ request-scoped context helpers
testkit/ shared test helpers
internal/petra/ the fitness product (domain / repository / service / notification)
repository/ owns schema.sql, fixtures.sql, and embed.go (SchemaSQL / FixturesSQL)
cmd/petra/ the Petra web app (owns its ui/templates + ui/static)
cmd/example/ a minimal todo CRUD app that proves the shared platform plumbing
internal/platform/ is generic and must stay product-agnostic; internal/petra/
is everything specific to the workout product. The split is enforced at lint time:
depguard rules forbid internal/platform/ from importing
internal/petra or cmd/, and forbid cmd/example/ from importing
internal/petra (it may only build on the shared platform).
cmd/example/ deliberately copies the web middleware/render boilerplate
rather than importing a shared web kit — see
ADR 0005.
Quickstart
make # install dependencies, configure linting
make setup-git-hooks # optional: pre-push gate for developing straight on main
make dev # start the server on a free local port and open the browser
You can attach a debugger
to the running server.
Development
When a feature spans multiple layers, work outwards from the data model;
when a change is scoped to one layer, start there. Each layer has a README
next to the code:
internal/petra/repository/ —
schema (schema.sql), migrations, SQL persistenceinternal/petra/domain/ — pure domain
logic and aggregate methodsinternal/petra/service/ —
cross-aggregate orchestration and external integrationscmd/petra/ — HTTP handlers, routing, error
handling, testingcmd/petra/ui/templates/ — templates
and CSS, with the visual language in
cmd/petra/ui/design-system.md
The domain vocabulary — canonical terms and the aliases to avoid — lives in
CONTEXT.md. Templates and static assets load from the filesystem
at runtime, so the UI dev loop is edit → refresh, no rebuild.
make test # go test --race ./... (cached)
go test -v ./path/to/package -run TestName # single test
make ci # build + lint-fix + test; the pre-push gate
How work ships
Petra is trunk-based: once make ci passes, push to main. Every push runs
make ci-full (adds shuffled tests + govulncheck) plus make migratetest
(restores the latest production backup and migrates it) in GitHub Actions,
deploys to staging, and promotes to production only when staging is healthy.
make ci is the fast local gate and deliberately skips the shuffle,
govulncheck, and migratetest that server CI adds — so a green make ci
can still fail the deploy gate. Before a risky push (test-ordering changes,
schema.sql/migrations, or go.mod bumps) run make ci-full locally —
and make migratetest for schema changes — to catch it on your machine.
Opening a PR instead provisions a production-like per-PR review app — useful
for infrastructure-level changes. Details in
docs/operations.md.
Documentation index
Attribution
Petra logo made by Martin Yrjölä using Inkscape.
