Skip to content

Architecture: UX Definitions

This document defines the User Experience (UX) rules and Presentation Logic that govern how data is displayed to the user. These are distinct from the Data Model (how data is stored) but must be consistent with it.

1. Time Domains & The "User Day"

While the Data Model defines the "User Day" (04:00 AM - 04:00 AM) for storage and aggregation, the UX layer interprets this for display.

The "4 AM Rule" (Display)

  • Logic: Any activity between 00:00 and 03:59 belongs to the previous calendar day.
  • Example: A snack at 2 AM on Tuesday is displayed as "Monday Night" (or just part of Monday's list).
  • Date Selector: When a user selects a date, they are selecting a "User Day".
    • Selecting "Jan 5" means viewing the range Jan 5 04:00 to Jan 6 04:00.

2. Meal Grouping (Breakfast / Lunch / Dinner)

To structure the daily feed, meals are grouped into three fixed time blocks based on their time relative to the User Day.

Time Blocks

These blocks are purely presentational.

Period Start Time (Local) End Time (Local) Note
Breakfast 04:00 11:30 Starts at the "User Day" boundary.
Lunch 11:30 17:00
Dinner 17:00 04:00 (+1) Extends into the next calendar morning.

Empty States

  • Behavior: If a time block contains no meals, it is still rendered (or a placeholder is shown) to give the user a sense of the day's structure.
  • Visual: "Nothing logged" or a subtle dash.

3. Date & Time Selection

Default State ("Now")

  • Behavior: The meal logger defaults to "Now".
  • Logic: The timestamp is generated at the moment of submission.
  • Indicator: A "Clock" icon or text indicating live mode.

Manual Selection

  • Behavior: Users can select a specific past or future time.
  • Granularity: Date + Time (e.g., "Jan 4, 12:30 PM").
  • Reset: A clear action must exist to return to "Now" mode.

Timestamp Persistence

  • Submission: The selected timestamp is passed explicitly to the backend.
  • Aggregation: The backend calculates the UserDate based on this timestamp, ensuring it falls into the correct "User Day" bucket (respecting the 4 AM rule).

4. Advanced Nutrient Display

Dynamic Columns

The "Daily Feed" and "Day Summary" must adapt to the user's active nutrient registry.

  • Scaling:
    • Core Macros (4): Always displayed (Calories, Protein, Carbs, Fat).
    • Extended Nutrients: Displayed as additional columns/rows if they have a non-zero value OR are marked as "Tracking" in settings.
  • Summary Row:
    • The daily summary header will wrap to a second line or use a horizontal scroll if the user tracks > 3 extended nutrients.
    • Format: Label: Value Unit (e.g., "Fiber: 12g").

Registry Visibility

  • Active: Visible in "Add Meal" form and "Settings".
  • Archived:
    • Hidden from "Add Meal" form.
    • Visible in "Settings" (read-only/restore only).
    • Hidden from Dashboard summaries unless historical data exists for that specific day.