Volunteer Match Platform 🤝

A comprehensive, production-ready volunteer matching platform that connects volunteers with local NGOs based on location, cause, and time availability.

🌟 Features

For Volunteers

• Smart Matching: Find opportunities based on location, interests, and availability
• Profile Management: Create detailed profiles with skills, interests, and availability
• Real-time Notifications: Get instant updates on opportunity matches
• Application Tracking: Track all your volunteer applications in one place
• Reviews & Ratings: Leave feedback for NGOs and build your volunteer reputation
• Calendar Integration: Export your volunteer schedule to Google Calendar, Apple Calendar, Outlook (iCal)
• Location-based Search: Find opportunities near you with map visualization
• Two-Factor Authentication: Secure your account with TOTP-based 2FA
• Team Volunteering: Create or join volunteer teams with friends, family, or colleagues
• Advanced Search: Find opportunities with powerful full-text search and filters
• Certificates: Get beautiful certificates for completed volunteer work
• Gamification: Earn badges, unlock achievements, and climb leaderboards

For NGOs

• Opportunity Posting: Create and manage volunteer opportunities
• Volunteer Discovery: Find qualified volunteers based on skills and availability
• Application Management: Review and manage volunteer applications
• Verification System: Get verified to build trust with volunteers
• Analytics Dashboard: Track volunteer engagement and impact metrics
• Communication Tools: Message volunteers directly through the platform
• Event Management: Create fundraisers, workshops, training sessions, and community events
• Webhook Integrations: Connect with external systems via secure webhooks
• Team Applications: Accept applications from volunteer teams
• Certificate Issuance: Automatically generate certificates for volunteers
• Calendar Exports: Share your event calendar via iCal feeds

Platform Features

• Geospatial Matching: Advanced PostGIS-powered location matching
• Real-time Messaging: Built-in chat system using Phoenix Channels
• Background Jobs: Automated matching, notifications, and reminders
• Admin Dashboard: Comprehensive admin tools for platform management
• Multi-language Support: Ready for internationalization
• Mobile Responsive: Works seamlessly on all devices
• GraphQL API: Full GraphQL API with subscriptions alongside REST
• Security: JWT authentication, role-based access control, rate limiting

🎉 Phase 2 Advanced Features (NEW!)

🔐 Two-Factor Authentication

• TOTP-based 2FA with QR codes for authenticator apps
• 10 backup codes per user for account recovery
• Compatible with Google Authenticator, Authy, 1Password, etc.

🔍 Advanced Full-Text Search

• PostgreSQL pg_trgm trigram similarity matching
• Full-text search with relevance ranking
• Search across opportunities, NGOs, and volunteers
• Autocomplete suggestions
• Fuzzy matching for typos

👥 Team/Group Volunteering

• Create volunteer teams (Volunteer, Corporate, Student, Family)
• Team leaders and co-leaders
• Team invitations and member management
• Apply to opportunities as a team
• Team statistics and analytics

📅 Event Management System

• Create events (fundraisers, workshops, training, meetings)
• Virtual and physical events
• Event registration with capacity limits
• Waitlist management
• Attendance tracking
• Event search by location

🔗 Webhook System

• Integrate with external systems
• 10+ event types (application., opportunity., event.*)
• HMAC-SHA256 signature verification
• Automatic retries with exponential backoff
• Delivery tracking and analytics

🏆 Certificate Generation

• Beautiful HTML certificates for completed work
• Single opportunity and summary certificates
• Professional design with organization branding
• Unique certificate IDs for verification
• PDF export ready

📆 Calendar Integration

• Export events to iCal format
• Export volunteer schedule
• Compatible with Google Calendar, Apple Calendar, Outlook
• Webcal URL for calendar subscriptions
• Event reminders

🏗️ Architecture

Backend Stack

• Elixir 1.14+: Functional, concurrent, fault-tolerant language
• Phoenix 1.7: Web framework with LiveView for real-time features
• PostgreSQL 14+: Primary database with PostGIS extension
• Oban: Background job processing
• Guardian: JWT-based authentication
• Swoosh: Email delivery system

Frontend Stack

• Phoenix LiveView: Server-rendered, real-time UI
• TailwindCSS: Utility-first CSS framework
• Alpine.js: Lightweight JavaScript framework
• Leaflet/MapBox: Interactive maps

Infrastructure

• Docker: Containerized deployment
• GitHub Actions: CI/CD pipeline
• Sentry: Error tracking and monitoring
• AWS S3: File storage (avatars, documents)

🚀 Getting Started

Prerequisites

• Elixir 1.14 or higher
• Erlang/OTP 25 or higher
• PostgreSQL 14+ with PostGIS extension
• Node.js 18+ (for assets)

Installation

1. Clone the repository

   git clone https://github.com/codeforgood-org/volunteer-matching-platform.git
   cd volunteer-matching-platform

2. Install dependencies

   mix deps.get

3. Install PostgreSQL and PostGIS

   # Ubuntu/Debian
   sudo apt-get install postgresql postgresql-contrib postgis
   
   # macOS
   brew install postgresql postgis
   
   # Enable PostGIS extension
   psql -d volunteer_match_dev -c "CREATE EXTENSION IF NOT EXISTS postgis;"

4. Configure environment variables

   cp .env.example .env
   # Edit .env with your configuration

5. Create and migrate database

   mix ecto.setup

6. Install frontend dependencies

   mix assets.setup

7. Start the Phoenix server

   mix phx.server

Visit localhost:4000 in your browser.

Development

# Run tests
mix test

# Run tests with coverage
mix coveralls.html

# Code quality checks
mix credo --strict

# Type checking
mix dialyzer

# Format code
mix format

🐳 Docker Deployment

Development

docker-compose up

Production

docker-compose -f docker-compose.prod.yml up -d

📋 Environment Variables

Create a .env file with the following variables:

# Database
DATABASE_URL=postgresql://user:password@localhost/volunteer_match_dev
DATABASE_POOL_SIZE=10

# Phoenix
SECRET_KEY_BASE=your-secret-key-base
PHX_HOST=localhost
PHX_PORT=4000

# Guardian JWT
GUARDIAN_SECRET_KEY=your-guardian-secret

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-password
FROM_EMAIL=[email protected]

# AWS S3 (optional)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_BUCKET=volunteer-match-uploads
AWS_REGION=us-east-1

# Sentry (optional)
SENTRY_DSN=your-sentry-dsn

# Maps API
MAPBOX_TOKEN=your-mapbox-token

📊 Database Schema

Core Entities

• Users: Authentication and base user data
• Volunteers: Volunteer profiles with skills and availability
• NGOs: NGO profiles with verification status
• Opportunities: Volunteer opportunities posted by NGOs
• Applications: Volunteer applications to opportunities
• Messages: Direct messaging between users
• Reviews: Ratings and reviews for completed volunteer work
• Matches: Algorithmic matches between volunteers and opportunities

🧪 Testing

The project includes comprehensive test coverage:

# Run all tests
mix test

# Run specific test file
mix test test/volunteer_match/accounts_test.exs

# Run tests with coverage
mix coveralls.html
open cover/excoveralls.html

📈 Performance

• Real-time Updates: Phoenix LiveView provides instant UI updates
• Geospatial Queries: PostGIS enables efficient location-based matching
• Background Jobs: Oban handles async processing without blocking
• Connection Pooling: Optimized database connection management
• Caching: Strategic caching for frequently accessed data
• Rate Limiting: Protects API endpoints from abuse

🔒 Security

• Authentication: JWT-based with secure token management
• Authorization: Role-based access control (RBAC)
• Password Hashing: bcrypt with strong work factors
• CORS: Configurable cross-origin resource sharing
• Rate Limiting: Request throttling to prevent abuse
• SQL Injection: Ecto parameterized queries
• XSS Protection: Phoenix HTML escaping
• CSRF Protection: Built-in Phoenix CSRF tokens

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 API Documentation

API documentation is available at /api/docs when running the server.

Authentication

# Register
curl -X POST http://localhost:4000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "secure_password"}'

# Login
curl -X POST http://localhost:4000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "secure_password"}'

Opportunities

# List opportunities
curl http://localhost:4000/api/opportunities \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Search by location
curl "http://localhost:4000/api/opportunities?lat=37.7749&lng=-122.4194&radius=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Phoenix Framework Team
• Elixir Community
• All contributors and volunteers

📞 Support

• Issues: GitHub Issues
• Email: [email protected]
• Documentation: Wiki

---

Built with ❤️ by Code for Good