Community Invest

Community Invest connects donors with neighbors facing utility shutoffs. Recipients create campaigns to crowdfund bill payments. Together, we prevent disconnections and strengthen communities

Comment

Community Invest

Community Invest connects generous donors with neighbors facing utility shutoffs. Recipients create public or anonymous campaigns to crowdfund bill payments. Together, we prevent disconnections and strengthen communities.

Project Overview

Community Invest is a neighborhood utility insurance platform that enables:

  • Recipients to submit utility bills, create fundraising campaigns, and share their stories
  • Contributors to discover campaigns, make donations, and track their impact
  • Admins to verify bills, manage payments, and oversee platform operations

Tech Stack

  • Frontend: Next.js 15 (App Router), TypeScript, Tailwind CSS, shadcn/ui
  • Backend: Convex (real-time database)
  • Authentication: Clerk
  • Payments: Stripe (payment intents, webhooks)
  • Icons: Lucide React
  • UI Components: shadcn/ui with accessible design

Getting Started

Prerequisites

  • Node.js 18+
  • pnpm (recommended) or npm

Installation

  1. Clone the repository

    git clone https://github.com/Syed-Ahmed02/ummahhacks.git
cd ummahhacks

  2. Install dependencies

    pnpm install

  3. Set up environment variables Create .env.local with:

    NEXT_PUBLIC_CONVEX_URL=<your-convex-url>
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=<your-clerk-key>
CLERK_SECRET_KEY=<your-clerk-secret>
STRIPE_SECRET_KEY=<your-stripe-key>
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=<your-stripe-public-key>

  4. Run the development server

    npm run dev

Open http://localhost:3000 to see the application.

Project Structure

app/
├── (auth)/                    # Authentication pages (sign-in, sign-up)
├── (dashboard)/               # Protected dashboard routes
│   ├── my-campaigns/         # Recipient campaign management
│   ├── my-requests/          # Bill request management
│   ├── admin/                # Admin dashboard
│   ├── settings/             # User settings
│   └── ...                   # Other dashboard sections
├── api/                       # API routes (Clerk, Stripe webhooks)
└── campaigns/                 # Public campaign viewing

components/
├── campaigns/                 # Campaign-related components
│   ├── CampaignCard.tsx
│   ├── CampaignForm.tsx       # Campaign details form
│   ├── CampaignTypeSelector.tsx # Public/anonymous selector
│   ├── CampaignImageUploader.tsx # Image upload with validation
│   ├── ImagePreview.tsx       # Image preview component
│   ├── CampaignPreview.tsx    # Campaign preview
│   ├── CampaignProgress.tsx   # Donation progress tracking
│   ├── DonationForm.tsx       # Donation submission
│   ├── DonationList.tsx       # Display campaign donations
│   ├── PrivacySettings.tsx    # Privacy configuration
│   ├── PrivacyNotice.tsx      # Privacy notice display
│   ├── LocationBadge.tsx      # Location indicator
│   ├── ShareButtons.tsx       # Social sharing
│   ├── ShareModal.tsx         # Sharing interface
│   └── CampaignDiscoveryPage.tsx # Campaign browsing
├── dashboard/                 # Dashboard components
├── landing/                   # Landing page sections
├── navigation/                # Navigation & header
├── onboarding/                # Onboarding flow
├── request/                   # Bill submission components
├── settings/                  # Settings pages
├── shared/                    # Shared utilities
└── ui/                        # shadcn/ui components

convex/
├── campaigns.ts               # Campaign mutations & queries
├── bills.ts                   # Bill submission logic
├── donations.ts               # Donation tracking
├── users.ts                   # User management
├── payments.ts                # Payment processing
├── schema.ts                  # Database schema
└── ...

lib/
├── campaigns/
│   ├── imageValidation.ts    # Image size/type/dimension validation
│   └── imageUpload.ts        # Storage integration helpers
├── auth.ts                    # Authentication helpers
├── utils.ts                   # Utility functions
└── ...

Key Features

Campaign Creation (Recipient Flow)

  1. Bill Linking - Link existing bill submissions or create standalone campaigns
  2. Form Prefilling - Utility details auto-populate when bill is selected
  3. Campaign Details - Title, description, goal amount, utility information
  4. Campaign Type - Choose between public (identified) or anonymous campaigns
  5. Privacy Settings - Control what information is visible to donors
  6. Image Upload - Add hero image with drag-drop, client-side validation
  7. Campaign Preview - Review before publishing
  8. Multi-Step Flow - Guided creation process with progress

Campaign Discovery (Contributor Flow)

  1. Browse Campaigns - Discover active fundraising campaigns
  2. Campaign Details - View recipient info, bill details, progress
  3. Campaign Cards - Summary view with key metrics
  4. Donation - Make donations via Stripe with optional messaging
  5. Privacy Respected - See only information recipient chose to share

Bill Management

  • Submit utility bills for verification
  • Track verification status
  • Link bills to campaigns
  • View bill payment history
  • Bill validation for campaign creation

Impact Tracking

  • Donation dashboard for contributors
  • Campaign metrics for recipients
  • Impact reports and statistics
  • Weekly impact summaries
  • Donation list with privacy filtering

Database Schema

Key tables:

  • users - User profiles with roles (recipient/contributor/admin)
  • billSubmissions - Submitted utility bills with verification status
  • campaigns - Fundraising campaigns linked to bills with hero images
  • campaignDonations - Donation records with payment status and source tracking
  • subscriptions - Recurring contribution plans
  • pools - Community funding pools

Component Architecture

Campaign Components

Core Campaign Components:

  • CampaignForm - Multi-field form for campaign details (title, description, amounts, dates)
  • CampaignTypeSelector - Public/anonymous toggle with descriptions and benefits
  • CampaignImageUploader - Drag-drop image upload with real-time validation
  • ImagePreview - Image preview with loading states and fallback
  • CampaignPreview - Full campaign preview before publishing
  • LocationBadge - Location indicator component

Discovery Components:

  • CampaignCard - Campaign summary card for listing pages
  • CampaignDiscoveryPage - Browse and filter campaigns page (350+ lines)
  • CampaignProgress - Visual donation progress indicator

Donation Components:

  • DonationForm - Donation interface with amount validation and messaging
  • DonationList - Display campaign donations with privacy filtering

Privacy & Sharing:

  • PrivacySettings - Privacy preference configuration per campaign
  • PrivacyNotice - Privacy information display for donors
  • ShareButtons - Social sharing functionality (Twitter, Facebook, LinkedIn, email)
  • ShareModal - Campaign link sharing interface with copy-to-clipboard

Image Validation (lib/campaigns/imageValidation.ts)

  • File size limits (5MB max, configurable)
  • Image type checking (JPG, PNG, WebP)
  • Dimension validation (minimum 1200x600px)
  • Async dimension checking via Image API
  • Detailed error messages

Image Upload Helpers (lib/campaigns/imageUpload.ts)

  • Storage integration utilities
  • URL generation from storage IDs
  • Error handling for failed uploads

Campaign Validation

  • Required field validation
  • Bill ownership verification
  • Duplicate campaign prevention
  • Type-safe form submission
  • Date validation for shutoff dates
  • Amount validation (positive numbers)

API Integration

Stripe Integration

  • Payment intent creation for donations
  • Webhook handling for payment confirmation
  • Customer management for recurring contributions
  • Refund processing
  • Payment status tracking

Convex Queries & Mutations

Campaigns:

  • createCampaign - Create campaign with optional bill linking
  • getCampaignBySlug - Public campaign retrieval (respects privacy)
  • getCampaignById - Full campaign data with owner/admin access
  • getUserCampaigns - List user's campaigns
  • getActiveCampaigns - Browse active campaigns
  • updateCampaign - Campaign metadata updates
  • completeCampaign - Mark campaign as complete
  • updateCampaignHeroImage - Update hero image after upload

Donations:

  • createDonation - Create donation record
  • updateDonationStatus - Track payment status
  • getCampaignDonations - List donations with privacy filtering
  • getDonationByPaymentIntent - Lookup by Stripe intent ID

Validation:

  • validateBillForCampaign - Pre-creation bill validation
  • getUserBillsForCampaignCreation - Get available bills for linking

Development Workflows

Creating a Campaign (Recipient)

1. Navigate to /my-campaigns/create
2. [Bill Step] Select or skip bill linking
   - If selected: form fields auto-populate from bill
   - Visual confirmation banner shows linked bill
3. [Details Step] Fill in campaign details
   - All fields required except heroImage
4. [Type Step] Choose campaign type (public/anonymous)
5. [Privacy Step] Set visibility preferences
   - Based on campaign type
6. [Image Step] Upload hero image (optional)
   - Client-side validation before upload
7. [Preview Step] Review all information
8. Publish campaign with unique slug

Making a Donation (Contributor)

1. Browse /campaigns or discover page
2. Click on campaign to view details
3. View recipient info (respects privacy settings)
4. Enter donation amount
5. Add optional message
6. Complete Stripe payment
7. Donation recorded and tracked
8. Campaign totals update

Bill Submission (Recipient)

1. Navigate to /submit-bill
2. Upload utility bill document
3. Enter bill details (type, provider, amount, due date)
4. Bill sent for verification
5. Admin reviews and verifies
6. Bill appears in campaign creation options
7. Recipient can link bill to campaign

Testing Checklist

Campaign Creation

  • [x] Bill selection prefills form fields correctly
  • [x] Form auto-fills: utilityType, utilityProvider, amountDue, shutoffDate, goalAmount
  • [x] Visual confirmation shows selected bill
  • [x] "Change Bill" button clears all prefilled data
  • [x] Campaign type selector works correctly
  • [x] Privacy settings respect campaign type (public vs anonymous)
  • [x] Image upload validates size (5MB max), type (JPG/PNG/WebP), dimensions (1200x600 min)
  • [x] Campaign preview displays all information
  • [x] Campaign publishes with unique slug
  • [ ] Standalone campaigns (no bill linking) work
  • [ ] Campaign creation without bill submission works

Campaign Discovery

  • [ ] Campaigns list displays active campaigns
  • [ ] Privacy settings respected (names hidden if anonymous)
  • [ ] Campaign cards show correct metrics (donations, progress)
  • [ ] Pagination works for campaign lists
  • [ ] Location display respects privacy settings
  • [ ] Sharing buttons work correctly

Donations

  • [ ] Donation form validates positive amounts
  • [ ] Stripe payment integration works
  • [ ] Donation recorded in database
  • [ ] Campaign totals update correctly
  • [ ] Donation count increments
  • [ ] Anonymous donations don't show donor name
  • [ ] Payment status transitions correctly (pending → succeeded)

Navigation

  • [ ] /my-campaigns link appears in recipient sidebar
  • [ ] Navigation between dashboard sections works
  • [ ] Proper role-based access control

Recent Updates

Phase 1 Implementation (Completed)

  • [x] Campaign creation form with bill prefilling
  • [x] Image upload with validation (5MB, type, dimensions)
  • [x] Campaign discovery page with filtering
  • [x] Privacy settings and configuration
  • [x] Donation form with security messaging
  • [x] Navigation sidebar updates
  • [x] Bill linking and validation
  • [x] Multi-step form flow
  • [x] Campaign type selection (public/anonymous)

Future Enhancements

  • Pool-based funding (community pools)
  • Recurring contributions (subscriptions)
  • Campaign scheduling
  • Advanced analytics dashboard
  • SMS notifications
  • Multi-language support
  • Mobile app
  • Image storage/retrieval optimization
  • Campaign analytics (views, click-through rates)
  • Donor notifications and receipts

Built With

Share this project:

Updates