first commit

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -1,36 +1,88 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Democratic Fundraiser
 
-## Getting Started
+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.
 
-First, run the development server:
+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
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open `http://127.0.0.1:8008` or `http://<machine-ip>:8008`.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+## Configuration
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+Copy `.env.example` to `.env` and fill in the real local values. Do not commit `.env`.
 
-## Learn More
+Required values:
 
-To learn more about Next.js, take a look at the following resources:
+- `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`
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+For local Stripe webhook forwarding:
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+```bash
+stripe listen --forward-to 127.0.0.1:8008/api/webhooks/stripe
+```
 
-## Deploy on Vercel
+## Useful Commands
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+```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
+```
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+## 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.