halkyon/docs/adr/0038-halkyon-meditate.md

ADR 0038: Halkyon Meditate, what it does and how it looks

• Status: proposed 3 Nov 2026 by the agent, the developer having asked to "continue as far as possible without my interjection"; every decision below is the agent's recommendation unless it says the developer's, and is put to the developer with the first version. Built the same day: steps 1 to 4.
• Builds on: ADR 0033 (Todo's shell, which Meditate copies as Train copied Todo's, ADR 0030, D12); ADR 0030, D7, D14, D15 and D61 (sealed rows, the person's key, What's new); ADR 0031, D5 and D7 (Meditate's icon: Lucide's sprout, cobalt through pacific into fern); ADR 0014 and 0016 (the module and the register).

Context

On 3 Nov 2026 the developer asked for Halkyon Meditate, following "the basic approach as the other applications": the bar and the rail, the theme, the settings and account screens; and to look at eleven screenshots of 7Mind's Android app (1 Nov 2026, ~/Downloads/7mind-screenshots/). On 2 Nov they chose fern as Meditate's backdrop (ADR 0031, D5). What the screenshots show:

• Three tabs: For you, Explore, Profile.
• For you: a greeting with the person's name; a band of newly added content, each a card with its kind (Meditation, Sound, Sleep Story, Movement, Morning Stories, a course of several tracks), its length and its speaker; Your favorites and Recently played, each a row of the same cards with More.
• Explore: a search field, four goals as large tiles (reduce stress, sleep better, learn to meditate, take care of yourself), categories as a row of icons (autogenic training, breathing, dream journeys, knowledge, meditation, morning stories, movement, progressive muscle relaxation, routines, sleep stories, sounds), and topics as a list of cards with a line each (sleep, strength, personal development, relaxation, feelings and relationships, daily life, silence and sounds).
• Profile: minutes, sessions and days as large figures; the week's days as dots with the days in a row; Favorites, Downloads and Your path; then Account, Subscription, Notifications, Language, Appearance, the streak's visibility, help, legal information.
• No player is shown; 7Mind's content is recorded speech by its speakers, behind a subscription.

Halkyon has no recorded meditations, and none may be taken from 7Mind (its content, texts, names and pictures are its own). Everything below is Halkyon's own.

Decisions (3 Nov 2026, the agent's, to be confirmed)

• D1 Meditate's frame is Todo's and Train's (ADR 0033, D1; ADR 0030, D60): go_router with a StatefulShellRoute, each tab keeping its own stack, halkyon_ui's NavigationFrame (the bar floating above the foot below medium windows, a rail with Meditate's icon on top from medium on), halkyon_app's first start, sign-in and account, What's new after an update, About, English and German. Copied from Todo's and renamed, as Train's was (ADR 0030, D12), Todo's own features left out.
• D2 Three tabs: Today, Explore, Profile, as 7Mind has three, Today opening. Today (not For you: nothing is chosen for the person by anyone) starts a sitting at once, shows the week and the streak, the favourite practices and the ones done last. Explore holds every practice, by kind and by what it is for, with search. Profile is every Halkyon app's (HalkyonProfile, decided 2 Nov 2026): the person's own tab first, then Meditate's Practice tab with the figures, the week and the sittings. The cog to Settings stands atop Today and Profile, as Train's does atop Home and Profile. Over four tabs with the timer as one: the timer is one tap from Today and from Explore, and a sitting is a screen over the tabs (D6), as Train's recording is.
• D3 The washes are fern (the developer's, 2 Nov: ADR 0031, D5): every tab and the sitting's screen wash down from the top in PaletteColor.fern; buttons and links stay cobalt, as in every app.
• D4 What is practised: Halkyon's own practices, guided by text and bells, and the silent timer. Without recorded speech, a practice is a sitting of a set or chosen length with cues: short lines of guidance shown on the sitting's screen one after the other, spread evenly over the length chosen (so a practice scales to each of its lengths), and later read out by the device's text-to-speech (see Later). The practices are written for Meditate in English and German (practice.dart holds what each is, the ARBs its words), so their licence is the app's. Version 0.1.0 has six: counting breaths, a three-minute pause, a body scan, open awareness, kind wishes (loving-kindness) and settling for sleep, under the kinds Breathing, Body, Awareness, Kindness, Sleep and Pause, and the goals Calm down, Sleep, Focus and Begin; breath at the nostrils, walking, the 4-7-8 breath and box breathing come next, the breathing ones with a paced ring. A practice's ID never changes once released. The silent timer is a sitting of any length from 1 to 120 minutes with a bell at the start, at the end and, if chosen, every 1 to 30 minutes between. Recorded guidance (the instance's or the person's own files) is a later step: it needs the instance to hold and serve files, their licences checked, and their downloads kept on the device.
• D5 The bells are made for Meditate: three sounds (a singing bowl, a small bell, a wooden block) synthesised by apps/meditate/tool/bells.py (Python's standard library alone: decaying partials with the bowl's beating) into assets/bells/*.wav, so they carry the app's licence and no one else's; played with audioplayers (already in the workspace's lock, Learn's). Over recorded bells from freesound.org and the like, whose licences differ file by file.
• D6 A sitting is a screen over the tabs: a ring filling as the time passes, what is left inside it counted down by the seconds begun (5:00 until a second has passed), the practice's cue of the moment, Pause and Resume, and End (also the close button and back). Time is counted from the clock, not from a ticker, so a sitting paused by the system or the app going to the background is right as it comes back. The screen stays on while it runs where the person's setting says so (on by default, wakelock_plus, as the lock already holds it). Ended early, it asks whether to keep what was sat (Keep, Discard, or Sit on); a sitting under a minute is never kept and ends without asking. At the end, the bell, and Done with what was sat. Bells while the app is in the background are a later step (a scheduled notification's sound), as is reading the cues out.
• D7 What is kept: sealed rows, synced, as Todo's and Train's (ADR 0033, D5; ADR 0030, D7, D15): the person's key (content_key), one settings row (meditate_settings: the bell, the interval and starting bells, the screen kept on, the favourite practices, whether the streak shows) and a row a sitting (sitting: the practice or the timer, when it started as a wall-clock time with the device's offset, how long it was planned and sat). Everything is in the sealed payload; the instance sees that rows exist, their sizes and when they changed. Called sitting, not session, as Serverpod's Session is every endpoint's. A person's data goes with them (deleteMeditateData, the sync spaces' cascade, as Todo's).
• D8 The figures are worked out on the device from the sittings: minutes, sittings, days with a sitting, the days in a row (up to today, or up to yesterday while today has none yet, so a streak doesn't break before the day is over), and the week's days as dots from the week's first day in the person's language. The streak can be hidden (Settings, as 7Mind's Streak visibility), as some find streaks a pressure.
• D9 Today greets by the time of day (no name: the account has a handle, not necessarily a first name), offers Sit now with 5, 10 and 20 minutes and the timer's own length, the practice of the day (one after the other by the date, the same on every device), the week with the streak, the favourites and the last three sittings.
• D10 Explore is a search field (titles, summaries and kinds, every word typed, without case or accents), the goals as four tiles (chosen again to let go), the kinds as chips, and every practice as a card, narrowed by what is chosen. A practice's page says what it is, its length (a choice of lengths where it scales), how it goes (its cues in order), its favourite heart and Start.
• D11 Settings as Todo's (ADR 0033, D4): Sync's card first, the operator's card, then Meditate's own Sitting card (the bell, the starting bell, the interval bell's default, the screen kept on, the timer's default length) and Practice card (the streak shown), the account, What's new and About, the version below.
• D12 No reminders and no notifications in the first version: a daily reminder at a time the person sets is the first thing to add after it (Todo's notifications show the way).
• D13 Development ports of its own: API 8280, Insights 8281, web 8282, PostgreSQL 8290 (Learn's and Todo's are 8080 to 8090, Train's 8180 to 8190), so Meditate's server runs beside the others as a member of Learn's register.

Steps

1. The shell (3 Nov): Todo's copied and renamed, its features left out, the three tabs (D1, D2, D3), Settings (D11), the icon (ADR 0031, D7).
2. The data (3 Nov): the server's models and its migrations, the device's key, settings and sittings (D7).
3. The practices and the sitting (3 Nov): the catalogue (D4), the bells (D5), the sitting's screen (D6), Explore (D10).
4. Today and Profile (3 Nov): D8, D9.
5. Released and deployed (later, as Todo's step 5): apps/meditate/release.dart, a key of its own, the F-Droid listing, a snap, deploy/compose.meditate.yaml at meditate.halkyon.eu (its .env values the developer has set already, 2 Nov), its database and role, redeploy.sh and backup.sh taking it in.

Migrations

• initial: Serverpod's tables, its auth modules', halkyon_base's and the OIDC module's as they stand, as Train's first migration (ADR 0030); only CREATE TABLE, CREATE INDEX and foreign keys, nothing to transform.
• initial also holds the sync engine's tables (offline_sync_*), as the module is in config/generator.yaml from the start.
• sittings: Meditate's three tables, content_key, meditate_settings and sitting (CREATE TABLE, each an id UUID made by gen_random_uuid_v7(), which the migration defines again with CREATE OR REPLACE, a nullable spaceId, and the envelope's columns), an index on each spaceId (CREATE INDEX … USING btree) so deleting a person doesn't read the tables, and each spaceId's foreign key to offline_sync_spaces deleting with the space (ON DELETE CASCADE); then the version rows of every module (INSERT … ON CONFLICT DO UPDATE into serverpod_migrations). Purely additive: no row exists to transform.

Later

• Recorded guidance (D4), the cues read out by text-to-speech, bells in the background (D6), a daily reminder (D12), sittings written to Health Connect as mindfulness sessions (Android 14's MindfulnessSessionRecord), courses of several practices in order (7Mind's courses), ambient sounds.

Consequences

• The practices are text, short and translatable, so a new one is a change to practice.dart and its words in the two ARBs; a practice once used keeps its ID, as sittings name it.
• Without recorded voices, Meditate is a timer with guidance more than a library; recorded guidance (D4) is what would make it more.