Lake Forest Caucus - Volunteer Management System

A Next.js web application for managing volunteer profiles with filtering, sorting, and PDF export capabilities.

Features

• 🔍 Advanced Filtering: Filter volunteers by skills, availability, and search terms
• 📊 Data Table: Clean, sortable table view of volunteer information
• 📄 PDF Export: Generate professional PDF reports of filtered volunteer lists
• 🎨 Modern UI: Built with Tailwind CSS and responsive design
• 🗄️ PostgreSQL Database: Robust data persistence with Prisma ORM
• 🔐 NationBuilder Authentication: Secure OAuth integration with your NationBuilder account
• 🚀 Netlify Ready: Configured for easy deployment to Netlify

Tech Stack

• Frontend: Next.js 14, React 18, TypeScript
• Styling: Tailwind CSS
• Database: PostgreSQL with Prisma ORM
• PDF Generation: Puppeteer
• Deployment: Netlify

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL database (local or cloud)
• npm or yarn

Installation

1. Clone and install dependencies:

   git clone <your-repo-url>
   cd lfc-volunteer-app
   npm install

2. Set up the database:

   # Copy environment file and configure
   cp .env.local.example .env.local
   
   # Edit .env.local with your database URL
   # DATABASE_URL="postgresql://username:password@localhost:5432/lfc_volunteers"
   
   # Generate Prisma client and push schema
   npx prisma generate
   npx prisma db push

3. Run the development server:

4. Open http://localhost:3000

Database Setup

Local PostgreSQL

1. Install PostgreSQL locally
2. Create a database: createdb lfc_volunteers
3. Update .env.local with your connection string

Cloud Database (Recommended for Production)

We recommend using:

• Supabase (Free tier available)
• Neon (Serverless PostgreSQL)
• Railway (Easy deployment)
• PlanetScale (MySQL alternative)

Environment Variables

Create a .env.local file in the root directory:

# Database
DATABASE_URL="postgresql://username:password@hostname:5432/database_name"

# NextAuth Configuration
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secure-random-secret-key-here"

# NationBuilder OAuth Configuration
NATIONBUILDER_BASE_URL="https://your-nation.nationbuilder.com"
NATIONBUILDER_CLIENT_ID="your-nationbuilder-client-id"
NATIONBUILDER_CLIENT_SECRET="your-nationbuilder-client-secret"

NationBuilder Setup

1. Create OAuth Application

1. Log in to your NationBuilder admin panel
2. Go to Settings > Developer > API Tokens & OAuth Applications
3. Click "Create OAuth Application"
4. Fill in the details:
   • Name: "Lake Forest Caucus Volunteer Management"
   • Redirect URI: http://localhost:3000/api/auth/callback/nationbuilder (for development)
   • Redirect URI: https://your-netlify-site.netlify.app/api/auth/callback/nationbuilder (for production)

2. Get Your Credentials

After creating the OAuth application, you'll receive:

• Client ID: Copy this to NATIONBUILDER_CLIENT_ID
• Client Secret: Copy this to NATIONBUILDER_CLIENT_SECRET

3. Configure Base URL

Set NATIONBUILDER_BASE_URL to your NationBuilder nation URL:

• For example: https://lakeforestcaucus.nationbuilder.com

4. User Permissions

The authentication system will automatically retrieve:

• User's membership level
• Tags/roles in NationBuilder
• Profile information (name, email, etc.)

You can use this information to control access levels within your application.

Deployment to Netlify

Automatic Deployment

1. Connect your GitHub repository to Netlify

2. Set build settings:

   • Build command: npm run build
   • Publish directory: .next
   • Node version: 18

3. Add environment variables in Netlify:

   • Go to Site settings > Environment variables
   • Add your DATABASE_URL and other environment variables

4. Deploy:

   • Push to your main branch
   • Netlify will automatically build and deploy

Manual Deployment

# Build the application
npm run build

# The .next folder will be created
# Upload this to Netlify or use Netlify CLI

Database Management

Prisma Commands

# Generate Prisma client
npx prisma generate

# Push schema changes to database
npx prisma db push

# Open Prisma Studio (database GUI)
npx prisma studio

# Create migration (if using migrations)
npx prisma migrate dev

Project Structure

├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── volunteers/    # Volunteer CRUD operations
│   │   └── export-pdf/    # PDF generation
│   ├── globals.css        # Global styles
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Home page
├── components/            # Reusable UI components
│   ├── volunteer-dashboard.tsx
│   ├── volunteer-table.tsx
│   ├── volunteer-filters.tsx
│   └── export-button.tsx
├── lib/                   # Utilities and types
│   ├── db.ts             # Database connection
│   ├── types.ts          # TypeScript types
│   └── utils.ts          # Utility functions
├── prisma/               # Database schema
│   └── schema.prisma     # Prisma schema
└── public/              # Static assets

API Routes

• GET /api/volunteers - Fetch volunteers with filtering
• POST /api/volunteers - Create new volunteer
• POST /api/export-pdf - Generate PDF report

Features to Add

• User authentication integration
• Volunteer profile editing/deletion
• Bulk import/export
• Email notifications
• Advanced reporting
• Admin dashboard

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License.