Repository navigation
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,neworlater. How to use the app:docs/usage-guide.md.
- Goals & principles
- Stack & platform
- Core model
- Alarms
- Timers & relays
- Relay language
- Stopwatch
- Clock
- Widgets
- Bedtime
- Calendar
- Settings
- Automation & assistants
- Firing & reliability
- Data model
- Visual direction
- Build order
- Open questions
The spec is split over these pages: Design spec, Panes spec, Relay language, Firing module, Data model, Visual direction and build order.
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.
- 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).
- 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.
- 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).
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
|
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)
- 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
- 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
- Counts up, with laps
- Stays in the list until deleted, named or not
- When: time, date or repeat days, end rule, exceptions
- What: one target (below)
| 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