Ramadan Quest

A Duolingo-inspired habit tracker for Ramadan. Check off daily deeds, keep your streak, compete with friends, and get notified to stay on track.

---

Why Ramadan Quest?

Most Ramadan apps are overwhelming or abandoned after a week. Ramadan Quest keeps it simple:

• 12 deeds, not 100. Three per spiritual pillar — enough to feel meaningful, not enough to feel like a chore.
• One minute per day. Check in, see your streak, and move on.
• Stay motivated with notifications. Friend nudges, achievement badges, and smart reminders keep you engaged without being annoying.
• Built for any region. Set your timezone and regions, then deploy. Works for any country.

---

Quick Start

1. Clone and install:

   git clone https://github.com/your-repo/ramadan-quest.git
   cd ramadan-quest
   npm install

2. Configure for your region: See SETUP_GUIDE.md

3. Set up Supabase: Create a free account, run migrations

4. Deploy: vercel deploy or similar

See SETUP_GUIDE.md for detailed instructions.

Stack

• Next.js — React framework
• Supabase — PostgreSQL database with auth
• shadcn/ui — Component library
• Web Push API — Browser notifications
• Service Workers — Background sync

Documentation

• SETUP_GUIDE.md — How to deploy for your region, set regions/timezone
• CRON_SETUP.md — Retention reminder cron job setup
• DEPLOYMENT.md — Deployment checklist

Features

📱 Daily Habit Tracking

• 12 balanced deeds grouped into 4 pillars (prayer, iman, fasting, social good)
• Daily streaks with visual progress tracking
• Month-long leaderboard to stay motivated

🎖️ Achievements & Badges

• Auto-awarded badges for 3, 7, 14, and 30-day streaks
• Stats dashboard showing achievements and key metrics
• Celebrate milestones with toast notifications

🔔 Push Notifications

• Friend nudges: Personalized notifications from friends
• Retention reminders: Hourly check-ins + evening "last chance" notifications
• Rank changes: Alerts when you move up/down the leaderboard
• Web push API integration with service worker

📲 Progressive Web App

• Install as standalone app on home screen
• Works offline with service worker
• Native app-like experience

Push Notifications & Retention Setup

Environment Variables

Add these to .env.local for push notifications:

NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
VAPID_PUBLIC_KEY=your-vapid-public-key
VAPID_PRIVATE_KEY=your-vapid-private-key
VAPID_SUBJECT=mailto:your-email@domain.com
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
ADMIN_SECRET=your-admin-secret
CRON_SECRET=your-cron-secret

Database Migrations

Run these in order in your Supabase SQL Editor:

1. supabase/migrations/00000000000000_run_first.sql (base schema)
2. supabase/migrations/20260222000000_fix_achievements_rpc_and_schema.sql (achievements schema + RPC compatibility)
3. supabase/migrations/20260222013000_fix_update_daily_stat_rank_changes_compat.sql (daily stat / rank_changes compatibility fix)

Cron Job for Retention Reminders

The retention reminder system requires a cron job to send scheduled notifications. See CRON_SETUP.md for detailed setup instructions.

Quick start: Use EasyCron to POST to /api/reminders/send every 5 minutes with header x-cron-secret: <CRON_SECRET>.

License

MIT — open source and free to use, fork, and adapt.

---

Independent project. Not affiliated with or endorsed by Duolingo.

Made with ❤️ for Ramadan 2026