CONTEXT.md

OnTime Front

This context defines product language for the OnTime Flutter app so analytics, release, and feature discussions use the same terms.

Language

OnTime User: A person's OnTime account profile that owns schedules, places, preparation defaults, and notification preferences. Avoid: User identity, analytics subject, device

Schedule: A planned commitment with an intended time, destination place, travel time, and optional preparation plan. Avoid: Alarm, notification, calendar row

Place: The destination or location label attached to a Schedule. Avoid: Route, address record, notification location

Preparation: An ordered plan of steps the user intends to complete before leaving for a Schedule. Avoid: Reminder, notification, alarm

Preparation Step: One named action in a Preparation with an expected duration. Avoid: UI row, checklist widget, notification step

Product Usage Event: A named record that a user performed a product-relevant action, excluding raw personal content. Avoid: User activity, tracking event, raw interaction log

Analytics Purpose: The approved reason a Product Usage Event may be collected or used. Avoid: Use case, tracking reason

Experiment: A pseudonymous feature or configuration comparison used for product improvement. Avoid: Personalization, marketing campaign, user targeting

Deferred Analytics Purpose: An Analytics Purpose that is recognized but not active until a later privacy and consent review approves it. Avoid: Future tracking, inactive use case

Pseudonymous Analytics Subject: The non-directly-identifying actor associated with a Product Usage Event. Avoid: User identity, personal identity, email identity

Analytics Preference: The user's current choice about whether optional Product Usage Events may be collected. Avoid: Tracking consent, privacy switch

Help Improve OnTime: The user-facing name for the Analytics Preference. Avoid: Tracking, marketing analytics, personalization

Analytics Provider: An external service approved to receive Product Usage Events. Avoid: Tracking vendor, analytics SDK

Workflow Milestone Event: A Product Usage Event that marks completion or failure of a meaningful user workflow step. Avoid: Tap event, raw navigation log, interaction trace

Schedule: A planned commitment with a target time that OnTime helps the user prepare for. Avoid: Event, appointment, alarm

Preparation: The ordered set of steps a user completes before a Schedule. Avoid: Preparation chain, task list

Preparation Step: One named action with an expected duration inside a Preparation. Avoid: Task, checklist item, alarm step

Provider Authentication Completed: The state where the external Apple or Google account prompt has returned credentials to OnTime. Avoid: Login completed, signed in, session ready

OnTime Session Established: The state where OnTime has accepted provider credentials, created an app session, and can route the user into the signed-in app experience. Avoid: Provider login completed, credential received

Analytics Event Parameter: An allowlisted non-content value attached to a Product Usage Event. Avoid: Event payload, arbitrary metadata, raw detail

Schedule: A planned commitment with a place, appointment time, travel time, optional buffer time, and preparation. Avoid: Event, appointment record

Preparation: An ordered set of steps and durations used to get ready for a Schedule. Avoid: Routine, prep checklist

Preparation Step: One named action in a Preparation with its own expected duration. Avoid: Task, todo, subroutine

Preparation Start Moment: The intended time for the user to begin Preparation so the Schedule can still be met on time. Avoid: Alarm time, notification time, wake-up time

Schedule Preparation Session: The active period when a user is working through Preparation for one Schedule. Avoid: Schedule run, preparation runtime, alarm session

Early Start Session: A Schedule Preparation Session that the user starts before the Preparation Start Moment. Avoid: Manual start, premature alarm, early alarm

Preparation Duration: The sum of a Schedule's Preparation step durations, excluding move time and Schedule Spare Time. Avoid: Total duration, travel time, buffer time

Schedule Spare Time: A user buffer before a Schedule's appointment time, separate from travel time and Preparation Duration. Avoid: Preparation time, move time

Default Preparation: The user's fallback Preparation for new Schedules. Avoid: Base preparation, global preparation

Custom Preparation: A Schedule-specific Preparation that differs from the user's fallback or selected template. Avoid: Changed preparation, edited default

Preparation Mode: The category describing whether a Schedule uses Default Preparation, a preparation template, or Custom Preparation. Avoid: Preparation type, preparation source

Schedule Notification: A user-facing notification that starts preparation for a scheduled commitment at the intended moment. Avoid: Schedule alarm, alarm, push

Schedule Notification Setting: The user-facing setting that controls whether OnTime sends notifications for upcoming schedule preparation. Avoid: Schedule alarm setting, alarm switch

Alarm: An alarm experience that opens an OnTime screen over the lock screen or current app without the user first tapping a notification. Avoid: Notification, alert, push

iOS AlarmKit Alarm: The iOS alarm experience OnTime may use when the device and build support AlarmKit. Avoid: iOS notification, fallback notification

Android Schedule Notification: The Android presentation that alerts the user through a notification instead of an Alarm. Avoid: Android alarm, native alarm UI

Precise Notification Timing: The expectation that a Schedule Notification is delivered at the intended preparation start moment. Avoid: Best-effort reminder, approximate notification

Fallback Notification: A secondary delivery path used only when Precise Notification Timing is unavailable. Avoid: Alarm, alarm permission

Exact Timing Permission: The user's permission for OnTime to schedule notifications at precise times on devices that require it. Avoid: Alarm permission, notification permission

No Scheduled Notification: The state where notifications are enabled but no Schedule Notification is currently armed for an upcoming schedule. Avoid: Pending, waiting, permission pending

Approximate Notification Timing: The state where OnTime may notify the user for a schedule but cannot guarantee delivery at the exact preparation time. Avoid: Disabled notifications, alarm denied

Precise Notification Status: The user-facing status for a Schedule Notification that can be delivered with Precise Notification Timing. Avoid: Native alarm, exact alarm

Notification Status: The user-facing status for schedule delivery through notifications when Alarm delivery or Precise Notification Timing is unavailable. Avoid: Fallback, degraded, time sensitive

Alarm Status: The user-facing status for schedule delivery through an Alarm. Avoid: Notification, native alarm

Preparation Run: One user attempt to prepare for a scheduled commitment. Avoid: Timer session, countdown session

Preparation Action Event: A user-performed action that changes a Preparation Run. Avoid: Timer tick, automatic step transition, elapsed-time snapshot

Schedule: A user commitment with a planned time and preparation context in OnTime. Avoid: Appointment, event, task

Monthly Calendar: The calendar surface that shows Schedules grouped by day across a calendar month. Avoid: Month view, calendar grid

Calendar Month Range: A contiguous span of calendar months whose Schedules are in scope for a Monthly Calendar. Avoid: Loaded range, stream range, cached range

Relationships

• A Product Usage Event may describe a Schedule, Preparation, notification, alarm, onboarding, or account action without storing the user's raw schedule names, notes, place names, credentials, tokens, or free text.
• A Schedule has one effective Preparation for calculating preparation timing.
• A Default Preparation may seed a new Schedule before the user chooses a different preparation.
• A Custom Preparation belongs to one Schedule.
• Preparation Mode may appear as an Analytics Event Parameter without exposing preparation step names.
• A Monthly Calendar displays Schedules grouped by calendar day.
• A Calendar Month Range starts at the first day of its first month and ends before the first day of the month after its last month.
• A Monthly Calendar may extend a Calendar Month Range when the user moves to an adjacent month.
• An OnTime User may own zero or more Schedules.
• A Schedule has one Place.
• A Schedule may use one Preparation.
• A Preparation contains zero or more Preparation Steps in user-defined order.
• A Preparation Step belongs to exactly one Preparation.
• A Schedule Notification uses Schedule and Preparation timing, but is not itself a Schedule or Preparation.
• First-release Product Usage Events are Workflow Milestone Events, not every tap or raw navigation step.
• First-release Workflow Milestone Events cover analytics preference, onboarding, authentication, schedule, notification permission, alarm, and schedule-finish outcomes.
• Provider Authentication Completed precedes OnTime Session Established during Apple or Google sign-in.
• Provider Authentication Completed does not mean the user is signed in to OnTime.
• The signed-in app experience begins only after OnTime Session Established.
• A Product Usage Event may include Analytics Event Parameters such as workflow, result, stable error category, coarse count, coarse duration, platform, or app version.
• An Analytics Event Parameter must not contain user-authored text, direct identifiers, tokens, raw exception strings, request bodies, or response bodies.
• A Product Usage Event uses a stable snake_case name and includes a schema version.
• A changed Product Usage Event meaning requires a new event name or schema version.
• A Schedule may have one Preparation for that specific commitment.
• A Preparation contains zero or more Preparation Steps in user-defined order.
• A user's default Preparation may be applied to a Schedule and then changed for that Schedule.
• A Schedule has a Preparation whose Preparation Duration contributes to preparation-start timing.
• Preparation Duration, move time, and Schedule Spare Time are distinct schedule timing inputs.
• User-facing copy should call a scheduled notification a Schedule Notification, not an Alarm, unless it opens an OnTime screen without the user first tapping a notification.
• A Schedule has one active Preparation selection.
• A Preparation contains one or more ordered Preparation Steps.
• A Preparation Start Moment is derived from the Schedule, Preparation, movement time, and spare time.
• A Schedule Preparation Session belongs to exactly one Schedule.
• An Early Start Session is a Schedule Preparation Session started before the Preparation Start Moment.
• A Schedule Notification may prompt the user to begin a Schedule Preparation Session at the Preparation Start Moment.
• The profile setting for upcoming schedule preparation delivery should be called Schedule Notification Setting.
• On iOS, user-facing copy may say Alarm only when OnTime can deliver an iOS AlarmKit Alarm.
• iOS permission prompts should use alarm language only when requesting an iOS AlarmKit Alarm; otherwise they should use notification language.
• When an iOS AlarmKit Alarm is unavailable or denied but notifications are allowed, user-facing status should say notification rather than expose Time Sensitive terminology.
• A Schedule Notification should use Precise Notification Timing when the user's device supports it and Exact Timing Permission is granted.
• A Fallback Notification may back up a Schedule Notification, but it does not satisfy Exact Timing Permission.
• On Android, OnTime should use an Android Schedule Notification unless Alarm policy approval is available.
• Android permission prompts for scheduled preparation delivery should say notification, not alarm, unless OnTime is requesting or explaining an Alarm experience.
• Android Exact Timing Permission copy should explain that the permission is needed to notify the user at the exact preparation time.
• Exact Timing Permission is granted only when the device reports it as granted, not when the user taps a permission request button.
• No Scheduled Notification does not indicate a missing Exact Timing Permission.
• Missing Exact Timing Permission means Approximate Notification Timing, not disabled notifications, when notification permission is granted.
• Android with Precise Notification Timing should show Precise Notification Status.
• Android without Precise Notification Timing but with notification permission should show Notification Status.
• iOS with an iOS AlarmKit Alarm should show Alarm Status.
• iOS without an available iOS AlarmKit Alarm but with notification permission should show Notification Status.
• No Scheduled Notification should be the user-facing empty state across platforms, even when future delivery may use an Alarm.
• A Preparation Run records Preparation Action Events, not timer ticks or automatic step transitions.
• A Preparation Action Event may represent starting preparation, skipping a preparation step, or finishing preparation.
• A Preparation Run begins when the user performs the starting Preparation Action Event.
• A skipped preparation step ends at the skip Preparation Action Event time; its unused planned duration is not treated as elapsed preparation time.
• The current step and completion state of a Preparation Run are derived from its starting action, user-performed Preparation Action Events, and the current time.
• Automatic step transitions are derived states, not Preparation Action Events.
• A Preparation Run must not outlive the scheduled commitment it belongs to.
• Active first-release Analytics Purposes are product improvement, debugging and operations, and experimentation.
• A first-release Experiment must not be used for marketing targeting, sensitive segmentation, or personalized treatment.
• Marketing and personalization are Deferred Analytics Purposes.
• A Product Usage Event belongs to a Pseudonymous Analytics Subject, using an internal user or analytics identifier for signed-in use and an installation identifier before sign-in.
• A Pseudonymous Analytics Subject must not be an email address, display name, OAuth identifier, FCM token, or raw personal content value.
• The first-release Analytics Preference is opt-out for active Analytics Purposes.
• A disabled Analytics Preference stops future optional Product Usage Events.
• Before sign-in, the Analytics Preference is installation-scoped.
• After sign-in, the Analytics Preference is account-scoped and should apply across the user's signed-in devices.
• Before sign-in, a Product Usage Event may be associated only with an installation-scoped Pseudonymous Analytics Subject.
• After sign-in, future Product Usage Events may be associated with a signed-in Pseudonymous Analytics Subject.
• After sign-out, future Product Usage Events return to an installation-scoped Pseudonymous Analytics Subject.
• Account deletion stops future user-linked Product Usage Events and may retain historical analytics only in aggregate or de-identified form.
• A first-release Analytics Provider may receive Product Usage Events only after privacy, Data Safety, retention, and deletion responsibilities are approved.

Example dialogue

Dev: "Should the analytics event include the schedule note so we can understand why users are late?" Domain expert: "No. A Product Usage Event can say a schedule was finished late, but it must not include the user's raw note."

Dev: "If the user taps Start before the scheduled notification, is that a separate schedule run?" Domain expert: "No - it is an Early Start Session, which is still the Schedule Preparation Session for that Schedule."

Dev: "Can a Schedule Notification replace the Schedule if the user taps it?" Domain expert: "No. The Schedule Notification only prompts preparation for the Schedule; the Schedule remains the planned commitment."

Flagged ambiguities

• "User" was overloaded as both the human actor and stored profile; resolved: use OnTime User for the account/profile concept and plain user only for the person performing an action.
• "Schedule" was used near notification and alarm flows; resolved: a Schedule is the planned commitment, while notifications and alarms are delivery experiences for preparation timing.
• "Preparation state" was ambiguous between step progress and display styling; resolved: Preparation Step progress belongs to preparation language, while visual labels should not redefine the domain.
• "User activities" was used broadly; resolved: the canonical term is Product Usage Event, and raw personal content is out of scope.
• "Analytics" was used to include all possible purposes; resolved: marketing and personalization are deferred, not first-release purposes.
• "User identity" for analytics was ambiguous; resolved: analytics uses a Pseudonymous Analytics Subject, not directly identifying user data.
• "Consent" was ambiguous for analytics; resolved: first-release analytics is opt-out with a user-visible Analytics Preference.
• "Third party" was ambiguous for analytics; resolved: the canonical term is Analytics Provider.
• "Event taxonomy" was broad; resolved: first-release analytics tracks Workflow Milestone Events only.
• "Event payload" was too open-ended; resolved: events use allowlisted Analytics Event Parameters only.
• "Schedule preparation session" was implicit in code but not in the glossary; resolved: the canonical term is Schedule Preparation Session, with Early Start Session for sessions started before the Preparation Start Moment.
• "Login completed" was ambiguous for Apple and Google sign-in; resolved: external account prompt completion is Provider Authentication Completed, while usable OnTime sign-in is OnTime Session Established.
• "Preparation" was ambiguous between the user's fallback steps and a schedule-specific edited set; resolved: use Default Preparation for the fallback and Custom Preparation for the schedule-specific version.
• "Alarm permission" was ambiguous between Exact Timing Permission and notification permission; resolved: notification permission may enable a Fallback Notification, but does not mean Exact Timing Permission is granted.
• "Pending" was ambiguous for notification status; resolved: the canonical state is No Scheduled Notification when notifications are enabled but no upcoming Schedule Notification is armed.
• "Allowed" was ambiguous for permission requests; resolved: a request action is not the same as granted Exact Timing Permission.
• "Native alarm" was ambiguous on Android; resolved: Android can use an Android Schedule Notification without promising an Alarm.
• "Fallback" was ambiguous as either a backup delivery path or permission bypass; resolved: Android's notification-only path should not be labeled fallback when it is the intended policy-safe path.
• "Notification-only alarm" was ambiguous as either approximate or precise; resolved: Android should keep Precise Notification Timing while using an Android Schedule Notification presentation.
• "Notification" was ambiguous as either a user-facing alarm concept or a platform presentation; resolved: user-facing copy should say Schedule Notification unless the experience is an Alarm.
• "Allow alarms" was ambiguous on Android; resolved: permission prompts should say notifications when the resulting user experience is notification-based.
• "Denied exact timing" was ambiguous as either disabled delivery or degraded delivery; resolved: with notification permission granted, it means Approximate Notification Timing.
• "Schedule alarm setting" was ambiguous after Android moved to notification-based delivery; resolved: the profile control is Schedule Notification Setting.
• "iOS alarm" was ambiguous across OS versions; resolved: iOS copy may say Alarm only when iOS AlarmKit Alarm is available.
• "iOS alarm permission" was ambiguous across OS versions; resolved: iOS permission prompts use alarm language only for iOS AlarmKit Alarm.
• "Time Sensitive" was too platform-specific for default user-facing status; resolved: fallback iOS delivery should be called notification.
• "Status label" was ambiguous across platforms; resolved: Android uses precise notification or notification status, while iOS uses alarm status only for iOS AlarmKit Alarm.
• "No scheduled alarm" was too capability-specific for an empty state; resolved: use No Scheduled Notification across platforms.
• "Step action events" was ambiguous as either user actions or automatic timer movement; resolved: the canonical term is Preparation Action Event, and automatic step transitions are derived rather than recorded as events.
• "Preparation chain" describes storage reconstruction, not product language; resolved: the domain concept is an ordered Preparation made of Preparation Steps.
• "Total duration" was ambiguous between Preparation Duration and the broader preparation-start timing calculation; resolved: Preparation Duration is steps only, while move time and Schedule Spare Time are separate inputs.