Contact Detail & Management
Feature Detail
Description
This feature delivers full contact profile management including viewing detailed contact information, editing contact records, and maintaining structured notes tied to each contact. Coordinators can manage custom fields that vary per organisation (supported by the organisation labels system), and peer mentors can view contact details relevant to their assigned work. Contact notes provide a chronological record of interactions, supporting continuity of care across multiple peer mentors or coordinators. The edit flow is designed as a step-by-step form to minimise cognitive load for users with accessibility needs.
Analysis
Accurate and accessible contact records are foundational to the quality of peer mentor work. Without structured contact management, organisations rely on fragmented Word documents and informal notes, leading to information loss when volunteers change and inconsistent support quality. For organisations like Blindeforbundet, where a formalised report structure after home visits is required (covering health status, course interest, assistive device situation, and next steps), a structured contact detail screen directly enables regulatory compliance and quality assurance. The notes system creates an auditable record that supports Bufdir reporting requirements and internal quality reviews.
Contact detail and edit screens are implemented as separate routes with deep-link support for navigation from other screens. The edit screen uses a reactive form built with Flutter's Form widget and custom AppTextField components, with field-level validation and auto-save drafts stored in SQLite. Custom fields are driven by the organisation labels system, fetching field definitions from Supabase at load time. Notes are stored as timestamped records linked to the contact and the author's user ID, rendered in a scrollable timeline widget. All text content must be HTML-escaped before rendering. RLS policies on Supabase restrict note visibility to authorised roles within the same organisation. The feature integrates with the encrypted task assignment feature to surface relevant assignment context on contact detail pages.
Dependencies
Definition of Done
Components (6)
User Stories (19)
As a As a user
I want I want to see all organisation-specific custom fields defined for my organisation displayed on a contact's profile, rendered with their correct labels and current values
So that So that I can access structured, organisation-relevant information about a contact (such as assistive device situation, course interest, or health status) without needing to rely on informal notes for structured data
- Given an organisation has defined 5 custom fields, when a user opens a contact detail screen, then all 5 fields are displayed with their organisation-defined labels and current values
- Given a custom field has no value set for the contact, when the field is rendered, then a clear 'Not set' or equivalent placeholder is shown instead of a blank space
- Given field definitions are fetched from Supabase, when the network is slow, then a loading skeleton is displayed in place of the fields while data is loading
- +2 more
As a As a user
I want I want my in-progress contact edit to be automatically saved as a local draft at regular intervals so that if I am interrupted — by a phone call, app switch, or connection loss — my work is not lost
So that So that I can confidently edit contact records on a smartphone in the field without anxiety about losing partially entered data
- Given a user is editing a contact and has made changes, when 10 seconds of inactivity passes, then the form state is saved to SQLite and a 'Draft saved' indicator briefly appears
- Given a user has a draft saved and navigates back from the edit screen without submitting, when they return to the edit screen for the same contact, then their draft data is pre-populated in the form
- Given a user cancels editing and confirms discard in the confirmation dialog, when they later return to the edit screen, then no draft is restored and a blank form is shown
- +2 more
As a As a user
I want I want to navigate directly to a specific contact's detail screen by tapping a contact reference in an activity log, assignment inbox, or notification, without having to search through the contacts list manually
So that So that I can move efficiently between related screens in my workflow — for example, going from an assignment dispatch directly to the contact it relates to — without losing context
- Given a user taps a contact reference in the assignment inbox, when the navigation resolves, then the Contact Detail Screen for that contact opens with all fields populated
- Given a user opens a contact via deep-link, when they tap the back button, then they are returned to the originating screen at the same scroll position
- Given a deep-link references a contact ID that does not exist or the user does not have permission to view, when navigation is attempted, then a friendly error screen is shown with an option to return to the contacts list
- +2 more
As a As a user
I want I want to be able to read previously loaded contact notes and add new notes even when I have no internet connection, with the new notes automatically synchronised when connectivity returns
So that So that I can complete my post-visit notes immediately after a home visit even in areas with poor connectivity, without being blocked by a network requirement
- Given a user has previously viewed a contact's notes while online, when they open the same contact while offline, then cached notes are displayed with an offline status banner
- Given a user writes a note while offline, when they submit it, then the note is stored locally with a pending indicator and appears immediately in the timeline
- Given connectivity is restored after offline note creation, when the sync runs, then pending notes are submitted to Supabase and the pending indicator is removed
- +2 more
As a As a user
I want I want to see all organisation-specific custom fields defined for my organisation displayed on a contact's profile, rendered with their correct labels and current values
So that So that I can access structured, organisation-relevant information about a contact (such as assistive device situation, course interest, or health status) without needing to rely on informal notes for structured data
- Given an organisation has defined 5 custom fields, when a user opens a contact detail screen, then all 5 fields are displayed with their organisation-defined labels and current values
- Given a custom field has no value set for the contact, when the field is rendered, then a clear 'Not set' or equivalent placeholder is shown instead of a blank space
- Given field definitions are fetched from Supabase, when the network is slow, then a loading skeleton is displayed in place of the fields while data is loading
- +2 more
As a As a user
I want I want my in-progress contact edit to be automatically saved as a local draft at regular intervals so that if I am interrupted — by a phone call, app switch, or connection loss — my work is not lost
So that So that I can confidently edit contact records on a smartphone in the field without anxiety about losing partially entered data
- Given a user is editing a contact and has made changes, when 10 seconds of inactivity passes, then the form state is saved to SQLite and a 'Draft saved' indicator briefly appears
- Given a user has a draft saved and navigates back from the edit screen without submitting, when they return to the edit screen for the same contact, then their draft data is pre-populated in the form
- Given a user cancels editing and confirms discard in the confirmation dialog, when they later return to the edit screen, then no draft is restored and a blank form is shown
- +2 more
As a As a user
I want I want to navigate directly to a specific contact's detail screen by tapping a contact reference in an activity log, assignment inbox, or notification, without having to search through the contacts list manually
So that So that I can move efficiently between related screens in my workflow — for example, going from an assignment dispatch directly to the contact it relates to — without losing context
- Given a user taps a contact reference in the assignment inbox, when the navigation resolves, then the Contact Detail Screen for that contact opens with all fields populated
- Given a user opens a contact via deep-link, when they tap the back button, then they are returned to the originating screen at the same scroll position
- Given a deep-link references a contact ID that does not exist or the user does not have permission to view, when navigation is attempted, then a friendly error screen is shown with an option to return to the contacts list
- +2 more
As a As a Coordinator
I want I want to edit the values of organisation-specific custom fields for a contact directly within the edit contact form, using the appropriate input type for each field
So that So that structured, organisation-required data is captured accurately in designated fields rather than buried in free-text notes, ensuring consistent data quality across all contacts
- Given a coordinator opens the edit contact screen, when custom fields are loaded, then each field is rendered as an editable input with the correct input type (text input, dropdown, or date picker)
- Given a coordinator enters an invalid value in a custom field (e.g., text in a date field), when they attempt to advance or submit, then field-level validation blocks progression with a descriptive error message
- Given a peer mentor opens the edit contact screen, when custom fields are loaded, then custom fields are rendered as read-only and no edit affordance is presented
- +2 more
As a As a user
I want I want to be able to read previously loaded contact notes and add new notes even when I have no internet connection, with the new notes automatically synchronised when connectivity returns
So that So that I can complete my post-visit notes immediately after a home visit even in areas with poor connectivity, without being blocked by a network requirement
- Given a user has previously viewed a contact's notes while online, when they open the same contact while offline, then cached notes are displayed with an offline status banner
- Given a user writes a note while offline, when they submit it, then the note is stored locally with a pending indicator and appears immediately in the timeline
- Given connectivity is restored after offline note creation, when the sync runs, then pending notes are submitted to Supabase and the pending indicator is removed
- +2 more
As a As a user
I want I want form fields to validate my input in real time as I type or move between fields, showing clear inline error messages before I attempt to submit
So that So that I can correct mistakes immediately while the context is fresh, rather than discovering validation errors after submitting an entire form
- Given a user enters a value in a required field and then clears it, when the field loses focus, then an inline 'Required' error message appears below the field
- Given a user enters a malformed phone number, when the field loses focus, then an inline format error is displayed with an example of the expected format
- Given a user attempts to advance to the next step with validation errors present, when they tap the next button, then advancement is blocked and all errors on the current step are highlighted
- +3 more
As a As a user
I want I want to open a contact's detail screen and see all their information in one place — personal details, organisation-specific custom fields, linked assignment context, and a summary of recent notes
So that So that I have the full picture of the contact before and after a peer support interaction, enabling better-quality, more personalised support
- Given a peer mentor navigates to a contact from their contacts list, when the detail screen loads, then all personal details, custom fields, and the most recent 3 notes are displayed within 2 seconds
- Given a coordinator views any contact in their organisation, when the detail screen loads, then all fields including coordinator-only fields are visible and correctly labelled
- Given any user on the contact detail screen, when a screen reader is active, then every field has a descriptive semantic label and sensitive field audio warnings are announced
- +3 more
As a As a user
I want I want to add a timestamped note to a contact's record directly from the contact detail screen, capturing the key outcomes of an interaction
So that So that a structured, chronological record of all interactions is maintained for continuity of care when multiple mentors or coordinators interact with the same contact
- Given a user taps the add-note button on a contact detail screen, when the note input form appears, then it is focussed and ready for input without requiring additional taps
- Given a user submits a non-empty note, when the Contact Notes Repository saves it, then the note appears immediately at the top of the notes timeline with the correct author name and current timestamp
- Given a user submits an empty note, when they tap save, then submission is blocked and an inline error message is shown
- +3 more
As a As a user
I want I want to scroll through a chronological timeline of all notes added to a contact, with each entry showing the author, date, and note content
So that So that I can quickly understand the history of interactions with a contact and pick up where a previous mentor left off without having to ask colleagues for context
- Given a contact has multiple notes, when the notes timeline renders, then notes appear in reverse-chronological order with author name, date, and note body for each entry
- Given a contact has more than 20 notes, when the user scrolls to the bottom of the visible list, then additional notes are loaded lazily without a full screen reload
- Given the app is offline, when a user opens the notes timeline, then locally cached notes are displayed with a banner indicating potential staleness
- +3 more
As a As a user
I want I want to edit a contact's information using a step-by-step form that validates each field before I proceed and clearly shows my progress through the edit flow
So that So that I can update contact records accurately without feeling overwhelmed by a long form, and so that invalid data is caught immediately rather than on submission
- Given a user opens the edit contact screen, when the screen loads, then organisation-specific custom fields are fetched from Supabase and rendered with the correct input type (text, select, or date) within 2 seconds
- Given a user enters an invalid value in a field (e.g., malformed phone number), when they attempt to advance to the next step, then an inline error message is shown on the invalid field and progression is blocked
- Given a user partially completes the edit form and navigates away, when they return to the edit screen for the same contact, then their draft data is restored from local SQLite storage
- +3 more
As a As a user
I want I want form fields to validate my input in real time as I type or move between fields, showing clear inline error messages before I attempt to submit
So that So that I can correct mistakes immediately while the context is fresh, rather than discovering validation errors after submitting an entire form
- Given a user enters a value in a required field and then clears it, when the field loses focus, then an inline 'Required' error message appears below the field
- Given a user enters a malformed phone number, when the field loses focus, then an inline format error is displayed with an example of the expected format
- Given a user attempts to advance to the next step with validation errors present, when they tap the next button, then advancement is blocked and all errors on the current step are highlighted
- +3 more
As a As a user
I want I want to open a contact's detail screen and see all their information in one place — personal details, organisation-specific custom fields, linked assignment context, and a summary of recent notes
So that So that I have the full picture of the contact before and after a peer support interaction, enabling better-quality, more personalised support
- Given a peer mentor navigates to a contact from their contacts list, when the detail screen loads, then all personal details, custom fields, and the most recent 3 notes are displayed within 2 seconds
- Given a coordinator views any contact in their organisation, when the detail screen loads, then all fields including coordinator-only fields are visible and correctly labelled
- Given any user on the contact detail screen, when a screen reader is active, then every field has a descriptive semantic label and sensitive field audio warnings are announced
- +3 more
As a As a user
I want I want to add a timestamped note to a contact's record directly from the contact detail screen, capturing the key outcomes of an interaction
So that So that a structured, chronological record of all interactions is maintained for continuity of care when multiple mentors or coordinators interact with the same contact
- Given a user taps the add-note button on a contact detail screen, when the note input form appears, then it is focussed and ready for input without requiring additional taps
- Given a user submits a non-empty note, when the Contact Notes Repository saves it, then the note appears immediately at the top of the notes timeline with the correct author name and current timestamp
- Given a user submits an empty note, when they tap save, then submission is blocked and an inline error message is shown
- +3 more
As a As a user
I want I want to scroll through a chronological timeline of all notes added to a contact, with each entry showing the author, date, and note content
So that So that I can quickly understand the history of interactions with a contact and pick up where a previous mentor left off without having to ask colleagues for context
- Given a contact has multiple notes, when the notes timeline renders, then notes appear in reverse-chronological order with author name, date, and note body for each entry
- Given a contact has more than 20 notes, when the user scrolls to the bottom of the visible list, then additional notes are loaded lazily without a full screen reload
- Given the app is offline, when a user opens the notes timeline, then locally cached notes are displayed with a banner indicating potential staleness
- +3 more
As a As a user
I want I want to edit a contact's information using a step-by-step form that validates each field before I proceed and clearly shows my progress through the edit flow
So that So that I can update contact records accurately without feeling overwhelmed by a long form, and so that invalid data is caught immediately rather than on submission
- Given a user opens the edit contact screen, when the screen loads, then organisation-specific custom fields are fetched from Supabase and rendered with the correct input type (text, select, or date) within 2 seconds
- Given a user enters an invalid value in a field (e.g., malformed phone number), when they attempt to advance to the next step, then an inline error message is shown on the invalid field and progression is blocked
- Given a user partially completes the edit form and navigates away, when they return to the edit screen for the same contact, then their draft data is restored from local SQLite storage
- +3 more