From 4ea3b8a0c1d2a27ce74de8f3d7e1144e1357b7ce Mon Sep 17 00:00:00 2001 From: Cedric Hornberger Date: Wed, 28 Oct 2026 22:55:07 +0100 Subject: [PATCH] Add glossary, ADRs and future ideas from design grilling Co-Authored-By: Claude Opus 5.5 --- GLOSSARY.md | 72 ++++++++++++++++++++++ docs/adr/0001-v1-foundations.md | 19 ++++++ docs/adr/0002-library-ui-and-player.md | 22 +++++++ docs/adr/0003-tech-stack-follows-cookit.md | 17 +++++ future_ideas.md | 15 +++++ 5 files changed, 145 insertions(+) create mode 100644 GLOSSARY.md create mode 100644 docs/adr/0001-v1-foundations.md create mode 100644 docs/adr/0002-library-ui-and-player.md create mode 100644 docs/adr/0003-tech-stack-follows-cookit.md create mode 100644 future_ideas.md diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..7901f97 --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,72 @@ +# ZenXercise + +An offline Android app for stretching and working out, split into two fully separate Modes. The user +builds their own Plans from a large built-in Exercise Library and performs them in a guided Player. + +## Modes + +**Mode**: +One of the two top-level app states, **Stretching** or **Workout**. Switching Mode changes the whole +app: design, Exercise Library, Plans and History. The last-used Mode is remembered. +_Avoid_: Tab, section, category + +**Stretching Mode**: +The calm Mode: light design, sage/teal, rounded shapes, slow transitions. + +**Workout Mode**: +The energetic Mode: dark design, orange/red on near-black, bold type, snappy transitions. + +## Exercises + +**Exercise**: +A single movement from the Exercise Library, with name, Instructions, primary and secondary muscles, +equipment, level and a start and end image. Belongs to exactly one Mode. Users cannot create their own. +_Avoid_: Move, drill, activity + +**Exercise Library**: +The read-only catalogue of Exercises bundled with the app, sourced from free-exercise-db (876 +Exercises). Category `stretching` belongs to Stretching Mode (123); every other category to Workout +Mode (753). Browsed with text search and filters for muscle, equipment and level. +_Avoid_: Catalogue, database + +**Flip Animation**: +Alternating an Exercise's start and end image about once a second, the v1 stand-in for real animation. + +## Plans + +**Plan**: +A user-created, ordered list of Steps (and Supersets) belonging to one Mode. The app ships no Plans. +_Avoid_: Routine, program, workout + +**Step**: +One Exercise inside a Plan, with Mode-specific parameters: +- *Workout Step*: number of sets; reps **or** duration; optional target weight (kg). +- *Stretching Step*: hold duration; both-sides flag (left, then right); rounds. +_Avoid_: Item, entry + +**Superset**: +Two or more Workout Steps grouped so they are performed alternately, one set of each in turn. +_Avoid_: Circuit, combo + +## Sessions + +**Session**: +One run-through of a Plan in the Player. It stores a snapshot of the Plan, so later edits to the Plan +never change it. A Session is **complete** or **incomplete** (ended early). +_Avoid_: Workout, run + +**Player**: +The guided, one-Exercise-at-a-time screen used to perform a Session. It shows a large countdown ring, +pulses the Mode's accent colour in the last three seconds, shows full-screen "next" cards, advances +automatically when a timer ends, keeps the screen awake, and plays a gentle sound. No vibration. + +**Set Log**: +The reps and weight actually done for one Workout set, prefilled from the Step's targets and confirmed +with "Set done". + +**History**: +The per-Mode list of Sessions with date, Plan, duration and Set Logs. + +**Streak**: +A single, Duolingo-style daily streak shared by both Modes: consecutive days with at least one complete +Session in either Mode. Incomplete Sessions do not count. diff --git a/docs/adr/0001-v1-foundations.md b/docs/adr/0001-v1-foundations.md new file mode 100644 index 0000000..4c722b1 --- /dev/null +++ b/docs/adr/0001-v1-foundations.md @@ -0,0 +1,19 @@ +# ADR 0001 — v1 foundations + +Status: Accepted (2026-10-28) + +## Decisions + +1. **Platform**: Flutter, Android only. +2. **Modes**: A global Stretching / Workout switch that changes design, content and everything else. +3. **Content**: A large bundled Exercise Library; users create all Plans themselves (no built-in Plans). +4. **Data**: Offline only, local on-device storage, no accounts. +5. **Sessions**: Guided Player (timers, rest countdown, cues) rather than a checklist. +6. **History**: Simple log (date, Plan, duration) + Streak. +7. **Visuals**: Simple animations are desired, but may be deferred past v1. +8. **Scheduling / reminders**: Not in v1. + +## Consequences + +- No backend; all persistence is a local database on the device. +- The Exercise Library must be bundled in the APK, so its size (incl. images) matters. diff --git a/docs/adr/0002-library-ui-and-player.md b/docs/adr/0002-library-ui-and-player.md new file mode 100644 index 0000000..0d4b820 --- /dev/null +++ b/docs/adr/0002-library-ui-and-player.md @@ -0,0 +1,22 @@ +# ADR 0002 — Exercise library, mode design, Player cues + +Status: Accepted (2026-10-28) + +## Decisions + +1. **Library source**: free-exercise-db (Unlicense, 876 exercises). `stretching` → Stretching mode, + everything else → Workout mode. No user-created exercises. +2. **Images**: Bundle both images per exercise, compressed to WebP (~400px, est. 15–20 MB). + The start/end "flip" is the v1 animation; real animations are a future step. +3. **Language**: English only; UI strings centralised for later translation. +4. **Plan Steps**: Workout = sets, reps-or-duration, optional weight; no rest countdown. + Stretching = hold, both-sides flag, rounds. Workout Steps can be grouped into Supersets. +5. **Library browsing**: search + muscle/equipment/level filters, reused as the Plan exercise picker. +6. **Structure & design**: Mode switch at top; per-mode tabs Plans · Library · History. + Stretching = calm/light (sage/teal, rounded, slow). Workout = dark/energetic (orange/red, bold, snappy). + Last-used mode is remembered. +7. **Player cues**: Visual cues (countdown ring, accent pulse, next cards, auto-advance, screen kept on) + plus a gentle, non-annoying sound. No vibration. +8. **History**: Separate per Mode. The Streak is one shared, Duolingo-style daily Streak across both Modes; + only complete Sessions count. +9. **Units**: kg only. diff --git a/docs/adr/0003-tech-stack-follows-cookit.md b/docs/adr/0003-tech-stack-follows-cookit.md new file mode 100644 index 0000000..a6fb4a8 --- /dev/null +++ b/docs/adr/0003-tech-stack-follows-cookit.md @@ -0,0 +1,17 @@ +# ADR 0003 — Tech stack follows CookIT + +Status: Accepted (2026-10-28) + +ZenXercise uses the same stack and conventions as the author's CookIT app (local-first Flutter, Android), +so both codebases read alike. + +- State: `provider` with `ChangeNotifier` controllers, wired in `main.dart` via `MultiProvider`. +- Persistence: `drift` + `drift_flutter` (SQLite); `shared_preferences` for small settings (last Mode). +- Navigation: plain `Navigator` with named routes (no go_router). +- Strings: `flutter gen-l10n` with ARB files in `lib/src/localization` (`app_en.arb` template). +- Layout: `lib/src//` with repositories, controllers and `views/`. +- Screen-on in the Player: `wakelock_plus`. IDs: `uuid`. +- Tests: `flutter_test`, `mocktail`, `sqlite3` (in-memory drift in tests). +- Lints: `flutter_lints`. Docs: `GLOSSARY.md` (term / definition / _Avoid_) and `docs/adr/`. + +Supersedes the Riverpod / go_router proposal from the grilling session. diff --git a/future_ideas.md b/future_ideas.md new file mode 100644 index 0000000..664c170 --- /dev/null +++ b/future_ideas.md @@ -0,0 +1,15 @@ +# Future ideas + +Things deliberately left out of v1. + +- Real exercise animations or video (v1 uses the start/end Flip Animation) +- iOS build (and web/desktop) +- Accounts and cloud sync / backup +- Scheduling Plans on weekdays, with reminder notifications +- Built-in starter Plans +- Custom user-created Exercises +- Progress charts and personal records from Set Logs +- lb units (v1 is kg only) +- Vibration cues and voice guidance in the Player +- Translations (v1 is English only) +- Mixed Plans that combine Stretching and Workout (e.g. warm-up, workout, cool-down)