89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# Democratic Fundraiser
|
|
|
|
A local-first Democratic fundraising platform built with Next.js, Stripe Payment Intents, Auth.js credentials login, Prisma, PostgreSQL, and a server-authoritative supporter wallet.
|
|
|
|
The app is designed to make donating feel active instead of transactional: cinematic landing page, public momentum meter, issue narrative cards, impact planner, Blue Wave (BLW) mock credit index, `/raised` totals page, wallet rewards, raffle entries, and compliance placeholders that must be configured before real fundraising.
|
|
|
|
## Features
|
|
|
|
- Stripe card donations through Payment Intents and Elements.
|
|
- Server-confirmed wallet credits from Stripe webhooks with idempotent ledger writes.
|
|
- Mock Blue Wave (BLW) supporter economy for rewards UX. BLW is not crypto and is not tradable.
|
|
- Supporter wallet with digital perk redemptions and raffle ticket spending.
|
|
- Public fundraising stats endpoint for raised total, donor count, and goal progress.
|
|
- Campaign action center, impact planner, issue grid, accountability frame, and rewards preview.
|
|
- Local LAN runtime on `0.0.0.0:8008`.
|
|
|
|
## Stack
|
|
|
|
- Next.js App Router + TypeScript
|
|
- React 19
|
|
- Tailwind CSS 4
|
|
- Prisma 7 + PostgreSQL
|
|
- Auth.js / NextAuth credentials provider
|
|
- Stripe SDK + Stripe React Elements
|
|
- Framer Motion for motion and interaction polish
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
cd /root/fundraising-platform
|
|
npm install
|
|
cp .env.example .env
|
|
npm run db:migrate
|
|
npm run db:seed
|
|
npm run dev
|
|
```
|
|
|
|
Open `http://127.0.0.1:8008` or `http://<machine-ip>:8008`.
|
|
|
|
## Configuration
|
|
|
|
Copy `.env.example` to `.env` and fill in the real local values. Do not commit `.env`.
|
|
|
|
Required values:
|
|
|
|
- `DATABASE_URL`
|
|
- `AUTH_URL`
|
|
- `NEXTAUTH_URL`
|
|
- `AUTH_SECRET`
|
|
- `STRIPE_SECRET_KEY`
|
|
- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`
|
|
- `STRIPE_WEBHOOK_SECRET`
|
|
- `PUBLIC_CAMPAIGN_GOAL_USD`
|
|
- `NEXT_PUBLIC_COMMITTEE_LEGAL_NAME_PLACEHOLDER`
|
|
- `NEXT_PUBLIC_DISCLAIMER_TEXT`
|
|
|
|
For local Stripe webhook forwarding:
|
|
|
|
```bash
|
|
stripe listen --forward-to 127.0.0.1:8008/api/webhooks/stripe
|
|
```
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
npm run dev # Next dev server on 0.0.0.0:8008
|
|
npm run build # Production build
|
|
npm run start # Serve production build on 0.0.0.0:8008
|
|
npm run db:migrate # Apply Prisma migrations in dev
|
|
npm run db:seed # Seed demo users, wallet, perks, raffles
|
|
npm run test:integration # DB and optional Stripe smoke checks
|
|
npm run test:http # HTTP smoke checks against a running server
|
|
```
|
|
|
|
## Donation Flow
|
|
|
|
1. A signed-in supporter chooses an allowed donation tier.
|
|
2. The server creates a Stripe PaymentIntent and stores the user id plus BLW spot snapshot in metadata.
|
|
3. Stripe confirms the card payment.
|
|
4. Stripe sends `payment_intent.succeeded` to `/api/webhooks/stripe`.
|
|
5. The webhook verifies the signature, checks idempotency, creates the donation, appends a ledger entry, and increments wallet credits exactly once.
|
|
6. The wallet reads the updated balance and enables rewards or raffle actions.
|
|
|
|
## Compliance Notes
|
|
|
|
This repository is a technical demo until configured by qualified campaign counsel. Political fundraising can require FEC, state, donor eligibility, disclosure, reporting, refund, and payment processor review. Replace all committee placeholders and legal copy before accepting live contributions.
|
|
|
|
Never commit secrets, live Stripe keys, donor exports, production database dumps, or private credentials.
|