Supabase Edge Functions

Attendrix executes serverless logic on the Supabase Edge Functions runtime (powered by Deno and V8 isolates). Edge functions handle asynchronous background queues, Google OAuth 2.0 token negotiations, OneSignal push broadcasts, and scheduled NASA APOD synchronization.

graph TD
    Client["Flutter Mobile Client"] -->|HTTPS / OAuth| EF_Auth["google-calendar-auth"]
    Client -->|HTTPS / JWT| EF_Disc["google-calendar-disconnect"]
    
    Cron["pg_cron / External Evaluator"] -->|Trigger| EF_Eval["notify-scheduled-evaluator"]
    Cron -->|Nightly| EF_Apod["fetch-apod"]
    
    EF_Eval -->|pgmq_send| DB_NQ[("public.notification_queue (PGMQ)")]
    DB_Trig["DB Trigger: Statement Coalesce"] -->|pgmq_send| DB_GQ[("public.gcal_sync_queue (PGMQ)")]
    
    DB_NQ -->|pgmq_read| EF_Notif["notify-worker"]
    DB_GQ -->|pgmq_read| EF_GCal["google-calendar-sync-worker"]
    
    EF_Notif -->|REST API| OneSignal["OneSignal Push Delivery"]
    EF_GCal -->|OAuth v3 REST| GCalAPI["Google Calendar API"]

Active Functions Inventory

Deep Dive: google-calendar-sync-worker

The google-calendar-sync-worker function reconciles scheduled classes with the student's Google Calendar account without creating duplicate events or generating unnecessary API calls.

1. Deterministic Event IDs

Google Calendar event IDs must be unique per calendar and conform to ^[a-v0-9]{5,1024}$. Attendrix derives deterministic IDs via SHA-256 and base32 hex encoding:

const raw = `${userId}:${classId}`;
const hex = await sha256Hex(raw);
const base32 = toBase32Hex(hex);
const googleEventId = `attendrix${base32.substring(0, 40)}`;

This guarantees idempotency: retrying a sync job for the same class and user always targets the exact same Google Calendar event ID.

2. Distributed Leases & Serialization

To avoid concurrent modifications to a user's Google Calendar:

• The worker calls acquire_gcal_user_sync_lease(userId, workerId, 45).
• If another worker currently holds an unexpired lease, the worker yields immediately.
• Upon completion or failure, the lease is released via release_gcal_user_sync_lease.

3. PGMQ Visibility & Poison Pills

• Claims batches of up to 10 messages with a 180-second visibility timeout (vt = 180).
• If read_ct >= 5 (max attempts reached), the message is classified as a poison pill and archived to the dead-letter queue via pgmq_archive.
• Failed messages receive exponential backoff up to 1 hour:

const vtOffset = Math.min(60 * Math.pow(2, readCt), 3600);
await supabase.rpc("pgmq_set_vt", { p_queue_name: "gcal_sync_queue", p_msg_id: msgId, p_vt_offset: vtOffset });

Deep Dive: notify-worker

The notify-worker processes notifications from notification_queue, performing personalization, quiet-hours filtering, and OneSignal batch dispatching.

1. Multi-Tone Personalization Engine

Attendrix personalizes notification copy based on each student's action_tone preference:

• Direct: Neutral, concise, factual.
• Playful: Energetic, emoji-rich, warm.
• Roast: Sarcastic, humorous reminders emphasizing attendance consequences.
• Motivational: Goal-oriented, positive, empowering.

2. Quiet Hours Filtering

Students can configure a quiet hours window (e.g. 22:00:00 to 07:00:00 IST). Non-urgent notifications are suppressed during quiet hours. Only time-sensitive notifications bypass quiet hours:

• class_reminder (10 minutes before lecture)
• class_cancelled
• class_rescheduled
• extra_class_added
• mess_reminder

3. Deduplication & Cross-User Privacy Guard

• Deliveries are logged to public.notification_log with unique constraint (user_id, dedup_key).
• Before dispatching to OneSignal, recipients are grouped by distinct copy and deep link to guarantee personalized tokens (e.g. student first names) never leak across users.