Synced from the repo — do not edit here

Canonical source: docs/claude/chat-notifications.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

Chat & Messaging + Notifications

Chat Architecture

Real-time chat between staff and clients, plus AI chat for client self-service.

Chat Types

Type	Participants	Use Case
Coach Chat	Staff <-> Client	Direct messaging, care coordination
AI Chat	Client <-> AI	Self-service health questions
Group Chat	Multiple staff + clients	Care team communication

Storage Structure

Simple Chat (legacy, single document):

chats/{clientUid}
  - name: string
  - email: string
  - clinicId: string
  - messages: Message[]

Scalable Chat (newer, subcollections):

chatsv2/{conversationId}
  - type: 'coach' | 'ai' | 'group'
  - participants: string[]
  - clinicId: string
  - createdAt: timestamp
  /messages/{messageId}
    - content: string
    - authorId: string
    - authorRole: 'patient' | 'coach' | 'ai'
    - timestamp: timestamp
    - readBy: string[]
    - media?: MediaItem[]

Message Structure

interface ChatMessage {
  time: string;                    // ISO timestamp
  content: string;
  author: {
    id: string;
    name: string;
    email?: string;
    role: 'patient' | 'coach' | 'ai';
  };
  media?: {
    uuid: string;
    mimeType: string;
    name: string;
    url: string;
  }[];
  hide: boolean;                   // Soft delete
  readReceipts: string[];
  isChatSystemMessage: boolean;
  threadId?: string;               // For replies
  replyToTime?: string;
  quote?: string;                  // Quoted text
}

File Sharing

• Supported formats: PDF, JPG, JPEG, PNG, GIF, WebP
• Size limit: 25MB per file
• Storage: Firebase Storage with signed URLs
• Path: chats/{conversationId}/attachments/{uuid}

Chat Settings

Per-clinic chat configuration (clinicsv2/{clinic} fields):

• humanChatEnabled - Allow staff <-> client chat
• humanChatClientReplyEnabled - Clients can send messages
• aiChatEnabled - Allow AI chat for clients
• clientAppChat - Chat visible in client app
• humanChatInboxOnly - Read-only mode

Key Files

File	Purpose
functions_chat.py	Chat backend functions
functions_notifications.py	Push notifications for chat
basisflow-web/components/chat/ChatDrawer.tsx	Staff chat UI
basisweb/app/portal/chat/page.tsx	Client portal chat
basishybrid/.../route_chat.dart	Mobile client chat
basiscoreui/.../service_chat.dart	Shared chat service

---

Notifications

Comprehensive notification system covering email, push, and in-app notifications across the platform.

Notification Types

Type	Trigger	Email	Push	In-App
Appointment Booked	New booking	+ iCal	Yes	Yes
Appointment Reminder	24h before	Yes	Yes	-
Appointment Cancelled	Cancellation	+ iCal	Yes	Yes
Waitlist Confirmed	Added to waitlist	Yes	-	-
Waitlist Available	Spot opened	Yes	Yes	-
Client Invited	Staff invites client	Yes	-	-
Welcome Email	Account created	Yes	-	-
Onboarding Forms	Forms due	Yes	-	-
New Chat Message	Staff/AI message	-	Yes	Yes
Lab Results	Results available	-	Yes	-
Protocol Activity	Activity due	-	Yes	Yes
Health Windows	Coffee/meal/winddown	-	Yes	Yes
CGM Reminders	Sensor expiring/scan	-	Yes	Yes

Email Notifications

File: functions_appointment_emails.py

Templates

Template	Purpose
APPOINTMENT_BOOKING_TEMPLATE	Booking confirmation
APPOINTMENT_CANCELLATION_TEMPLATE	Cancellation notice
WAITLIST_CONFIRMATION_TEMPLATE	Waitlist confirmation
WAITLIST_AVAILABLE_TEMPLATE	Spot available notification

Key Functions

Function	Purpose
send_appointment_confirmation_email	Booking confirmation + iCal
send_appointment_cancellation_email	Cancel notice + iCal update
send_waitlist_confirmation_email	Waitlist add confirmation
resend_welcome_email	Re-send client invite

iCal Integration

Emails include iCal (ICS) attachments:

• Auto-adds to calendar on open
• Cancellations include CANCELLED status
• utils_ical.py - iCal generation utilities

Branded Email Domains

Clinics can use custom sender domains:

• Configured via clinicsv2/{clinic}/config/email
• DNS verification via MailerSend
• verificationStatus: 'verified' + useBranded: true

Push Notifications

Files: functions_appointment_notifications.py, functions_notifications.py

Appointment Push Flow

clinic_service -> send_appointment_booking_notifications()
  -> Get device tokens (users/{uid}.deviceToken)
  -> messaging.send_all(messages)
  -> Push notification on device

Chat Push

Firestore triggers detect new messages:

• coach_notification_handler - Global chat
• clinic_coach_notification_handler - Clinic-scoped chat

Logic:

1. Compare before/after snapshots for new messages
2. Validate message author (id, role)
3. Route to opposite party (coach -> user, user -> coaches)
4. Send via FCM with thread grouping

In-App Notifications (Basis Hybrid)

Files: service_notifications.dart, service_notifications_io.dart, service_notification_manager.dart

Notification Types

Type	Description
windowCoffee	Coffee window started
windowPeak1 / windowPeak2	Energy peak windows
windowWinddown	Wind-down time
windowMeal	Meal window
glucoseScanReminder	CGM scan reminder
glucoseSensorExpiration	CGM sensor expiring
reminder	Habit/event reminder
coach	Coach message

Scheduling Features

• iOS 64-notification limit handling
• Timezone-aware scheduling
• Cooldown management (prevent spam)
• Automatic rescheduling on user preference changes

Deep Linking

Notifications link to relevant screens:

• Health windows -> Calendar view
• CGM reminders -> CGM manager modal
• Chat messages -> Chat screen

Device Token Management

// users/{uid}
{
  deviceToken: string;     // FCM token
  devicePlatform: string;  // 'ios' | 'android'
  lastTokenUpdate: timestamp;
}

• Updated on app launch and token refresh
• Validated before sending (invalid tokens removed)
• Platform-specific handling (APNS for iOS)

APNS Configuration (iOS)

messaging.APNSConfig(
    payload=messaging.APNSPayload(
        messaging.Aps(
            thread_id='appointments',  # Group by type
            sound='default',
            badge=1,
        ),
        **custom_data
    )
)

Key Files

File	Purpose
functions_appointment_emails.py	Email notifications + iCal
functions_appointment_notifications.py	Push for appointments
functions_notifications.py	Push for chat
functions_email.py	Email sending core
email_templates.py	HTML email templates
utils_ical.py	iCal generation
basishybrid/.../service_notifications.dart	In-app notifications
basishybrid/.../service_notifications_io.dart	Native push handling