Technical Specifications

Architecture Overview

The app is a Flutter client backed by Supabase (auth + Postgres + edge functions). Practice tracking, profiles, and calendar data flow through Supabase, with local notifications for reminders. Below is a high-level architecture diagram:

Release requirements (from current code)

• Supabase project with URL + anon key (baked defaults in main.dart; overridable via --dart-define).
• Supabase tables: devotees (familyMembers JSON, mentor/guide info), daily_tracking (practice logs), mentors, seva_services, and any edge function for vaishnava_calendar data.
• Supabase Auth: email/password + optional TOTP MFA (GoTrue); factors enrollment/verification supported in Settings.
• Local notifications: daily reminder + calendar alerts; on Android falls back to inexact alarms if exact alarms are not permitted.
• iOS/Android build: iOS 13+; Android minSdk from Flutter defaults; App Store/Play builds include Supabase defaults; Android release signing configured via key.properties.
• Data deletion: publish data-deletion.html link for Play/App Store forms.

Flutter UI
  ├─ Screens (stateful widgets)
  │    ├─ Onboarding, Contact, Mentor/Children
  │    ├─ Home (Practice/Overview/Calendar)
  │    └─ Settings (MFA, notifications)
  ├─ Widgets (practice rows, cards, pickers)
  └─ State mgmt: local setState + async calls

Domain/Models
  ├─ Devotee, DevoteeContext, DevoteeDraft
  ├─ DailyTargets (target catalog)
  └─ DailyTracking (per-day saved entries)

Services
  ├─ Supabase (auth, db, functions, MFA)
  ├─ NotificationService (local notifications)
  └─ StatisticsRepository (charts/stats)

Backend (Supabase)
  ├─ Tables: devotees, daily_tracking, mentors, seva_services
  ├─ MFA via Supabase Auth (GoTrue)
  └─ Edge functions: vaishnava_calendar
        

Screens

Onboarding

• Collects name, gender, DOB, spiritual status; sets appGroup (FTM/VOL/KL/FOLK) and ashraya flags.
• Age computed from DOB; targets derived via DevoteeContext → getTargetsForPerson.

Contact/Profile

• Email, phone/WhatsApp, address, education, university picker (sheet with search + “Other”).
• Phone formatter with auto dial code; custom “+” disables auto-prefix.

Mentor & Children

• Mentor/guide from Supabase mentors (active, sort_order asc).
• Children stored in family JSON with relation, DOB, grade, Ashraya participation, consent (<13).
• Youth (≤18) Ashraya → kid Ashraya targets (includes kirtan minutes).

Home

• Profiles: primary + dependents (family JSON; fallback to dependents with parent_id).
• Practice: Japa rounds toggle (youth/adult Shraddhavan/Sevak/Sadhak + kids default) or completion time; reading/hearing; kirtan when target > 0; seva breakdown.
• Overview: progress rings (rounds, association, seva) averaged; association uses read+hear+kirtan capped for OR targets.
• Calendar: Vaishnava days from Edge function; fallback sample; mounted checks on async.

Settings

• Notifications toggle; legal links; support/about; sign out.
• MFA TOTP: enroll (unique friendly name, cleans unverified), show QR/URI/secret, copy/share, verify, disable.

Models & Targets

• Devotee: persisted user; includes familyMembers JSON, appGroup, ashraya flags.
• DevoteeDraft: in-memory onboarding aggregate passed between screens.
• DevoteeContext: ageYears, isInitiated, partOfAshraya, ashrayaLevel, isPrimaryDevotee.
• DailyTargets: per profile target catalog (rounds, reading/hearing, kirtan, seva, programs).
• DailyTracking: per-day entries saved to Supabase (rounds, time, reading/hearing minutes, kirtan minutes, seva hours breakdown, arati/guru-puja flags).

Target Resolution

• Initiated → initiated targets (16 rounds, 30/30 read/hear, 24h seva/month).
• Ashraya levels: Shraddhavan (1 round, 15/15, 2h), Sevak (4, 20/20, 4h), Sadhak (8, 30/30, 8h), Vandana (12, 30/30, 12h), Upasak (16, 45/45, 16h), Charanashraya (16, 60/60, 20h), Full-time Missionary (16, 60/60, 40h).
• Volunteer: 0 rounds, 10/10 read/hear, 12h seva/month.
• Adult default: 4 rounds, 30/30 read/hear, 6h seva/month.
• Kids default (<15, non-Ashraya): 2 rounds, 20/20 read/hear, 15m kirtan, 0h seva.
• Kid Ashraya Shraddhavan: 2 rounds, 15/15, 10m kirtan, 2h seva.
• Kid Ashraya Sevak: 4 rounds, 20/20, 15m kirtan, 4h seva.
• Youth ≤18 in Ashraya (shraddhavan/sevak) also use kid Ashraya targets (keeps kirtan minutes).

Services & Data

• Supabase: Auth (email/password, MFA TOTP), Database (devotees, daily_tracking, mentors, seva_services), Edge functions (vaishnava_calendar).
• NotificationService: schedules daily reminders and calendar alerts; invoked on init/resume.
• StatisticsRepository: provides data for charts/stats (Statistics screen).
• Seva services: fetched from `seva_services` (code, name, sort_order, active); defaults used if fetch fails.
• MFA: listFactors, enroll (unique friendly name), challenge, verify, unenroll; unverified factors cleaned before enroll.

Workflows

Profile & Target Workflow

Onboarding → Contact/University → Mentor/Children → Credentials
  ↓ builds DevoteeDraft (status, age, appGroup, family JSON)
Save to Supabase (devotees.familyMembers JSON, mentor/guide IDs)
Home init:
  - Load devotee by auth_id/email
  - If family JSON empty, load dependents by parent_id
  - Build DevoteeContext per profile → getTargetsForPerson
  - Render Practice/Overview with resolved targets
        

Practice Save Workflow

User updates practice rows (rounds/time, reading/hearing, kirtan, seva, arati)
  → setState (per profile) → _saveTracking()
  → upsert daily_tracking (profile_key, date, rounds, japa_time, reading_minutes, hearing_minutes, kirtan_minutes, service_hours, seva_breakdown, flags)
Overview progress:
  roundsProgress: rounds / targetRounds
  associationProgress: (read+hear+kirtan) / targetAssoc (capped for OR profiles)
  sevaProgress: serviceHours / (targetSeva/30)
  overall: average of three
        

MFA TOTP Workflow

Start setup:
  - listFactors → unenroll unverified TOTP
  - enroll totp (unique friendly name) → receive secret + uri + factorId
  - show QR + URI + secret + copy/share buttons
Verify:
  - challenge(factorId) → challengeId
  - verify(factorId, challengeId, code) → enable MFA
Disable:
  - unenroll(factorId)
        

Calendar Workflow

On init:
  - call edge function vaishnava_calendar
  - if fail/empty → fallback sample
  - schedule notifications for days
Mounted checks guard setState after navigation
        

Seva Services Workflow

On init:
  - select * from seva_services where active = true order by sort_order
  - replace default list; rebuild breakdown keys
  - on failure, retain defaults
User edits breakdown → save in daily_tracking for the selected profile