A full-stack charity community listing platform where users can post items for donation, browse by category and location, claim items they need, and track the full donation lifecycle. Includes admin approval, impact dashboards, reporting, and more.

🌐 Live Demo: charity-community-listing.vercel.app

Homepage — Browse listings	Dark Mode
Admin Panel — Approve/Reject listings	Create Listing — With image upload & tags
Listing Detail — Claim & messaging	Dashboard — Impact stats & badges
Login Page	Mobile Responsive

• 📸 Image Upload — Upload images for listings (JPEG, PNG, WebP, GIF, up to 5MB)
• 📂 Categories — Organize listings by type (Food, Clothing, Electronics, Furniture, Books, Toys, Health, Other)
• 🏷️ Tags — Add custom tags for better discoverability
• 📍 Location — Add location info to help nearby community members
• 🔍 Search & Filter — Search by keyword, filter by category/location/condition with debounced input
• 🙋 Claim System — Users can claim items with a message to the donor
• 🔐 User Authentication — Register/login with email & password (bcrypt hashed)
• 👨‍💼 Admin Panel — Approve or reject listings before they go public
• 🌗 Dark Mode — Full dark/light theme toggle

• Giver-Selects Model — Donors review all claims and choose who to give to
• 💬 Claim Messaging — Chat between donor and claimer (up to 5 messages per claim)
• 📅 Pickup Scheduling — Set a pickup date/time when approving a claim
• ✅ Fulfillment Tracking — Mark items as fulfilled once handed over
• 🙏 Gratitude Notes — Claimers can leave thank-you notes after receiving items

• 🏆 Impact Dashboard — Track your donation stats and earn badges (First Donation, Generous Giver, Community Hero, etc.)
• 🔖 Condition Badges — Items labeled as New, Like New, Good, or Fair
• 🚩 Report System — Flag inappropriate listings (Spam, Inappropriate, Scam)
• ⏰ Auto-Expiry — Listings older than 30 days are automatically hidden
• 🔔 Notifications — Real-time alerts for claim updates, approvals, and more
• ⏱️ Relative Timestamps — "2 hours ago" style display with auto-refresh

# Clone the repo
git clone https://github.com/sirhafizho/charity-community-listing.git
cd charity-community-listing

# Install dependencies
npm install

# Set up environment
cp .env.example .env

# Push database schema & seed
npx prisma db push
npm run prisma:seed

# Start development server
npm run dev

Open http://localhost:3000

src/
├── app/
│   ├── api/
│   │   ├── auth/           # Registration & NextAuth handlers
│   │   ├── listings/       # Listings CRUD + detail
│   │   ├── categories/     # Category management
│   │   ├── claims/         # Claim system + messages + gratitude
│   │   ├── reports/        # Report listing system
│   │   ├── notifications/  # User notifications
│   │   ├── users/me/       # Impact stats + badges
│   │   ├── upload/         # Image upload (local + Vercel Blob)
│   │   └── admin/          # Admin approval endpoints
│   ├── dashboard/          # User dashboard
│   ├── listings/           # Browse, detail, create pages
│   ├── login/              # Login page
│   └── register/           # Registration page
├── components/
│   ├── admin/              # Admin dashboard
│   ├── claims/             # ClaimActions, MessageThread, GratitudeForm
│   ├── dashboard/          # UserDashboard, ImpactDashboard
│   ├── forms/              # CreateListingForm
│   ├── ConditionBadge.tsx   # Item condition display
│   ├── RelativeTime.tsx     # "X ago" timestamps
│   ├── ReportButton.tsx     # Report modal
│   └── ListingCard.tsx      # Listing card with badges
├── lib/                    # Utilities (prisma, auth, validation, rate-limit)
└── types/                  # TypeScript type definitions

e2e/                        # Playwright E2E tests
__tests__/                  # Jest unit & integration tests
scripts/                    # Build & deployment scripts

# Unit tests
npm test

# Unit tests with coverage
npm test -- --coverage

# E2E tests (requires dev server)
npx playwright test

# E2E with UI
npx playwright test --ui

Test Coverage: 148 total tests

• 62 unit tests — API routes, validations, edge cases
• 86 E2E tests — Full browser flows including registration, login, listing creation, claim lifecycle, admin approval, state machine edge cases, reports, impact dashboard, dark mode, search/filter, and more

Every push to main runs through GitHub Actions:

1. Lint — ESLint
2. Type Check — TypeScript tsc --noEmit
3. Build — Next.js production build
4. Unit Tests — Jest with coverage report
5. E2E Tests — Playwright browser tests
6. Deploy — Automatic deploy to Vercel (only after all checks pass)

• Passwords hashed with bcrypt (12 rounds)
• Role-based access control (USER / ADMIN)
• Input validation with Zod on all endpoints
• File upload type & size validation (5MB max, images only)
• SVG uploads blocked (XSS prevention)
• Comprehensive rate limiting on all API endpoints (per-user and per-IP)
• Race condition protection on claims (DB unique constraint + transaction)
• State machine guards on listing/claim lifecycle (prevents invalid transitions)
• Protected admin routes via middleware
• CSRF protection via NextAuth

This project was built entirely with AI assistance as an experiment in AI-driven software engineering.

• Sprint-based workflow — Features planned and tracked in structured sprints
• Divergence/Convergence — Multiple sub-agents explore solutions in parallel, best approach selected
• Adversarial Review — Code reviewed by separate agent after each feature for bugs and edge cases
• Test-Driven Validation — Every feature backed by unit + E2E tests before merge
• Continuous Deployment — Auto-deploy pipeline ensures every commit is production-ready

• 86 E2E tests + 62 unit tests = 148 total automated tests
• 22 API endpoints with full CRUD, state machines, and rate limiting
• 6-stage CI/CD pipeline — lint, typecheck, build, unit tests, E2E, deploy
• Full state machine for listing + claim lifecycle with transition guards
• Zero manual code — 100% AI-generated from requirements to deployment

• Parallel sub-agents for independent research and implementation tasks
• Session checkpoints for context preservation across long conversations
• SQL-based todo tracking for sprint management
• Playwright E2E for browser-level validation of all user flows
• Rate limiting designed to protect demo site from abuse while allowing CI

MIT

Built with ❤️ for the community — powered by AI.