# Fete — MVP Scope & Terms (v2)

**Domain:** fete.africa

## 1. Overview

Fete is an all-in-one platform for receiving donations/gifts at event venues (weddings, birthday parties, burials), with guest photo uploads via QR code and a live wish wall for congratulatory messages — plus an affiliate/event-planner layer that earns commission on events they bring to the platform, and built-in budgeting so hosts can see money raised vs. money spent.

## 2. Tech Stack

- **Backend:** PHP 8
- **Database:** MySQL / MariaDB
- **Frontend:** HTML, CSS, vanilla JavaScript — no frameworks, no build step
- **Hosting:** shared cPanel-compatible hosting
- **Payment processor:** Flutterwave (Ghana)
- **USSD (later phase):** Moolre APIs

## 3. User Roles

1. **Guest / Donor** — gives, uploads a photo, leaves a wish. No account required.
2. **Host** — the celebrant/family running the event. Creates an account, then creates and manages the event.
3. **Event Planner / Affiliate** — creates an account, refers hosts to the platform, and earns commission on the events they bring in.
4. **Admin** — platform owner. Manages users, events, commission settings, and approves every transfer and withdrawal.

## 4. MVP Feature Set

### 4.1 Event Creation & Management
- Host signs up and creates an event: name, type (wedding / birthday / burial / other), date, cover photo
- System generates a unique, shareable event page and a printable QR code for that event
- Host dashboard: running total raised, list of wishes, photo gallery

### 4.2 Donations & Payments (Flutterwave)
- Guests give via the event page (amount, optional name or anonymous toggle)
- Payments processed through Flutterwave Ghana
- Funds from a donation only become available to withdraw **24 hours after the event date**
- Running total displayed on the event page

### 4.3 Currency Handling
- Host can accept donations in any of the currency pairs Flutterwave supports
- The donation page auto-loads a default currency based on the donor's detected IP address, with a manual override so donors on VPNs or inaccurate geolocation can correct it
- Each donation stores the currency given, the amount, and the FX rate applied at the time, so totals stay auditable

### 4.4 QR Photo Upload
- Guest scans the event's QR code and uploads a photo from their phone
- Uploaded photos land in a moderated gallery tied to that event
- Host can approve, reject, or download photos

### 4.5 Live Wish Wall
- Guests leave a text wish/congratulatory note tied to the event
- Wishes display on a live, auto-refreshing wall page (suitable for projecting at the venue)
- Host can export all wishes after the event (PDF or text file)

### 4.6 Named Sub-Funds & Transfers
- Host can create multiple named funds within one event (e.g. "Honeymoon Fund," "Cake Fund," "Burial Expenses")
- Guests choose which fund to give to when donating
- Host can transfer money between sub-funds (and to/from the event's general fund) after donations land
- Dashboard breaks totals down per fund, in addition to the overall total

### 4.7 Affiliate / Event Planner Module
- Planners create an account and get a unique referral link/code
- A host who signs up or creates an event through a planner's link has that planner attached to the event
- Planner earns commission on donations raised for that event, at the rate the admin has set
- A planner can manage multiple concurrent events or a single one — no restriction either way
- Planner dashboard: referred events, commission earned, withdrawal status

### 4.8 Withdrawals & Payout Rules
- Hosts and affiliates submit a withdrawal request for funds available to them
- Withdrawal **requests** can be submitted any day of the week
- Actual **payouts** only process on weekdays — none on Saturday or Sunday
- A donation's funds aren't withdrawable until 24 hours after the event date (see 4.2)

### 4.9 Admin Approval Workflow
- Every transaction transfer (payout to a host or affiliate) requires admin approval before it's released
- Admin has a queue of pending withdrawal requests to approve or reject, with a reason on rejection
- Admin settings page controls the commission model (flat fee vs. percentage) and the rate/amount applied — not hardcoded

### 4.10 Budgeting — Money Raised vs. Money Spent
- Each event shows total raised, total withdrawn/spent, and remaining balance
- Vendor disbursements (4.13) and approved withdrawals both count against "spent"
- Gives hosts a simple running budget view rather than just a donation total

### 4.11 Big-Screen / Projector Live Ticker
- A dedicated, auto-refreshing display view of the event page designed for projecting at the venue
- Shows incoming donations (donor name + amount, unless anonymous) and new wishes in real time as they come in

### 4.12 SMS / WhatsApp Notifications
- Host receives an SMS/WhatsApp alert on new donations and new wishes
- Optional confirmation message sent to the donor after giving

### 4.13 Bulk Disbursement to Vendors
- Host can pay multiple vendors (caterer, photographer, decorator) directly out of the event's raised funds
- Single bulk-payment action instead of individual transfers
- Subject to the same admin-approval and weekday-payout rules as withdrawals

### 4.14 Advanced Analytics & Reporting
- Host dashboard expands beyond the running total: donor breakdown, giving trends over time, top donors, export to spreadsheet

### 4.15 Admin Panel
- Manage hosts and planners
- View all events and donations, moderate flagged content
- Approve/reject withdrawal and transfer requests
- Set commission model and rate

## 5. Deferred to a Later Phase

- **USSD / feature-phone support** — will use Moolre's API once built. Not part of the initial build.
- **Implementation note carried forward:** telcos issue short codes as a limited, regulator-controlled resource — a fully unique per-event short code isn't likely to be practical at scale. The realistic approach is one shared platform code with a per-event reference number entered in-session. Worth confirming with Moolre when this phase starts.

## 6. Build Phases

1. **Foundation** — folder structure, database schema, config, DB connection, `.htaccess` protection for non-public files
2. **Auth & Event Management** — host/affiliate/admin accounts, event creation, QR code generation, sub-funds
3. **Donations & Flutterwave** — donation flow, IP-based currency detection, Flutterwave payment + webhook handling
4. **Wish Wall & Photo Upload** — guest-facing upload flow, moderation, live wall, export
5. **Affiliate Module** — referral attribution, commission ledger, planner dashboard
6. **Withdrawals & Admin Approval** — withdrawal requests, weekday/24-hour rules, admin approval queue, sub-fund transfers
7. **Budgeting & Analytics** — money raised vs. spent view, reporting/export
8. **Later phase** — USSD via Moolre