Skip to content

Design Spec

haakooto edited this page Oct 24, 2026 · 2 revisions

Relay design spec

v1.0 · clean restart · 2026-09-30 · Android · Kotlin · Compose

One clock app, and timers that relay.

Relay rivals and replaces the stock Android Clock. Where the stock app is good, copy it closely. Where it is limited (timers can't chain, only alarms can be scheduled, a timer can't run twice at once), fix it.

v1.0, built. This is the baseline v1.0 was built from: all seven build steps (§16) are done and on-device tested, and the "As built" notes record where the build settled details the design left open. The earlier docs are in git history. Section tags show what is keep (proven in v0.5, carried over), changed, new or later. How to use the app: docs/usage-guide.md.

Contents

The spec is split over these pages: Design spec, Panes spec, Relay language, Firing module, Data model, Visual direction and build order.

01 · Goals & principles

Why

A one-app replacement for the stock Clock: Alarms, Timers, Stopwatch, Clock, Settings, and if feasible Bedtime, so nobody needs the stock app alongside it.

What to fix compared to the stock app

  • Timers can't chain. Relay has relays: scripted sequences of timers and other relays.
  • Only alarms can be scheduled. Relay can schedule a timer, a relay or a stopwatch as well as a plain alarm.
  • A saved timer can only run once at a time. In Relay, one definition can spawn any number of parallel runs.
  • Clock and widget styling is limited. Relay offers deep, per-instance style configuration.
  • Creating many similar alarms is tedious. A future automation API lets an on-phone assistant create them in bulk (§12).

Principles

  • An alarm must never fail to fire. Reliability beats features. Everything that rings goes through one hardened firing path (§13).
  • Separate definitions from runs. A definition is what you saved. A run is a live instance of it. One definition can have many runs.
  • One scheduling primitive. An alarm is a schedule whose target rings. Timers, relays and stopwatches are other targets on the same machinery.
  • Close copy where the stock app is good (alarm ringing screen, quick timers, world clock list). Don't reinvent what already works.
  • Fully local, no account, no sync. minSdk 33, single code path.
  • Room schema is versioned with real migrations from day one.

Non-goals

  • Sync or backup to a server.
  • Lock-screen widgets (Android removed third-party keyguard widgets).
  • Editing recorded stopwatch laps (a stopwatch is a factual record).

02 · Stack & platform

Foundation

Layer Choice Why
Language / UI Kotlin, Jetpack Compose (Material 3) Standard modern Android keep
Widgets Glance, with bitmap-rendered analogue faces Glance can't draw a Canvas or rotate views, so the analogue face is drawn to a bitmap on each minute tick keep
Persistence Room (entities) + DataStore (settings) Local only keep
Scheduling AlarmManager.setAlarmClock() for anything that rings, exact alarms for run step ends The only APIs that survive Doze reliably changed
Runs State persisted in Room, step ends driven by exact alarms, foreground service only for the live notification and in-app UI v0.5 used a coroutine delay() with in-memory state, so a process kill lost the run changed
Ringing audio Our own foreground playback (MediaPlayer, USAGE_ALARM, looping), not a notification-channel sound v0.5 finding: a channel sound is one-shot, and any other notification cut it off changed
Relay language chainlang, a standalone JVM module Parser, evaluator, safety limits and cycle checker are tested (30/30) keep. Extended in §06
SDK min 33, target latest stable Single notification-permission code path
i18n English + Norwegian (nb) from the first screen Retrofitting strings was expensive in v0.5 keep

03 · Core model

The idea

A timer counts down. An alarm is a countdown scheduled to end at a wall-clock time. Generalizing: anything startable can be scheduled, and anything scheduled can ring.

Schedule (time + repeat + exceptions) → Target (Ring · Timer · Relay · Stopwatch) → Run (live instance) → Firing (shared ring UI)

Definition

  • Timer or Relay, explicitly saved to the library
  • Its label is unique and is the name relays reference
  • Idle when not running; start any time
  • Referenceable by name from any relay

Run

  • A live countdown, spawned from a definition or unsaved
  • Optional free-text label, shown on the ringing screen
  • Many runs of one definition can run in parallel
  • Own state, controls and notification
  • Persisted, so it survives a process kill and a reboot

Stopwatch

  • Counts up, with laps
  • Stays in the list until deleted, named or not

Schedule (UI: "Alarm")

  • When: time, date or repeat days, end rule, exceptions
  • What: one target (below)

Lifecycle rules

Object Saved (library) Unsaved (anonymous)
Timer When a run ends, the definition goes back to idle, ready to start again Exists only as its run, optionally with a label. Gone when stopped
Relay Same as a saved timer Same as an unsaved timer
Stopwatch Stays until explicitly deleted, whether named or not
Schedule target Points at a library definition Inline, created and owned by the schedule, optionally labelled. Each fire spawns a fresh run. Save to library promotes it to a definition

Label vs. saved: any timer, relay or run can carry a free-text label ("Pasta", "Take pills"), which is shown when it rings. Saving to the library is a separate, explicit action (the Save button, not a checkbox). A saved block's label must be unique, because relays reference it by that label. Unsaved labels don't need to be unique.


Relay · spec v1.0 · clean-restart baseline, update as screens get built

Clone this wiki locally