140 lines
4.5 KiB
Markdown
140 lines
4.5 KiB
Markdown
# 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.
|