# Pledge Now, Pay Later

> Convert "I'll donate later" into tracked pledges with automatic payment follow-up. Free forever for UK charities.

## Features

- **15-Second Pledge Flow**: Mobile-first, 3-screen donor experience
- **QR Code Attribution**: Every pledge tied to event + volunteer/table
- **Pay by Bank Transfer**: Zero fees — unique reference for matching
- **Direct Debit**: GoCardless integration for automatic collection
- **Automated Reminders**: 4-step follow-up sequence (export/webhook)
- **Bank Statement Reconciliation**: Upload CSV, auto-match payments
- **CRM Export**: Full attribution data ready for import
- **Pipeline Dashboard**: Track pledges from new → paid

## Quick Start

### Prerequisites
- Node.js 18+
- Docker & Docker Compose
- npm or pnpm

### Setup

```bash
# 1. Clone and install
cd pledge-now-pay-later
npm install

# 2. Start database
docker compose up -d

# 3. Run migrations
npx prisma migrate dev --name init

# 4. Seed demo data
npx prisma db seed

# 5. Start dev server
npm run dev
```

Visit [http://localhost:3000](http://localhost:3000)

### Demo URLs
- **Landing**: http://localhost:3000
- **Donor Flow**: http://localhost:3000/p/demo
- **Dashboard**: http://localhost:3000/dashboard

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Frontend | Next.js 14 (App Router) |
| Language | TypeScript |
| Styling | Tailwind CSS + shadcn/ui |
| Database | PostgreSQL 16 |
| ORM | Prisma |
| QR Codes | qrcode (node) |
| CSV Parsing | PapaParse |
| Icons | Lucide React |
| Auth | NextAuth.js (ready) |

## Architecture

```
src/
├── app/
│   ├── api/              # API routes
│   │   ├── analytics/    # Event tracking
│   │   ├── dashboard/    # Stats & pipeline
│   │   ├── events/       # CRUD + QR management
│   │   ├── exports/      # CRM pack CSV
│   │   ├── imports/      # Bank statement matching
│   │   ├── pledges/      # Create, update, mark paid
│   │   ├── qr/           # Resolve QR tokens
│   │   └── webhooks/     # Reminder event polling
│   ├── dashboard/        # Staff UI
│   │   ├── events/       # Event management + QR codes
│   │   ├── pledges/      # Pledge pipeline
│   │   ├── reconcile/    # Bank CSV import
│   │   ├── exports/      # Download CRM data
│   │   ├── settings/     # Org config
│   │   └── apply/        # Fractional CTO upsell
│   └── p/[token]/        # Donor pledge flow
│       └── steps/        # Amount → Payment → Identity → Instructions
├── components/ui/        # Reusable UI components
└── lib/                  # Core utilities
    ├── prisma.ts         # DB client
    ├── reference.ts      # Bank-safe ref generator
    ├── qr.ts             # QR code generation
    ├── matching.ts       # Bank statement matching
    ├── reminders.ts      # Reminder sequences
    ├── analytics.ts      # Event tracking
    ├── exports.ts        # CRM export formatting
    └── validators.ts     # Zod schemas
```

## API Reference

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/qr/{token}` | GET | Resolve QR code → event info |
| `/api/pledges` | POST | Create pledge |
| `/api/pledges/{id}` | PATCH | Update pledge status |
| `/api/pledges/{id}/mark-initiated` | POST | Donor "I've paid" |
| `/api/events` | GET/POST | List & create events |
| `/api/events/{id}/qr` | GET/POST | Manage QR sources |
| `/api/events/{id}/qr/{qrId}/download` | GET | Download QR PNG |
| `/api/dashboard` | GET | Dashboard stats |
| `/api/imports/bank-statement` | POST | Upload & match CSV |
| `/api/exports/crm-pack` | GET | Download CRM CSV |
| `/api/webhooks` | GET | Poll pending reminders |
| `/api/analytics` | POST | Track events |

## Payment Reference Format

References follow format: `PREFIX-XXXX-NN`
- **PREFIX**: Configurable per org (default: PNPL), max 4 chars
- **XXXX**: 4-char alphanumeric (human-safe: no 0/O, 1/I/l)
- **NN**: Amount in pounds (helps manual matching)
- Total max 18 chars (UK BACS limit)

Example: `PNPL-7K4P-50` (£50 pledge)

## Reminder Sequence

| Step | Delay | Message |
|------|-------|---------|
| 0 | T+0 | Payment instructions with bank details |
| 1 | T+2 days | Gentle nudge |
| 2 | T+7 days | Impact story + urgency |
| 3 | T+14 days | Final reminder + easy cancel |

Reminders auto-stop when pledge is marked paid.

## License

Proprietary — © Omair. All rights reserved.