Full-Stack Web Developer for Dilemma Track

# Dilemma Track – Developer Summary (Corrected)

## What is Dilemma Track?

**Dilemma Track** is a full-stack web platform used to manage real-world, flyer-based referral campaigns powered by gig workers (e.g., Uber, DoorDash drivers). These drivers distribute physical flyers containing their unique referral codes.

**Important:** Customers do *not* sign up online. Instead, they **bring flyers to physical stores or call centers**, where **Employees** or **Admins** manually log the referrals.

---

## Purpose & Value

| Audience | Pain Point | Solution Provided |
|--------------|-------------------------------------|----------------------------------------------|
| Business Ops | Untrackable, decentralized flyer programs | Centralized platform for flyer, driver, and referral control |
| Finance | Manual and error-prone tracking | Timed referral release system + clawbacks |
| Marketing | No visibility into local performance| Heatmaps and geo-based flyer strategies |
| Drivers | No incentive to distribute flyers | Earn commission for physical distribution |

---

## Roles

- **Driver**: Distributes flyers, views earnings, geo data, and personal info. Cannot log referrals.
- **Employee**: Logs referrals at the point of customer redemption. Cannot see payouts or dashboard data.
- **Admin**: Oversees everything — drivers, employees, flyers, referrals, payouts, announcements.

---

## System Flow (Corrected)

```
Driver Registers -> Admin Approves -> Driver Gets Referral Code
-> Driver Distributes Flyers -> Customer Brings Flyer In
-> Employee/Admin Logs Referral -> 30-Day Timer Starts
-> Referral Becomes Released or Clawed Back -> Driver Can Cash Out
```

---

## Driver Portal

### Dashboard
- Balance Cards: Released, Pending, Negative
- Last 5 referrals (read-only)
- Quick actions: Flyers, Cash-Out, Support, Earnings Statement
- Geo heatmap: Visualize high-performing zones
- Notification bell + announcement bar

### Flyer Management
- Flyers categorized by service type, customer type, region, promotions
- Drivers download flyers (PDF) that embed their referral code
- Must edit PDF manually to insert their referral code before printing

### Referral Tracker
- View-only: See all referrals linked to their code
- Columns: Date, Type, Commission, Status (Pending / Released / Clawed Back), Countdown
- Filters: Date, Status, Commission Amount
- Chart and timeline visualizations included

### Geo Heatmap
- Color-coded zones by 3-digit postal code prefix
- Shows referral counts and earnings by region
- Filters: Date range, service type

### Profile Management
- Editable: phone, email, address, profile picture
- Payout email changes trigger 24-hour hold + limit 2/week
- Referral code is permanent and read-only

---

## Admin Portal

- **Driver Approvals**: Review, approve, or reject applications
- **Flyer Management**: Upload, categorize, expire, activate/deactivate flyers
- **Referral Management**: Modify or claw back referrals
- **Employee Accounts**: Add/remove staff, reset passwords
- **Announcement System**: Push banners to driver dashboards
- **Financial Dashboard**: Track pending/released commissions, enable payouts

---

## Employee Portal

- **Primary Task**: Log new referrals when a customer brings in a flyer
- Inputs: Driver code, service sold, date, postal code, notes
- Can edit their own entries but not others

---

## Referral Lifecycle

- **Pending**: Default state on entry
- **Released**: Becomes eligible after 30 days
- **Clawed Back**: Triggered manually if customer cancels or service is reversed
- Only **Released** referrals are eligible for cash-out

---

## Support System

- Drivers can open support tickets from dashboard
- Admin responses appear as notifications
- Status updates and resolution timestamps included

---

## Security Rules

- SMS verification for registration
- Strong password enforcement
- 1-hour expiry for password reset links
- Rate limits:
- 3 failed SMS attempts → lock for 15 mins
- 5 password resets/hour
- 2 payout changes/week
- All access attempts are IP-logged and auditable

---

## Summary Diagram

```
[Driver Portal] -> Dashboard / Flyers / Referral Viewer / Geo Stats / Profile
[Employee Portal] -> Log New Referrals Only
[Admin Portal] -> Driver Review / Flyer Upload / Referral Management / Finance
[Database & Logic] -> Stores all referrals, user accounts, flyer metadata, state timers
```

---

**Note:** This document reflects the correct business logic where *Employees log referrals manually*.
There is no self-signup or automated tracking by customers.