🔍 Overview • 🎯 How It Works • 🌟 Features • 🛠️ Tech Stack • 🏗️ Architecture • ⚙️ Local Setup • 🔐 Test Credentials • 🚢 Deployment • 📡 API Routes • 🗺️ Roadmap
Golf Charity Subscription Platform is a premium full-stack web application that combines the passion of golf with the power of giving. Subscribers submit their monthly golf scores, enter automated lottery draws, and a percentage of every subscription directly funds real charities.
const platform = {
concept : "Golf scores → Lottery entries → Charity donations + Prizes",
subscribers: "Golf enthusiasts who want to compete AND give back",
charities : "Real organizations receiving direct contribution percentages",
engine : "Random & weighted draw algorithms for provably fair results",
payments : "Stripe subscriptions with automated webhook handling",
tagline : "Where every swing counts — for you AND the world 🌍"
}💡 Unique Value: This isn't just a lottery. It's a community-driven giving platform disguised as a golf competition. Players compete, winners win, charities benefit — automatically.
🏌️ THE FULL PLAYER JOURNEY
══════════════════════════════════════════════════════════════════
STEP 1 → Player subscribes via Stripe
💳 Monthly subscription activated
📧 Welcome email via Resend
STEP 2 → Player submits 5 golf scores each month
⛳ Score entry with automated validation
🎫 Each valid score = lottery ticket entry
STEP 3 → Monthly lottery draw runs automatically
🎰 Random + weighted algorithm executes
🏆 Winners selected fairly & transparently
STEP 4 → Winners notified, charities funded
📧 Winner email notification sent
💚 % of subscription goes to charity
🎉 Prizes distributed
REPEAT → Cycle begins again next month 🔄
══════════════════════════════════════════════════════════════════
+ Monthly entry of 5 golf scores
+ Automated score validation rules
+ Score history tracking per player
+ Handicap-aware entry system
+ Submission deadline enforcement+ Pure random draw algorithm
+ Weighted draw (more scores = better odds)
+ Admin-controlled draw execution
+ Transparent result publishing
+ Winner verification system |
+ Direct % contribution per subscription
+ Multiple charity selection
+ Real-time donation tracking
+ Charity impact dashboard
+ Annual giving reports+ Full draw management panel
+ Winner verification & announcement
+ Subscriber management
+ Analytics & reporting dashboard
+ Stripe webhook monitoring |
Subscriber Signs Up
↓
Stripe Checkout Session Created
↓
Payment Processed → Webhook Fired → Supabase Updated
↓ ↓
Subscription Active Email Sent via Resend
↓
Monthly Renewal → Auto-debit → Continue Cycle ♻️
┌─────────────────────────────────────────────────────────────────┐
│ ⛳️ GOLF CHARITY PLATFORM — TECH STACK 🏆 │
├──────────────────┬──────────────────────────────────────────────┤
│ 🖥️ FRAMEWORK │ Next.js 14 (App Router + Server Actions) │
│ │ TypeScript (End-to-end type safety) │
├──────────────────┼──────────────────────────────────────────────┤
│ 🗄️ DATABASE │ Supabase PostgreSQL (Primary DB) │
│ │ Supabase Auth (User management) │
│ │ Supabase RLS (Row Level Security) │
│ │ Supabase Storage (Assets & files) │
├──────────────────┼──────────────────────────────────────────────┤
│ 💳 PAYMENTS │ Stripe (Subscription billing) │
│ │ Stripe Webhooks (Event processing) │
│ │ Stripe Customer Portal (Self-service) │
├──────────────────┼──────────────────────────────────────────────┤
│ 📧 EMAIL │ Resend (Transactional notifications) │
│ │ React Email (Email templates) │
├──────────────────┼──────────────────────────────────────────────┤
│ 🎨 STYLING │ Tailwind CSS (Utility-first styling) │
│ │ Framer Motion (Animations & transitions) │
│ │ Lucide React (Icon library) │
├──────────────────┼──────────────────────────────────────────────┤
│ 🚀 DEPLOYMENT │ Vercel (Hosting + CI/CD pipeline) │
└──────────────────┴──────────────────────────────────────────────┘
┌─────────────────────┐
│ 👤 SUBSCRIBER │
└──────────┬──────────┘
│
┌────────────────▼─────────────────┐
│ NEXT.JS 14 APP ROUTER │
│ (Server Components + Actions) │
└───┬───────────┬──────────┬────────┘
│ │ │
┌──────────▼──┐ ┌─────▼────┐ ┌──▼──────────┐
│ SUPABASE │ │ STRIPE │ │ RESEND │
│ │ │ │ │ │
│ PostgreSQL │ │ Checkout │ │ Welcome │
│ Auth + RLS │ │ Webhooks │ │ Win Notify │
│ Storage │ │ Billing │ │ Receipts │
└──────┬──────┘ └────┬─────┘ └─────────────┘
│ │
│ ┌─────────▼──────────┐
│ │ WEBHOOK HANDLER │
│ │ /api/webhooks/ │
│ │ stripe │
│ └─────────┬──────────┘
│ │
└──────────────▼
┌──────────────────┐
│ 🎰 LOTTERY │
│ ENGINE │
│ (Cron Job) │
│ Random Draw │
│ Weighted Draw │
└──────────────────┘
node --version # 18+ required
npm --version # 9+ recommended# Clone the repository
git clone <repo-url>
cd GolfCharity
# Install all dependencies
npm installCreate a .env.local file in the root directory:
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🗄️ SUPABASE
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT_PUBLIC_SUPABASE_URL= # Dashboard → Settings → API
NEXT_PUBLIC_SUPABASE_ANON_KEY= # Dashboard → Settings → API
SUPABASE_SERVICE_ROLE_KEY= # Dashboard → Settings → API (Secret)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 💳 STRIPE
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STRIPE_SECRET_KEY= # Stripe → Developers → API Keys
STRIPE_WEBHOOK_SECRET= # Stripe CLI or Dashboard Webhook
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 📧 RESEND
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
RESEND_API_KEY= # Resend → API Keys
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🌐 APP
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT_PUBLIC_APP_URL=http://localhost:3000# Initialize DB with test users and charities
npx ts-node scripts/seed.ts# Install Stripe CLI, then forward webhooks locally
stripe listen --forward-to localhost:3000/api/webhooks/stripenpm run dev
# → http://localhost:3000
⚠️ For development/evaluation only. Never use in production.
| Role | Password | Access | |
|---|---|---|---|
| 👑 Admin | admin@test.com |
Admin1234! |
Full dashboard + draw management |
| 🏌️ Subscriber 1 | user1@test.com |
User1234! |
Score entry + lottery |
| 🏌️ Subscriber 2 | user2@test.com |
User1234! |
Score entry + lottery |
✅ Success Payment → 4242 4242 4242 4242
❌ Payment Declined → 4000 0000 0000 0002
🔐 3D Secure Auth → 4000 0025 0000 3155
Expiry: Any future date | CVV: Any 3 digits | ZIP: Any 5 digits
# Step 1 — Connect repo to Vercel
# Go to vercel.com → New Project → Import GitHub repo
# Step 2 — Add all env variables in Vercel dashboard
# Settings → Environment Variables → add all from .env.local
# Step 3 — Deploy
vercel deploy --prod1. Go to Stripe Dashboard → Developers → Webhooks
2. Click "Add Endpoint"
3. URL: https://[your-vercel-domain]/api/webhooks/stripe
4. Select these events:
✅ checkout.session.completed
✅ customer.subscription.updated
✅ customer.subscription.deleted
5. Copy the Signing Secret → Add as STRIPE_WEBHOOK_SECRET in Vercel
| Method | Route | Description | Auth |
|---|---|---|---|
POST |
/api/webhooks/stripe |
Stripe event handler | Webhook Secret |
POST |
/api/scores/submit |
Submit monthly golf scores | Subscriber |
GET |
/api/scores/history |
Fetch player score history | Subscriber |
POST |
/api/draw/execute |
Run monthly lottery draw | Admin only |
GET |
/api/draw/results |
Fetch draw results | Public |
GET |
/api/charities |
List all charities | Public |
GET |
/api/admin/analytics |
Platform analytics | Admin only |
📦 GolfCharity/
│
├── 🌐 app/ # Next.js App Router
│ ├── (auth)/ # Auth pages (login, signup)
│ ├── (dashboard)/ # Subscriber dashboard
│ │ ├── scores/ # Score entry & history
│ │ ├── draws/ # Lottery results
│ │ └── profile/ # Subscription management
│ ├── admin/ # Admin panel (protected)
│ │ ├── draws/ # Draw management
│ │ ├── subscribers/ # User management
│ │ └── analytics/ # Platform stats
│ └── api/ # API route handlers
│ ├── webhooks/stripe/ # Stripe webhook
│ ├── scores/ # Score endpoints
│ └── draw/ # Lottery endpoints
│
├── 🧩 components/ # Reusable UI components
│ ├── ui/ # Base components
│ ├── dashboard/ # Dashboard widgets
│ └── admin/ # Admin components
│
├── 📚 lib/ # Core utilities
│ ├── supabase/ # DB client & queries
│ ├── stripe/ # Payment helpers
│ ├── lottery/ # Draw algorithms
│ └── email/ # Resend templates
│
├── 🗄️ scripts/
│ └── seed.ts # Database seeder
│
└── 📄 .env.local # Environment config
PHASE 1 — CORE PLATFORM ████████████ 100% ✅
✅ Stripe Subscription Billing
✅ Supabase Auth + RLS Security
✅ Monthly Score Submission (5 scores)
✅ Random & Weighted Lottery Engine
✅ Admin Draw Management Panel
✅ Charity Contribution System
✅ Resend Email Notifications
✅ Vercel Deployment
PHASE 2 — ENHANCEMENTS █████░░░░░░░ 40% 🔄
✅ Stripe Customer Portal (self-service)
🔄 Leaderboard & Rankings
🔄 Score verification system
🔲 PDF Winner Certificates
🔲 Mobile-responsive PWA
PHASE 3 — ADVANCED ░░░░░░░░░░░░ 0% 📋
🔲 Multiple subscription tiers
🔲 Live draw streaming (WebSockets)
🔲 Charity selection by subscribers
🔲 Annual giving impact reports
🔲 Referral & rewards program
+ WEBHOOKS → Always start Stripe CLI locally before testing payments
+ RLS → Supabase Row Level Security enabled on all tables
+ SEED DATA → Run seed.ts to get test users, charities & scores
+ DRAW ENGINE → Located in lib/lottery/ — two algorithms available
+ ADMIN ROUTE → /admin/* is protected — only admin@test.com can access
! STRIPE KEYS → Never commit .env.local to GitHub
! SERVICE KEY → SUPABASE_SERVICE_ROLE_KEY bypasses RLS — handle carefullyRavi Kumar Keshari CS & Data Analytics @ IIT Patna (2024–2028)
⭐ If this project impressed you — star the repo! ⭐