Listen · architecture profile
LoftwahFM
A music platform and the portfolio's shared radio capability. An Astro site and player on Cloudflare with D1, R2 media, KV sessions, Analytics Engine and four schedules.
How it is built.
LoftwahFM is both a product and a capability. Listeners get a catalogue, stations and a player. Games get a versioned radio client and station programmes. The same deployment owns media, catalogue rows, anonymous listening analytics and a protected admin surface.
- Stack
- Astro 7.1, React 18.3, TypeScript, Effect 3, Tailwind 4Evidence: package.json; astro.config.mjs
- Runtime
- Cloudflare Worker `loftwahfm` with static assets and four cron schedulesEvidence: wrangler.toml
- Storage
- D1 `loftwahfm`, R2 bucket `loftwahfm` for media, KV `SESSION`, Analytics Engine dataset `plays`Evidence: wrangler.toml
- Identity
- First-party email/password accounts with PBKDF2-SHA256 hashes and an `lfm_session` cookie; admin pages and /api/admin/* add Basic Auth with rate limiting. Listening does not require an account.Evidence: src/utils/dbAuth.mjs; src/pages/api/auth/login.ts; src/middleware.ts
- Delivery
- Cloudflare Worker `loftwahfm` with separate preview bindings; the custom domain is not declared in wrangler.toml, so its attachment is dashboard-managed and not provable from the repositoryEvidence: wrangler.toml; public request on 7 November 2026
- Integrations
- Stripe Checkout Sessions and a signed webhook for purchases; Resend email; ElevenLabs text-to-dialogue for radio production; publishes @loftwahfm/radio-client 1.2.0; receives listening-v1 events at /api/track; exposes /api/portfolio-analytics to WoodhouseEvidence: src/pages/checkout/[product].ts; src/pages/api/stripe-webhook.ts; src/services/radio/producer/RadioSynthesis.ts; docs/game-music-hand-off.md; packages/radio-client/src/telemetry.ts
The shape of the system.
- Site and playerAstro serves the public catalogue and player shell; React runs playback.Evidence: src/pages; src/player
- Station APIVersioned station programmes and game profiles are public JSON contracts, not hidden endpoints.Evidence: docs/radio-game-integration.md
- MediaAudio and artwork are served from the media bucket through the site.Evidence: src/pages/media/[...key].ts; wrangler.toml r2_buckets
- Radio clientA zero-dependency browser package pinned by exact version, with an integrity manifest beside it.Evidence: public/radio/v1/client/1.2.0/integrity.json
- AnalyticsAnonymous listening events use the listening-v1 contract. No persistent identity, polling or retry loop.Evidence: packages/radio-client/src/telemetry.ts
- CommerceStripe Checkout Sessions are created server-side and a signed webhook owns the purchase record. This is a real provider boundary, not a demo.Evidence: src/pages/checkout/[product].ts; src/pages/api/stripe-webhook.ts
A versioned client and an anonymous listening contract.
LoftwahFM has to be two things at once: a site a listener can use, and a dependency four games can pin without inheriting its release schedule. The architecture separates those by publishing a client and a set of JSON contracts rather than offering an SDK that floats.
The client is served from an immutable version directory with an integrity manifest. A game installs one exact archive, verifies the bytes and commits the lockfile entry. That is more friction than a floating script tag, and it buys the property that matters: a game release cannot change because someone deployed the radio service.
The telemetry contract follows the same rule. Games send a small listening-v1 payload with a per-play id, a source and a station; there is no persistent listener identity and no retry loop. The music service learns what was audible without turning a game session into an account.
Engineering decisions worth knowing.
- Version the client, not the integration
Games pin an exact archive URL and verify its hash. A new client version cannot silently change a shipped game, and rollback is changing one dependency back.
- The host keeps its audio graph
The client manages stations and queues. Volume, ducking, speech and dialogue stay with the game, because only the game knows what else is making noise.
- Listening measurement is anonymous and optional
The listening contract carries no account, only a per-play id and an origin. A game can send events without making listening a condition of play, and the site's own account system stays out of the radio client.
- Commerce has its own trust boundary
Checkout happens in Stripe, not in the Worker. The signed webhook is the record; a browser return URL is not treated as proof of payment.
What it connects to.
BubblesLoftwahFMradio client 1.2.0two-way
Bubbles pins @loftwahfm/radio-client 1.2.0 for station and queue state, and its host audio manager keeps effects, volume and mute. The same client sends anonymous listening-v1 events back to LoftwahFM, which makes this pair two-way without a shared account.
Evidence: Bubbles package.json dependency URL; src/app/music-transport.ts; LoftwahFM packages/radio-client/src/telemetry.ts
FighterLoftwahFMradio client 1.2.0two-way
Fighter pins the same client and the pressure-system station profile. The client sends the game's anonymous listening events back to LoftwahFM; Fighter keeps its own audio graph.
Evidence: Fighter package.json; LoftwahFM docs/radio-game-integration.md game profile table
SHOALSHOTLoftwahFMradio client 1.2.0two-way
SHOALSHOT pins the same client with the low-tide station. Its adapter supplies the game id and origin, and listening-v1 events go back to LoftwahFM so the telemetry distinguishes a real deployment from a test.
Evidence: SHOALSHOT package.json; src/platform/radio.ts; LoftwahFM docs/radio-game-integration.md
Protocol 11LoftwahFMradio client 1.2.0two-way
Protocol 11's jukebox pins the same client with the cartridge-club station. The client owns station selection and queue state and sends anonymous listening events back to LoftwahFM; the table keeps volume and effects.
Evidence: Protocol 11 package.json; src/client/jukebox.ts; LoftwahFM docs/radio-game-integration.md
WoodhouseLoftwahFMportfolio analytics
Woodhouse reads LoftwahFM's portfolio-analytics aggregate for listening context, and reads station manifests for the patch-bench exhibit. It does not read the underlying listening events.
Evidence: Woodhouse src/data/portfolio-analytics.ts; src/scripts/exhibits/patch-bench.ts; LoftwahFM API
Authoritative public sources
What this review does not know.
- Analytics Engine retention and the exact aggregation window were not re-derived from provider settings in this review.
- Stripe live-mode configuration, tax and refund handling were not exercised; this profile verifies the integration shape, not a completed purchase.
- No listening session was measured on a physical phone for this profile.
- The admin surface's operational history and the dashboard-managed custom domain were not audited.