Timezone-Aware Health Record Reminders
Project: FamilyShell LLP — Health Records module
Area: Domain modeling, timezone handling, FastAPI, MongoDB, scheduling
The Challenge
The Health Records module allows a user to create a health record for themselves, a family member, or even another person.
This means a health record has an important distinction between thecreator and the subject.
While investigating the reminder system, I found that reminders were using the current user's local timezone when converting a reminder time to UTC.
The system was also sending the reminder to the creator, even though the reminder could belong to the health-record subject.
Why This Was an Architectural Problem
Consider a user creating a reminder for a health-record subject who lives in another country.
If the user enters 9:00 AM, the intended meaning should be 9:00 AM in the subject's timezone, not 9:00 AM in the creator's timezone.
Using the creator's timezone could therefore cause the reminder to be delivered at the wrong local time for the person the reminder concerns.
This made it clear that the reminder system was using the wrong entity as the source of timezone information.
Research and Solution
I explained these architectural issues in a team discussion and was asked to research common approaches to timezone handling.
Based on that research and the application's domain requirements, I introduced a preferred timezone field for users.
The timezone is associated with the user who is the subject of the health record. Existing users were assigned a default timezone so that the change would remain compatible with existing application data, while users can update their timezone later.
Moving Validation to the Backend
I also moved timezone validation from the Flutter frontend to the FastAPI backend.
The reason is that validation affecting application correctness should have a backend source of truth. Client-side validation can improve the user experience, but the backend should not rely on the client to enforce important data rules.
New Reminder Flow
With the updated architecture, reminder creation follows the subject of the health record.
- The backend identifies the health-record subject.
- The backend retrieves the subject's current preferred timezone.
- The reminder's local day and clock time are interpreted in that timezone.
- The resulting datetime is converted to UTC.
- The UTC value is stored in MongoDB.
- The scheduler uses the stored UTC value to trigger the reminder.
Engineering Principle
The main lesson from this challenge was that correct technical behavior depends on correctly modeling the domain.
The system should not assume that the person performing an action is always the person the action concerns. Once the distinction between creator and subject was made explicit, the correct timezone and reminder behavior became much clearer.
This also reinforced my preference for keeping important validation and business rules on the backend, where they can be applied consistently regardless of which client is using the API.