Pulse: Building on the sample

Pulse shares its shape with Savor and Wayline: the module layout, accounts and sign-in, cards and the payment provider, text messages, push notifications, the live channel and hosting the app in a browser. This chapter covers what a studio changes: households, a timetable that never oversells, a door pass, recurring billing, and the marketing that runs by itself.

The project is in scripts/pulse. Start the server on the development profile, which seeds the demo studio and its accounts and simulates the cards:

Then run the app in the simulator:

shared holds the data classes and the @RestClient interfaces both sides build from, so a change one side didn’t follow is a compile error. common is the app, for every platform. backend is the server, in packages by subject:

Roles are MEMBER, TRAINER, DESK and OWNER, in Roles. Every account is a member; the others are granted by an owner. The kiosk is a desk account on a tablet, so it needs no role of its own.

The rule that must never break is that a class isn’t booked past its capacity, however many people tap Book at once. Bookings leaves it to the database: the places taken are a column of the class, and the only statement that raises it does so on condition that it’s still below capacity. A booking whose statement changed no row joins the waitlist instead. Two requests for the last place both run that statement, and the database makes the second find the class full.

Everything else is checked first: the class is still to come, the person fits its age range on the day, the waiver is signed, and a membership covers it. A place given back promotes the first person on the waitlist, one promotion at a time per class, and a job settles finished classes, turning the absent into no-shows.

The same pattern takes a trainer’s offered shift: two trainers tapping Take together are told apart by one conditional statement.

A pass on a phone is a QR code reading pulse:<member id>:<code>, where the code is an HOTP (RFC 4226, SHA-256, eight digits) of the pass’s secret over the number of 30-second periods since the epoch. The phone and the server make the same com.codename1.security.Otp call, so the phone needs no signal. The server takes a code one period either side of now, for a phone whose clock is slightly off, and keeps every code it accepted until it could no longer be valid, so a screenshot shown twice is refused as a replay.

An NFC id is the other kind of pass, for a fob or wristband. It doesn’t change, so it’s as good as the thing it’s written on; replacing the pass’s secret replaces it too.

A check-in always answers, admitted or refused with a reason, and never fails for a member who simply isn’t allowed in. The kiosk turns that answer into a green or a red screen. Each check-in is also sent to staff over the live channel.

Billing charges in three steps and only the middle one talks to the processor: a transaction writes the invoice and claims it, the card is charged with no transaction open, and a second transaction records the result. The invoice id is the processor’s idempotency key, so a server that dies between the charge and the record charges the same invoice again on the next run and is answered the first charge, not a second one.

The processor is behind PaymentProvider: a customer, a card saved to it once as a token, and charges against that token with nobody present. The server keeps the token, a brand and four digits, never a card number. SimulatedPayments takes the test cards; StripePayments adds cards on Stripe’s hosted page. Another processor is one more implementation of the interface, chosen in Services.

The nudge job in engagement runs every 15 minutes and sends two kinds of message on its own: a class starting in 3 to 36 hours that’s under 60% full is offered to members who took that kind of class before, at most three per empty place; and a member who hasn’t been in for 14 days is told the studio misses them, at most every 21 days. Neither reaches a member who is away, one who turned promotions off, or one inside their quiet hours; those are left for a later run. Each message is its own transaction, checked again inside it, so two servers running the job send it once.

Campaigns are the owner’s: a message to those who took a kind of class, every active member, or the lapsed, counted as sent, opened, and booked.

A member’s watch sends heart rate readings during a class. HeartRates keeps the latest per member in memory only: a reading matters for a few seconds, and the workout, which is kept, arrives whole when it ends. The zone, one to five, is the reading’s share of 220 less the member’s age, in fifths from 50%. Readings go to the class’s trainer over the live channel.

The live channel carries four frames: a class’s places changing, one of an account’s bookings changing, a heart rate, and a check-in. The connections are those of one process; running more than one instance needs a channel between them, such as a database LISTEN/NOTIFY or a message broker, feeding the same methods.

backend/application.properties lists every setting. A deployment sets the database (DATABASE_URL), the issuer and signing key, the first owner (pulse.admin.email, pulse.admin.password), and the providers:

Unset, each provider is the development one on a development profile and the real one elsewhere. A real provider with missing settings is logged at start-up, naming them, and every call to it fails with the same message; nothing falls back to a development stand-in. Secrets go in the environment, in upper case with _ for each dot (PULSE_PAYMENTS_STRIPE_SECRET).

The server’s tests run on in-memory SQLite, which accepts any value in any column. sample-server-tests-on-database.sh runs them against PostgreSQL or MySQL, where the ORM checks every mapping against its migration. CI runs both, in .github/workflows/pulse.yml.

The sample is complete as a demonstration and stops where a studio’s legal and physical systems begin. A product needs at least: