General Backlog

BreakLoop General Product Backlog

How to read this backlog

Column	Meaning
ID	Stable identifier. Sprint backlogs, GitHub issues, and the sprint reports use these same IDs.
Pri	MoSCoW priority: M Must · S Should · C Could · W Won't (this term)
Pts	Story points (Fibonacci), per platform. Initial estimate, to be re-pointed during planning.
Source	Traceability to the wiki: V# prototype view · F# functional scenario · Q# quality scenario · SF# smart feature · CAS# context-aware feature · BQ# business question · PAS# PAS hypothesis
Kotlin / Flutter	When each app implements the item: S2 Sprint 2 (current) · S3 Sprint 3 · Later · — not planned
Plan	Used for shared items (backend, analytics, architecture, BQs), which are built once for both apps.

---

Epic overview

Epic	Goal	Scope
E0 · Foundation	Project skeletons, persistence, background work	Per app
E1 · Architecture & Design	Diagrams, architectural patterns, design patterns, tactics	Shared + per app
E2 · Design System	Reusable UI components matching the prototype	Per app
E3 · Backend & Cloud Services	Firebase setup, data model, sync, security, cloud jobs	Shared
E4 · Authentication & Onboarding	Accounts, permissions, first-run configuration	Per app
E5 · Usage Tracking & Sensors	Screen time, per-app usage, pickup detection	Per app
E6 · Goals & Progress	Personalized adaptive goals and streaks	Per app
E7 · Home & Statistics	Dashboard, progress, deep stats	Per app
E8 · Offline Activities & Recommendations	Activity library and context-aware suggestions	Per app
E9 · Focus Sessions	Pomodoro-style focus sprints	Per app
E10 · App Shield	Challenge gate and intent prompt for flagged apps	Per app
E11 · Gamification	XP, levels, pet, cabin, badges	Per app
E12 · Context-Aware Interventions	Wind-Down, notification management, adaptive interventions	Per app
E13 · Social	Friends, nudges, group quests	Per app + shared backend
E14 · Settings & Privacy	Configuration, permissions panel, account deletion	Per app
E15 · Analytics Pipeline	Instrumentation, processing, storage, dashboards	Shared + per app
E16 · Business Questions	Implementation of the Sprint 1 BQs	Shared
E17 · Quality & Release	Testing, pilot study, store release	Per app

---

E0 · Foundation

ID	Item	Pri	Pts	Source	Kotlin	Flutter
FND-01	Repositories (Kotlin app, Flutter app, backend, analytics), wiki, branching strategy, PR template, project board.	M	1	—	S2	S2
FND-02	App project setup: Kotlin with Compose M3 and a Gradle version catalog; Flutter with a pinned SDK, lints, and folder structure.	M	2	V1–V12	S2	S2
FND-03	Architecture skeleton: layered ui / domain / data, dependency injection, reactive streams (see ARC-03).	M	3	—	S2	S2
FND-04	Navigation: auth flow, onboarding flow, main flow with 5 bottom tabs and nested routes for all views.	M	3	V1–V12	S2	S2
FND-05	Local persistence: relational database (usage, pickups, goals, streaks, activities, logs) and key-value preferences.	M	5	Q4, Q11	S2	S2
FND-06	Build variants (dev / prod) and secrets handling. No keys in the repositories.	M	2	Q9	S2	S2
FND-07	CI with GitHub Actions: build, lint, and unit tests on every PR.	S	3	—	S2	S2
FND-08	Shared domain model and data dictionary: entities, field names, and what stays on device vs. what is synced. Both apps must write the same schema.	M	3	Q9	S2	S2
FND-09	Background work framework: periodic jobs, foreground-service base, restart after reboot.	M	3	Q10, Q11	S2	S2

E1 · Architecture & Design

ID	Item	Pri	Pts	Source	Plan
ARC-01	Architecture overview, component diagrams (Kotlin, Flutter, backend/analytics), and deployment diagram, each with a rationale.	M	3	Q1–Q12	S2
ARC-02	Sequence diagrams for key communication flows (sign-in and restore; usage tracking to analytics), each with a rationale.	M	2	Q4, Q9	S2
ARC-03	Architectural patterns implemented and documented: frontend pattern per app, backend pattern, analytics pattern. Each member contributes to one.	M	5	—	S2
ARC-04	Design patterns: one per member (6 total), each implemented in code with a snippet and rationale.	M	5	—	S2
ARC-05	Architectural tactics (performance, scalability, security, reliability, privacy) implemented and mapped to quality scenarios, with owners.	M	3	Q1–Q12	S2

E2 · Design System

ID	Item	Pri	Pts	Source	Kotlin	Flutter
DS-01	Theme: color tokens (cream, rust, dark brown, success green), pixel display font + body font, shapes.	M	3	All views	S2	S2
DS-02	Components: offset-shadow card, primary / secondary buttons, filter chips, toggle, progress bar, stat card, back button.	M	5	All views	S2	S2
DS-03	App header: logo, section label, Shield Test chip, streak chip.	M	2	V2–V12	S2	S2
DS-04	Bottom navigation: Hearth, Focus, Stats, Offline, Friends, with pixel icons and selected state.	M	2	V5–V12	S2	S2
DS-05	Pixel-art assets (pet stages, cabin scene, activity and badge icons), shared between both apps.	M	5	V1, V2, V6	S2	S2
DS-06	Accessibility: semantics / content descriptions, 48 dp touch targets, font scaling, contrast check.	S	3	—	S3	S3
DS-07	UI state pattern (loading / empty / error / content) used by every screen.	M	2	Q2, Q6	S2	S2

E3 · Backend & Cloud Services

Built once and shared by both apps. The data model and service list are detailed in Backend architecture.

ID	Item	Pri	Pts	Source	Plan
BE-01	Firebase projects (dev / prod); register the Kotlin app and the Flutter app (Android and, if targeted, iOS), including SHA-1 for Google Sign-In.	M	2	—	S2
BE-02	Firestore data model and composite indexes (see Data model).	M	3	Q9, Q12	S2
BE-03	Security rules: per-user isolation, field validation, public-profile subset; rules tested in the emulator.	M	3	Q9	S2
BE-04	Firebase Emulator Suite for local development and automated tests.	S	2	—	S2
BE-05	User provisioning on sign-up: create users/{uid} and default settings in a single transaction.	M	2	—	S2
BE-06	Daily stats sync: upload dailyStats/{date} from the local database; idempotent by date, retries with backoff.	M	5	Q4, Q12	S2
BE-07	Daily close job: at local midnight (with catch-up on app open) finalize the day, evaluate goal met, update streak in progress/current via transaction.	M	5	Q4, Q11	S2
BE-08	Activity catalog in Firestore, seeding script, local cache with bundled JSON fallback.	M	3	Q2	S2
BE-09	Weather service client (Open-Meteo, no API key): 30-minute cache, timeout and offline handling.	M	3	Q1, Q2	S2
BE-10	Activity log sync (activityLogs).	M	2	BQ6, BQ11	S2
BE-11	Focus session sync (focusSessions).	M	2	BQ4, BQ5	S3
BE-12	Restore on login: pull goals, stats (last 30 days), progress, and logs into the local database on a new or reinstalled device.	M	3	Q4, Q11	S2
BE-13	FCM token registration per device and push-sending Cloud Function (milestones, nudges, quest updates).	S	3	F4	S3
BE-14	Account deletion cascade (Cloud Function on auth user delete) and data export.	M	3	Q9	S3
BE-15	Remote Config for tunables: goal step %, XP values, challenge durations, recommendation weights.	S	2	SF3, SF5	S3
BE-16	Monitoring: Crashlytics, Cloud Function logs and alerts, Firestore usage and budget alerts.	S	2	Q12	S3
BE-17	Social backend: friend requests, status updates, nudge rate limiting (Cloud Functions).	M	5	V11	Later
BE-18	Quest evaluation and leaderboard aggregation (scheduled Cloud Functions, server-side trusted totals).	M	5	V11, V12	Later
BE-19	Server-side validation of streaks and XP (Cloud Function) to prevent client tampering.	S	3	Q9	Later
BE-20	Aggregated, anonymized reporting (minimum group size) for partner insights.	C	5	BQ11, BQ12	Later
BE-21	Backend repository as code: security rules, indexes, seed scripts, and functions deployed with the Firebase CLI.	M	2	—	S2

E4 · Authentication & Onboarding

ID	Item	Pri	Pts	Source	Kotlin	Flutter
AUTH-01	Login and sign-up screens (email / password) with field validation.	M	3	—	S2	S2
AUTH-02	Firebase Auth email / password integration and user-friendly error mapping.	M	3	—	S2	S2
AUTH-03	Google Sign-In.	S	3	—	S2	S2
AUTH-04	Session persistence, auto-login, auth-state routing from splash, logout that clears user-scoped local data.	M	2	Q9	S2	S2
AUTH-05	Password reset by email.	S	1	—	S2	S2
AUTH-06	Email verification.	C	1	—	Later	Later
ONB-01	Welcome screens explaining the value proposition.	S	2	§1.4	S3	S3
ONB-02	Core permission flow with rationale screens: usage access, notifications, coarse location (optional).	M	5	Q6	S2	S2
ONB-03	Advanced permission flow: display over other apps, DND access, notification listener, modify system settings, exact alarms, battery-optimization exemption.	M	5	Q3, Q7	S3	S3
ONB-04	Flag distracting apps from installed launchable apps; set a daily limit for each one.	M	5	F3, F6	S2	S2
ONB-05	Interest profile: categories (Move, Create, Relax, Socialize) and specific interests.	M	3	PAS2, Q8	S2	S2
ONB-06	Baseline and first-goal step (UI for GOAL-01 to GOAL-04).	M	3	SF6	S2	S2
ONB-07	Bedtime and preferred focus length.	M	2	F1, F2	S3	S3
ONB-08	Name your pet.	C	1	V2	S3	S3
ONB-09	Privacy consent, data-use explanation, and analytics opt-in.	M	2	Q9	S2	S2

E5 · Usage Tracking & Sensors

ID	Item	Pri	Pts	Source	Kotlin	Flutter
TRK-01	Per-app foreground time and daily totals from Android usage events.	M	8	SF1, F6	S2	S2
TRK-02	Aggregation job writing to the local database; handles midnight rollover and time-zone changes.	M	5	Q10	S2	S2
TRK-03	Flagged-app usage vs. limit and "cushion left" against the daily goal.	M	3	V1	S2	S2
TRK-04	Pickup detection: screen-on and unlock events in a foreground service, each screen-on classified with a short accelerometer window (picked up vs. woke on table).	M	8	SF2, F5	S2	S2
TRK-05	Pickup metrics: daily count, difference vs. baseline, average interval between checks.	M	2	V8	S2	S2
TRK-06	Sensor capability check with fallback to unlock-only counting; capability recorded for telemetry.	M	2	BQ1	S2	S2
TRK-07	Permission revocation detection, degraded mode, and deep link to restore.	M	3	Q6	S3	S3
TRK-08	Battery and performance budget: sensor only active during classification windows; profiling.	M	3	Q10, BQ2	S2	S2

E6 · Goals & Progress

ID	Item	Pri	Pts	Source	Kotlin	Flutter
GOAL-01	Baseline computation: median daily screen time over the last 7 days of usage history, with fallback when less history exists.	M	3	SF6	S2	S2
GOAL-02	Goal suggestion algorithm: gradual weekly steps from baseline toward the −20 % target.	M	3	SF6, §1.1	S2	S2
GOAL-03	Weekly adaptive adjustment based on how many days the goal was met.	M	5	SF6, PAS7	S2	S2
GOAL-04	Goal review UI: accept or override the suggestion, with a short "why this goal" explanation.	M	2	SF6	S2	S2
GOAL-05	Streak engine: consecutive days under goal, best streak, local-first.	M	3	V7, F4, Q4	S2	S2
GOAL-06	Per-app limit suggestions from history.	S	3	SF1	Later	Later

E7 · Home & Statistics

ID	Item	Pri	Pts	Source	Kotlin	Flutter
STA-01	Home screen-time card: today's time, % vs. goal, cushion left.	M	3	V1	S2	S2
STA-02	Stats overview metric cards: today, focus minutes, current streak, best streak.	M	3	V7	S2	S2
STA-03	Weekly screen-rhythm bar chart with goal line, weekly average, and breach count.	M	5	V7	S2	S2
STA-04	"Tamed distraction loops": time saved per flagged app vs. that app's baseline.	M	3	V7	S2	S2
STA-05	Deep Stats pickup card: daily pickups, vs. baseline, average interval.	M	2	V8	S2	S2
STA-06	Deep Stats intentionality gauge (requires SHD-09).	M	2	V8	S3	S3
STA-07	Reduction-vs-baseline insight: weekly average vs. baseline week, % change, progress toward −20 %.	M	3	BQ3	S2	S2
STA-08	Day / week / month selector and per-app breakdown.	S	3	F6	S3	S3
STA-09	Focus session history (completed vs. abandoned).	S	3	BQ5	S3	S3

E8 · Offline Activities & Recommendations

ID	Item	Pri	Pts	Source	Kotlin	Flutter
OFF-01	Local activity catalog (synced from BE-08) with category, duration, XP, prompt, and context tags.	M	3	Q2	S2	S2
OFF-02	Offline list screen with category filter chips.	M	3	V9	S2	S2
OFF-03	Activity detail with "Start & Log": timer, completion confirmation, XP recorded.	M	3	V10	S2	S2
OFF-04	Context provider: builds a snapshot of time of day, day type, available time, weather, interests, and recent history.	M	5	CAS1	S2	S2
OFF-05	Rule-based recommender: scores and ranks activities; cold-start fallback on interests only.	M	5	SF4, Q8	S2	S2
OFF-06	"Suggested for right now" card on the Offline screen with an available-time selector and a reason label.	M	2	CAS1, Q1	S2	S2
OFF-07	Weather context via BE-09 plus coarse location; clear "offline-based" label when unavailable.	M	3	Q1, Q2	S2	S2
OFF-08	Suggestion notification when a daily limit is reached.	S	3	F11	S3	S3
OFF-09	Acceptance tracking and activity streaks.	S	2	PAS2, BQ11, BQ13	S2	S2
OFF-10	Learn from accept / skip feedback by re-weighting categories.	S	3	SF4	Later	Later

E9 · Focus Sessions

ID	Item	Pri	Pts	Source	Kotlin	Flutter
FOC-01	Focus Setup screen: 25 / 45 / 60 / custom, optional goal, soundscape, shield toggle.	M	5	V3	S3	S3
FOC-02	Quick-start focus sprint from Home with the saved default length.	M	1	V1, F1	S3	S3
FOC-03	Session timer as a foreground service with ongoing notification; countdown and progress bar.	M	5	V4	S3	S3
FOC-04	DND during the session, restoring the previous state afterward; DND badge.	M	3	V4, Q7	S3	S3
FOC-05	Looping soundscapes.	S	3	V3	S3	S3
FOC-06	End session early with confirmation; partial XP logged.	M	2	V4	S3	S3
FOC-07	Summary screen: duration, % on target, XP, streak, vitality, next actions.	M	3	V5	S3	S3
FOC-08	Crash and reboot recovery of a running session.	M	3	Q11	S3	S3
FOC-09	Priority contacts allowed through during focus.	S	5	F7, PAS6	Later	Later
FOC-10	Hold non-urgent notifications during a session and show a summary afterward (uses INT-06).	S	5	F7, F12	Later	Later

E10 · App Shield

ID	Item	Pri	Pts	Source	Kotlin	Flutter
SHD-01	Spike: detection strategy for flagged-app launches (AccessibilityService vs. usage-event polling), including Play policy impact.	M	3	Q3	S3	S3
SHD-02	Block overlay when a flagged app reaches its limit, with an "Unlock" action.	M	5	F3	S3	S3
SHD-03	10-second breathing challenge that grants a temporary access window.	M	5	F3, V3	S3	S3
SHD-04	Additional challenge types: quick quiz, short physical task.	S	5	PAS1	Later	Later
SHD-05	Escalating friction: longer or harder challenge per bypass, reset daily.	M	3	SF5, CAS4, BQ9	S3	S3
SHD-06	Gate integrity: re-show if the app is reopened from recents or BreakLoop is force-closed.	M	5	Q3	S3	S3
SHD-07	App Shield toggle; header "Shield Test" launches a demo challenge.	M	2	V3	S3	S3
SHD-08	Offer an offline activity on the block screen.	S	3	PAS2, F11	Later	Later
SHD-09	Intent prompt (specific task / messages / just browsing) before a flagged app opens.	M	5	F8, V8, PAS12	S3	S3

E11 · Gamification

ID	Item	Pri	Pts	Source	Kotlin	Flutter
GAM-01	XP rules engine with daily caps against farming.	M	3	V1, V2, V5	S3	S3
GAM-02	Levels and evolution thresholds.	M	2	V1	S3	S3
GAM-03	Hearth Vitality formula (0–100).	M	3	V1, V5	S3	S3
GAM-04	Pet & Cabin screen: pet state, mood from vitality, décor unlocks, "Water Sprout".	M	5	V2	S3	S3
GAM-05	Home cabin preview with level and XP bar.	M	5	V1	S3	S3
GAM-06	Badges: definitions, unlock evaluator, grid with states, unlock celebration.	M	5	V6	S3	S3
GAM-07	Streak milestone notifications (uses BE-13).	S	2	F4	S3	S3
GAM-08	Pet evolution animation.	C	3	V1	Later	Later

E12 · Context-Aware Interventions

ID	Item	Pri	Pts	Source	Kotlin	Flutter
INT-01	Wind-Down Mode: exact-alarm schedule, reminder, lower brightness and filter notifications until morning.	M	8	F2, CAS2	S3	S3
INT-02	Wind-down activity suggestions (reuses OFF-05).	S	2	PAS11	Later	Later
INT-03	Spike: grayscale options on Android and detection of external display changes.	S	5	Q5, SF3	Later	Later
INT-04	Adaptive intervention rules engine: triggers (overuse, pickup bursts, late night) → actions.	S	8	SF3, CAS5	Later	Later
INT-05	Context-aware Focus Mode (selected activity and schedule adapt the phone environment).	S	5	CAS3	Later	Later
INT-06	Notification listener infrastructure and scheduled grouped delivery.	S	5	F10, Q7	Later	Later
INT-07	FOMO Journal.	C	5	F9, PAS4	Later	Later
INT-08	Reinstall cooldown. Not feasible for a normal store app.	W	—	PAS5	—	—

E13 · Social

ID	Item	Pri	Pts	Source	Kotlin	Flutter
SOC-01	Friends: add by code or username, accept / decline, remove (uses BE-17).	M	5	V11	Later	Later
SOC-02	Status sharing (focusing, offline activity, resting). Status only, never raw usage.	M	5	V11, Q9	Later	Later
SOC-03	Buddy list with streaks and rate-limited "Nudge" push.	M	5	V11	Later	Later
SOC-04	Mindful-hours leaderboard (uses BE-18).	S	3	V11	Later	Later
SOC-05	Group quests: create / join cohort, goal, duration, daily evaluation, progress (uses BE-18).	M	8	V11, V12	Later	Later
SOC-06	"Send warmth & cheer" to cohort.	S	2	V12	Later	Later
SOC-07	Shared-cabin lanterns reward.	C	3	V12	Later	Later

E14 · Settings & Privacy

ID	Item	Pri	Pts	Source	Kotlin	Flutter
SET-01	Settings screen: flagged apps and limits, goal, bedtime, focus defaults, challenge types, notifications.	M	5	—	S3	S3
SET-02	Permissions status panel with fix-it links.	M	2	Q6	S3	S3
SET-03	Delete account and data; export data (uses BE-14).	M	3	Q9	S3	S3
SET-04	Notification channels (tracking service, reminders, social).	M	1	Q7	S2	S2

E15 · Analytics Pipeline

ID	Item	Pri	Pts	Source	Plan
DAT-01	Analytics event taxonomy shared by both apps: event names, parameters, app version, and platform on every event.	M	3	Analytics persona	S2
DAT-02	Instrument events in both apps (session, challenge, intent, activity suggested / accepted, pickup, goal met).	M	5	BQ1–BQ14	S2
DAT-03	Device telemetry: model, OS, accelerometer present, battery impact.	S	3	BQ1, BQ2	S2
DAT-04	Crashlytics and non-fatal error logging in both apps.	M	1	—	S2
DAT-05	Analytics pipeline design: diagram with rationale covering generation, collection, processing, storage, and analysis.	M	2	—	S2
DAT-06	Ingestion and storage: Firebase Analytics events and Firestore aggregates exported to the analytics store (e.g. BigQuery).	M	5	BQ1–BQ14	S2
DAT-07	Processing jobs in the analytics repository: cleaning, aggregation per user / day / device, privacy filters.	M	5	Q9	S2
DAT-08	Dashboards and visualizations answering the implemented BQs (e.g. Looker Studio or notebooks).	M	3	BQ1–BQ14	S2
DAT-09	Data-quality checks: missing days, duplicates, app-version consistency.	S	2	Analytics persona	S3

E16 · Business Questions

Each member implements one BQ (6 in Sprint 2, from the Sprint 1 list). "S2 candidate" means the data needed is produced by features planned for Sprint 2. Set Responsible once the 6 are chosen, and change the other candidates to S3 / Later.

ID	BQ	Type	Needs	Pri	Pts	Plan	Responsible
BQ-01	Devices without an accelerometer, by model and OS	1	TRK-06, DAT-03	M	3	S2 candidate
BQ-02	Battery consumption by device model	1	TRK-08, DAT-03	S	3	S2 candidate
BQ-03	Weekly screen-time decrease after interventions	2	TRK-01, GOAL-01, STA-07	M	3	S2 candidate
BQ-04	Focus Mode and uninterrupted sessions	2	E9	S	3	S3
BQ-05	Pomodoro completion information shown to users	2	E9, STA-09	S	3	S3
BQ-06	Screen time avoided after accepting an offline activity	2	TRK-01, OFF-03, OFF-09	S	3	S2 candidate
BQ-07	Check Counter (> 4 weeks vs. < 1 week) and pickups	3	TRK-04, 4+ weeks of data	S	3	Later
BQ-08	Virtual pet and focus-session length	3	E9, E11	S	3	S3
BQ-09	Challenge difficulty and flagged-app access rate	3	E10	S	3	S3
BQ-10	Offline recommendations and flagged-app time	3	TRK-03, OFF-09	S	3	S2 candidate
BQ-11	Activity categories with the highest acceptance	4	OFF-09, DAT-07	S	3	S2 candidate
BQ-12	Times and locations with highest activity acceptance	4	OFF-07, OFF-09, BE-20	C	5	Later
BQ-13	Activity acceptance vs. goal-streak length	*	OFF-09, GOAL-05	S	3	S2 candidate
BQ-14	Phone checks vs. flagged-app time vs. focus completion	*	TRK-04, TRK-03, E9	S	5	S3

E17 · Quality & Release

ID	Item	Pri	Pts	Source	Kotlin	Flutter
QA-01	Unit tests for domain logic (goals, streaks, recommender, pickup classifier; later XP and escalation).	M	5	—	S2	S2
QA-02	Database and repository tests, including day rollover and sync edge cases.	M	3	Q4, Q11	S2	S2
QA-03	UI / widget tests for key flows.	S	5	—	S3	S3
QA-04	Device matrix testing, including aggressive OEM background killers (Xiaomi, Samsung, Huawei).	M	5	Q10, Q11	S3	S3
QA-05	Performance and battery profiling.	S	3	Q10	S3	S3
QA-06	Analytics validation: events arrive, aggregates match app values, BQ results reproducible.	M	3	BQ1–BQ14	S2	S2
QA-07	Usability tests with about 5 students matching the personas.	M	3	Personas	Later	Later
QA-08	Pilot study: baseline week vs. intervention weeks to measure the −20 % target.	S	5	§1.1, BQ3	Later	Later
QA-09	Backend load test.	C	3	Q12	Later	Later
REL-01	Store release: privacy policy, Data Safety form, sensitive-permission declarations, signing, internal testing track.	S	5	Q9	Later	Later
REL-02	Premium subscription and partner offers.	W	—	§1.3	—	—

---

Backend architecture

Services

Service	Used for	Backlog items
Firebase Authentication	Email / password and Google accounts	AUTH-01 – AUTH-05, BE-05
Cloud Firestore	User profile, goals, daily stats, progress, logs, catalog, social data	BE-02 – BE-12, BE-17, BE-18
Cloud Functions	Account deletion cascade, push sending, quest and leaderboard aggregation, server-side validation	BE-13, BE-14, BE-17 – BE-19
Firebase Cloud Messaging	Milestones, nudges, quest updates	BE-13, GAM-07, SOC-03
Remote Config	Tunable algorithm parameters	BE-15
Firebase Analytics / Crashlytics	Event collection and stability	DAT-01 – DAT-04
Analytics store and dashboards	Processing and answering the BQs	DAT-06 – DAT-08
Open-Meteo API	Current weather for recommendations (free, no API key)	BE-09, OFF-07
Location services	Coarse location for weather	OFF-07

Plan limits: Cloud Functions require the Firebase Blaze (pay-as-you-go) plan. Check the export limits of your plan before committing to the DAT-06 storage choice.

Firestore data model

Both apps must read and write exactly this schema (FND-08).

users/{uid}
  displayName, email, createdAt, timeZone, platform: "kotlin" | "flutter"
  interests: [string]
  flaggedApps: [{ packageName, label, dailyLimitMin }]
  consent: { analytics: bool, location: bool }

users/{uid}/goals/{weekStart}          # yyyy-MM-dd (Monday)
  baselineMin, goalMin, targetMin, daysMet, source: "suggested" | "user"

users/{uid}/dailyStats/{date}          # yyyy-MM-dd, one doc per day (idempotent)
  screenTimeMin, flaggedAppMin: { packageName: minutes }
  pickups, unlocks, goalMin, goalMet, closed: bool, updatedAt

users/{uid}/progress/current
  currentStreak, bestStreak, lastClosedDate, xp, level, vitality

users/{uid}/activityLogs/{logId}
  activityId, startedAt, completedAt, durationMin, xp
  source: "recommended" | "browsed", accepted: bool
  context: { timeOfDay, weather, availableMin }

users/{uid}/devices/{installationId}
  model, osVersion, appVersion, platform, hasAccelerometer, fcmToken

users/{uid}/focusSessions/{sessionId}  # Sprint 3
users/{uid}/badges/{badgeId}           # Sprint 3

activities/{activityId}                # read-only catalog
  title, category, durationMin, xp, prompt
  tags: { outdoor: bool, weather: [string], timeOfDay: [string] }, active

publicProfiles/{uid}                   # Later: shared subset only
friendships/{pairId}, quests/{questId}, quests/{questId}/members/{uid}, nudges/{nudgeId}

Privacy rule (Q9): only per-app time for flagged apps leaves the device. The full installed-app list and non-flagged usage stay local.

---

Platform implementation notes

The items above describe what to build. This table suggests how each app can build it. The Flutter packages listed are common choices; verify that each is maintained and fits your SDK version before adopting it.

Capability	Kotlin	Flutter
UI	Jetpack Compose M3	Flutter widgets (Material 3)
State / architecture	ViewModel + StateFlow (MVVM)	Provider, Riverpod, or BLoC
Dependency injection	Hilt	Provider / Riverpod / get_it
Local database	Room + DataStore	drift or sqflite + shared_preferences
Background work	WorkManager + foreground service	workmanager + a foreground-service plugin
Usage stats	UsageStatsManager / UsageEvents	Usage-stats plugin or a platform channel to the Android API
Accelerometer	SensorManager	sensors_plus
Screen-on / unlock events	Dynamic BroadcastReceiver	Platform channel (no pure-Dart equivalent)
Networking	Retrofit / OkHttp	dio or http
Location	Fused Location Provider	geolocator
Charts	Compose Canvas	fl_chart
Firebase	Firebase Android SDKs	FlutterFire plugins

---

Roadmap

Phase	Focus	Main items
S2 (current)	Foundation, architecture, auth, tracking and sensor, smart goals, stats, context-aware recommendations, cloud sync, analytics pipeline, 6 BQs	See Sprint 2 Backlog
S3	Focus sessions, App Shield and intent prompt, gamification, Wind-Down, settings, push, remaining S3 BQs	E9, E10, E11, INT-01, E14, BE-11, BE-13 – BE-16
Later	Social and quests, adaptive interventions, notification management, pilot study, release	E13, INT-02 – INT-07, BE-17 – BE-20, QA-07 – QA-09, REL-01

---

Risks and open questions

Risk	Impact	Mitigation
iOS does not give apps per-app usage data or screen-on events without Apple's Screen Time (Family Controls) entitlement.	Flutter app on iOS: E5, E7, E10	Target Android for the Flutter app, or plan reduced features on iOS.
Some tracking features on Flutter need native Android code (platform channels).	Flutter: TRK-01, TRK-04	Plan platform-channel work in the Flutter estimates; share knowledge with the Kotlin team.
Two apps writing the same Firestore data can drift apart.	BE-02, DAT-01	One shared schema and event taxonomy (FND-08, DAT-01); security-rule validation (BE-03).
Grayscale cannot be toggled by a normal store app (needs WRITE_SECURE_SETTINGS granted over adb).	SF3, CAS5, Q5	INT-03 spike; plan an alternative intervention.
AccessibilityService triggers extra Play policy review.	App Shield	SHD-01 spike; prefer usage-event polling if latency is acceptable.
OEM battery managers kill foreground services.	Pickup detection, Q3, Q11	Battery-optimization exemption (ONB-03), restart after reboot (FND-09), QA-04.
Android 12+ exact alarms need a separate permission.	Wind-Down	Request in ONB-03; fall back to an inexact alarm.
Android 14+ requires a declared foreground-service type.	Pickup detection	Use specialUse with a justification property.
Cloud Functions and some analytics exports need a paid Firebase plan.	BE-13 – BE-19, DAT-06	Sprint 2 relies on client-side jobs and security rules; verify plan limits for DAT-06.
"Time saved" and "Hearth Vitality" are undefined formulas; values differ between prototype screens (92/100 vs. 96 %).	V1, V5, V7	Define formulas in STA-04 and GAM-03 before implementation.
Screens missing from the prototype: auth, onboarding, permissions, settings, challenge overlay, intent prompt, activity in progress, friend management.	Several epics	Design them before the sprint that implements them.

---

Definition of Done

An item is done when:

1. The code is merged to main through a reviewed PR and CI passes.
2. It follows the agreed architectural pattern for its app.
3. Domain logic has unit tests.
4. Every screen handles loading, empty, error, and permission-missing states.
5. Strings are externalized and no secrets are hard-coded.
6. Shared data follows the schema in FND-08 and the event taxonomy in DAT-01.
7. It has been tested on at least one physical device.
8. Its acceptance criteria have been demonstrated to the team.
9. The wiki is updated if the item changes architecture, data, or analytics.