External Services Reference

Attendrix integrates with five primary external service providers to deliver database hosting, serverless computing, push notifications, calendar syncing, and astronomy data caching.

---

1. Supabase Cloud (AWS ap-south-1)

• Role: Primary relational database, authentication provider, connection pooler, PGMQ message broker, and serverless compute host.
• Region: ap-south-1 (Mumbai, India) to ensure sub-30ms latency for Indian university student networks.
• Protocols:
  • PostgREST: Automatic RESTful HTTP endpoints mapping directly to PostgreSQL tables, views, and stored procedures with JWT authentication.
  • Connection Pooling: Supavisor running on port 6543 (transaction pooling) and port 5432 (session pooling).
  • Supabase Vault: Encrypted credential storage for Google OAuth refresh tokens.

---

2. Google Calendar API & OAuth 2.0

• Role: Bi-directional academic calendar synchronization.
• Scopes Requested:
  • https://www.googleapis.com/auth/calendar: Read/write access to user calendars for automated class creation, update, and cancellation.
  • https://www.googleapis.com/auth/userinfo.email: Read primary email address to associate Google identity.
• Authentication Protocol: OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange, S256).
• Secondary Calendar Strategy: Creates a dedicated secondary calendar named "Attendrix" with time zone "Asia/Kolkata". Timetable events are never injected into the user's personal default calendar, allowing safe deletion upon disconnection.

---

3. OneSignal Push Notifications

• Role: Device push delivery across Android and iOS platforms.
• Client Integration: onesignal_flutter SDK initializes upon app boot, acquires a device subscription_id, and calls register_device RPC.
• Backend Dispatch Protocol: Deno Edge Function notify-worker posts HTTP JSON payloads to https://onesignal.com/api/v1/notifications in chunks of up to 2,000 device tokens.
• Invalid Token Handling: OneSignal response errors containing invalid_player_ids trigger immediate database deactivation (is_active = false) in public.notification_devices to keep target queues lean.

---

4. NASA Astronomy Picture of the Day (APOD)

• Role: Daily astronomical photograph and educational caption displayed on the student dashboard greeting view.
• Endpoint: https://api.nasa.gov/planetary/apod
• Ingestion: Deno Edge Function fetch-apod runs nightly via cron schedule, fetches the day's image URL, HD URL, title, explanation, and copyright, and upserts the row into public.apod.
• Offline Resiliency: The mobile client fetches from public.apod via get_latest_apod and caches the data locally in FFAppState. If offline, the last cached image renders seamlessly.

---

5. OpenRouteService (Pedestrian Routing Matrix)

• Role: Campus pedestrian distance and duration matrix generation.
• Dataset Generation: Used during campus mapping to compute distances between 152,904 coordinate pairs across all campus buildings, hostel blocks, dining halls, and academic departments.
• Runtime Dependency: Zero. All routes are precomputed and published into public.routing_dataset_routes, downloaded once by the client, and resolved completely offline with 0 runtime HTTP requests.