A gamified bill payment system that rewards users with credits for paying bills on time. Redeem credits for gift cards and exclusive perks.

• 🔐 Secure Authentication - Supabase Auth integration
• 💳 Bill Management - Track and pay bills
• 🎁 Rewards System - Earn credits on every payment
• 🔥 Streak Bonuses - Higher rates for consistent payments
• 🏆 Leaderboard - Compete with other users
• 🛍️ Redemption Catalog - Gift cards, discounts, and perks

Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS, shadcn/ui
Backend: FastAPI (Python), Uvicorn
Database: Supabase (PostgreSQL)
Auth: Supabase Auth

# Clone repository
git clone <your-repo-url>
cd guhack2025

# Backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Frontend
cd ../frontend
npm install

See SETUP.md for detailed setup instructions.

Quick setup:

• Create backend/.env with Supabase credentials
• Create frontend/.env.local with Supabase credentials
• Get credentials from: https://app.supabase.com/project/_/settings/api

Terminal 1 - Backend:

cd backend
source venv/bin/activate
python main.py

Terminal 2 - Frontend:

cd frontend
npm run dev

Open: http://localhost:3000

guhack2025/
├── backend/              # FastAPI backend
│   ├── main.py          # Application entry
│   ├── reward.py        # API routes
│   ├── db.py            # Database operations
│   └── .env             # Environment config (create this)
│
├── frontend/            # Next.js frontend
│   ├── app/            # Pages
│   │   ├── page.tsx           # Login
│   │   ├── signup/            # Sign up
│   │   ├── dashboard/         # User dashboard
│   │   ├── bills/             # Bill management
│   │   └── rewards/           # Rewards catalog
│   ├── components/     # React components
│   ├── lib/           # Utilities & API client
│   └── .env.local     # Environment config (create this)
│
├── README.md          # This file
└── SETUP.md          # Detailed setup guide

1. Sign Up → Create account
2. Add Bills → Track bills with due dates
3. Pay Bills → Make payments through the app
4. Earn Credits → Get 1-5% back based on category
5. Build Streaks → Increase reward rate with consistent payments
6. Redeem Rewards → Spend credits on gift cards and perks

Streak Bonuses: Pay on time consistently to unlock higher rates!

# Check backend health
curl http://localhost:8001/api/health

# Verify environment setup
cd backend && python check_env.py

# Full system diagnostic
./diagnose.sh

# View API documentation
open http://localhost:8001/docs

• Check backend/.env exists with valid Supabase credentials
• Run: cd backend && python check_env.py

• Ensure backend is running on port 8001
• Check frontend/.env.local has NEXT_PUBLIC_API_URL=http://localhost:8001

• Restart backend: Stop (Ctrl+C) and run python main.py again
• Hard reload browser: Ctrl+Shift+R

More help: See SETUP.md or run ./diagnose.sh

Once backend is running, visit http://localhost:8001/docs for interactive API documentation.

Key Endpoints:

• POST /api/reward/users/init - Initialize user
• GET /api/reward/bills - List bills
• POST /api/reward/payments - Record payment
• GET /api/reward/rewards - List rewards
• POST /api/reward/redemptions - Redeem reward

Using Supabase (PostgreSQL) with tables:

• profiles - User accounts & credits
• bills - Bills to pay
• payments - Payment transactions
• rewards_ledger - Credit earning details
• streak_status - Streak tracking
• credit_shop - Available rewards
• redemptions - Redemption history

MIT License - See LICENSE file for details

1. Fork the repository
2. Create feature branch
3. Make changes
4. Test thoroughly
5. Submit pull request

Need help? Check SETUP.md or run ./diagnose.sh

Made for GUHack2025 🎓