calvana/pledge-now-pay-later

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

# 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

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.