Hourly - Volunteer Opportunity Platform

A comprehensive volunteer opportunity platform that connects high school students with meaningful volunteer experiences using AI-powered personalized recommendations.

🚀 Features

Core Functionality

• User Authentication: Secure registration and login with JWT tokens
• AI-Powered Recommendations: Personalized volunteer opportunities using Groq LLM
• Volunteer Hours Logging: Track and manage volunteer hours with detailed statistics
• User Preferences: Customizable availability, interests, and location preferences
• Social Features: Friend connections and challenge participation
• Progress Tracking: Comprehensive statistics and achievement tracking

Technical Features

• Frontend: React with TypeScript, Tailwind CSS, React Router
• Backend: Node.js with Express, TypeScript
• Database: Azure SQL Database with Microsoft Entra authentication
• AI Integration: Groq API with Llama 3.1-8b-instant model
• Authentication: JWT-based authentication with secure middleware

🏗️ Architecture

hourly/
├── frontend/          # React TypeScript frontend
│   ├── src/
│   │   ├── components/    # Reusable UI components
│   │   ├── contexts/      # React contexts (Auth)
│   │   ├── pages/         # Application pages
│   │   ├── services/      # API service layers
│   │   ├── types/         # TypeScript type definitions
│   │   └── utils/         # Utility functions
│   └── package.json
├── backend/           # Node.js Express backend
│   ├── src/
│   │   ├── config/        # Database and app configuration
│   │   ├── middleware/     # Authentication and validation
│   │   ├── routes/         # API route definitions
│   │   ├── services/       # Business logic services
│   │   └── types/          # TypeScript type definitions
│   ├── database/          # SQL schema and migrations
│   └── package.json
└── README.md

🛠️ Setup Instructions

Prerequisites

• Node.js (v16 or higher)
• npm or yarn
• Azure SQL Database access
• Groq API key

Backend Setup

1. Navigate to backend directory:

   cd backend

2. Install dependencies:

   npm install

3. Environment Configuration:

   cp env.example .env

   Update .env with your configuration:

   NODE_ENV=development
   PORT=3001
   
   # Database Configuration
   DB_SERVER=your-server.database.windows.net
   DB_DATABASE=your-database
   DB_AUTHENTICATION_TYPE=azure-active-directory-default
   DB_ENCRYPT=true
   DB_TRUST_SERVER_CERTIFICATE=false
   
   # JWT Configuration
   JWT_SECRET=your-super-secret-jwt-key
   JWT_EXPIRES_IN=7d
   
   # CORS Configuration
   CORS_ORIGIN=http://localhost:3000
   
   # LLM API Configuration
   LLM_API_KEY=your-groq-api-key
   LLM_API_URL=https://api.groq.com/openai/v1/chat/completions

4. Database Setup:

   npm run setup-db

5. Start the server:

   npm run dev

Frontend Setup

1. Navigate to frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Environment Configuration: Create .env file:

   REACT_APP_API_URL=http://localhost:3001/api

4. Start the development server:

   npm start

📊 Database Schema

The application uses the following main tables:

• users - User accounts and preferences
• opportunities - Volunteer opportunities
• volunteer_logs - User volunteer hour records
• challenges - Volunteer challenges
• user_challenges - User challenge participation
• friends - Friend connections
• friend_requests - Friend request management

🔧 API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• GET /api/auth/profile - Get user profile
• PUT /api/auth/profile - Update user profile

Opportunities

• GET /api/opportunities - Get volunteer opportunities
• GET /api/opportunities/:id - Get specific opportunity
• POST /api/enhanced/opportunities/personalized - Get AI-powered recommendations

Volunteer Logs

• POST /api/enhanced/volunteer-logs - Log volunteer hours
• GET /api/enhanced/volunteer-logs - Get user volunteer logs
• GET /api/enhanced/volunteer-logs/stats - Get user statistics
• DELETE /api/enhanced/volunteer-logs/:id - Delete volunteer log

Social Features

• GET /api/enhanced/friends - Get user friends
• POST /api/enhanced/friends/request - Send friend request
• POST /api/enhanced/friends/accept - Accept friend request
• GET /api/enhanced/challenges - Get active challenges
• POST /api/enhanced/challenges/join - Join challenge

🤖 AI Integration

The platform uses Groq's LLM API to provide personalized volunteer opportunity recommendations based on:

• User location and preferences
• Availability schedule
• Transportation method
• Skills and interests
• Time commitment preferences

🎯 Key Features Implemented

✅ Completed Features

• User authentication and profile management
• AI-powered personalized opportunity recommendations
• Volunteer hours logging with statistics tracking
• User preference management with navigation
• Social features (friends, challenges)
• Comprehensive progress tracking
• Responsive UI with modern design
• Database integration with Azure SQL
• API route configuration and testing

🔄 User Flow

1. Registration/Login → User creates account or logs in
2. Profile Setup → User sets preferences and availability
3. AI Recommendations → System generates personalized opportunities
4. Volunteer Logging → User logs volunteer hours
5. Progress Tracking → System tracks statistics and achievements
6. Social Interaction → Users connect with friends and join challenges

🚀 Deployment

Backend Deployment

1. Build the application:

   npm run build

2. Start production server:

   npm start

Frontend Deployment

1. Build for production:

   npm run build

2. Deploy the build folder to your hosting service

📝 Development Notes

• The application uses TypeScript throughout for type safety
• Authentication is handled via JWT tokens
• Database operations use parameterized queries for security
• AI integration includes fallback mechanisms for reliability
• All API endpoints include proper error handling and validation

🤝 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.

🎉 Acknowledgments

• Groq for AI API services
• Azure for database hosting
• React and Node.js communities for excellent tooling
• All volunteer organizations that inspire this platform