Welcome to the Jose Madrid Salsa developer docs — explore features, APIs, and deployment guides.
Jose Madrid SalsaJMS Docs

Office Display (TRMNL)

A TRMNL e-ink screen in the office that rotates live sales, inbox, fundraiser, show, review and alert screens rendered by the storefront.

Office Display (TRMNL)

A TRMNL 7.5" e-ink display (the Seeed "OG DIY Kit": XIAO ESP32-S3, 800×480 black-and-white panel) sits in the office and shows the business at a glance. It talks to the storefront directly using TRMNL's Bring Your Own Server protocol, so the data never passes through TRMNL's cloud and no TRMNL plugin is involved.

How it works

StepEndpointWhat happens
Once, after Wi-Fi setupGET /api/trmnl/api/setupAn allow-listed device (by MAC) receives its access token.
Every wakeGET /api/trmnl/api/displayThe server picks the next screen and returns a signed image URL and refresh_rate.
Right afterGET /api/trmnl/screens/:screenThe screen is rendered live to a 1-bit 800×480 PNG (next/og + sharp).
On device errorsPOST /api/trmnl/api/logFirmware errors are written to the function log.

Code lives in apps/storefront/lib/trmnl/ (device.ts access, playlist.ts rotation, data.ts loaders, dev.ts development sources and the brief, screens.tsx layouts, graphics.tsx logo, star ratings and charts, logo.ts the pre-thresholded logo, render.tsx rasterising).

Screens

ScreenShowsSource
todaySales and orders since midnight Eastern, orders to ship, visitors, unread chats and emails, failed payments, latest orders with a sales-channel icon, and a chart of the last seven days' sales (today drawn as an outline while it fills)Orders, operational queues, GA4, Gmail
inboxUnread mail in the connected Gmail inbox (mike@josemadridsalsa.com) and website chats waiting on a replyGmail API (live), Conversation/Message
fundraisingActive fundraisers: revenue against goal, orders, days leftFundraiser
showsBooked shows in the next 30 daysFeaturedEvent (synced from Google Calendar)
reviews30-day average rating and count, reviews awaiting approval, the Google rating and newest Google review, latest product reviewsReview, SiteReview, Google Places (GOOGLE_PLACES_API_KEY, GOOGLE_PLACE_ID)
socialScheduled posts, posts and engagement (likes, comments, shares) over 7 days, the next two scheduled posts, the top posts and the newest failed publish. Direct messages need Meta's messaging approval and are not shown.SocialMediaPost, SocialPostPublish
trafficVisitors today and over 7 days, add-to-carts, top traffic sources and countriesGA4 (the Analytics integration)
shopsPer sales channel: live, pending and problem listings and the last sync; the newest listing errorsShopListing
devProduction deploy state, CI on main (the CI result of the newest merged pull request into main, since CI runs on pull requests, not on main), open pull requests, unresolved Sentry errors in the last 24 hours, the last two deploys, the top two errors and the newest pull requestVercel, GitHub and Sentry APIs (live)
briefA two-sentence summary of what shipped and up to three suggested next steps, written by Claude once per business daydev data + Anthropic
alertsUp to three, most serious first: a failed latest production deploy, critical operator notifications nobody has read, website messages and contact-form submissions from the last two hours nobody has read, and unread mail Gmail marks important in Primary from the last hour. Each clears once read.Vercel, Notification, Conversation, Gmail

The display rotates one screen per wake (every 2 minutes by default, so a full cycle of ten screens takes 20 minutes; lower TRMNL_REFRESH_SECONDS for a faster cycle). Contact form submissions arrive as website chats, so they show on inbox. While a critical alert is unread, every other wake shows the alerts screen; it clears as soon as any operator reads that notification in the admin. Between 10 pm and 6 am Eastern the display wakes every 30 minutes and shows today (or alerts).

Daily brief

The trmnl-brief cron (/api/cron/trmnl-brief, 10:30 UTC, before the office opens) asks Claude for the day's brief and caches it for the business day, so the display never waits on it. A failed generation is not cached: the next render of brief tries again, and until then the screen reads "No brief yet today". Claude sees only deploy, pull request, CI and error titles, never orders or customer records.

Setup

  1. Set TRMNL_DEVICE_MACS and TRMNL_API_KEY in Vercel (see Environment variables). Generate the key with openssl rand -hex 32. The MAC address is printed on the device's setup screen.
  2. Set TRMNL_SETUP_OPEN=true and redeploy. A MAC address is not secret, so setup hands out the access token only while this is set.
  3. Flash the TRMNL firmware onto the kit if it did not ship with it (TRMNL's web flasher).
  4. Hold the button to enter Wi-Fi setup, join the TRMNL network, choose your Wi-Fi, and under Custom server enter https://www.josemadridsalsa.com/api/trmnl.
  5. The device registers, then shows the first screen within a refresh.
  6. Remove TRMNL_SETUP_OPEN and redeploy. The registered device keeps working; setup refuses everyone until you open it again.
  7. Optional: set TRMNL_VERCEL_TOKEN, TRMNL_GITHUB_TOKEN and TRMNL_SENTRY_TOKEN for the dev and brief screens.
  8. The display server at display.josemadridsalsa.com has no copies of those tokens: it reads the finished development data and brief from GET /api/trmnl/dev. Set TRMNL_DEV_FEED_SECRET to the same value on both Vercel projects; while it is unset here, the route refuses every call.

To preview a screen in the browser, sign in with the api_keys:manage permission (the one that reads the owner's mailbox; admins and the developer by default) and open /api/trmnl/screens/today (or any screen name above). Other staff cannot preview, since the screens show the owner's email, revenue and analytics.

To revoke a device, change TRMNL_API_KEY: every device must then register again.

Changing it

  • A new screen: add a loader in data.ts, a layout in screens.tsx, the case in render.tsx, and the id to ROTATION in playlist.ts. The render test fails if a worst-case screen overflows the panel or the 90 KB device limit.
  • Refreshes: /api/display sends maximum_compatibility: true, so every update is a full refresh (a ~3 s black-white flash). Partial refreshes left the previous screen showing through and made solid black speckled on the OG DIY Kit panel; keep it on.
  • Design rules: the panel is pure black and white; grey renders as black. Use size, borders and inverted bars for emphasis, and keep rows to one line.
  • Icons and pictures: icons come from lucide-react (already a dependency) and render through Satori as SVG; draw them at strokeWidth 2.5 so thin strokes survive the 1-bit threshold. Photos and colour artwork do not survive it: threshold an image ahead of time, as logo.ts does for the round logo, and inline it so the function needs no file access.

How is this guide?

Edit on GitHub

Last updated on

On this page