Volunsphere 🌟

A comprehensive volunteer management platform that connects volunteers with meaningful opportunities and helps organizations manage their volunteer programs effectively.

📑 Table of Contents

Expand Table of Contents

📱 Project Overview
🎯 Key App Screens
✨ Features
🗂️ Sample API File (Flutter)
📋 Prerequisites
🚀 Installation & Setup
📦 Download APK
🏗️ Project Architecture
🔧 Development
🛡️ Security Features
📊 Performance Optimizations
🤝 Contributing
👥 Contributors
📄 License
🆘 Support & Documentation
🎯 Future Roadmap

📱 Project Overview

Volunsphere is a full-stack application consisting of:

Frontend: Flutter mobile application with cross-platform support
Backend: FastAPI REST API with modern Python stack
Database: PostgreSQL with Redis for caching
Storage: Supabase for file storage and additional services
Push Notifications: Firebase Cloud Messaging (FCM) for real-time alerts

🎯 Key App Screens

🔐 Sign In Secure authentication with remember me option	🏠 Home Dashboard Volunteer statistics and opportunities	📅 Events Browse and manage volunteer events	� Leaderboard Track volunteer hours and achievements	🤖 AI Agent Interact with AI for event insights
👤 Profile User profile management, stats, achievements	🌐 Community Social newsfeed for engagement and updates	📝 Event Details Detailed event info and actions	💬 Chat Real-time messaging for events	📱 Navigation Elegant side drawer, purple theme, animations

✨ Features

👤 For Volunteers

🔐 Secure Authentication – JWT-based login/signup, guest mode
📅 Event Management – Browse, join, and track volunteer events
💬 Real-Time Chat – Communicate with volunteers and organizers
👤 Profile Management – Customize profiles, image upload
🏆 Leaderboard – Rank volunteers by achievements
🌐 Community Feed – Create posts, like, comment, engage
🎨 Modern UI – Purple-themed, smooth animations
📄 Certification – Download certificates after volunteering
🤖 AI Agent – Get event and volunteer insights via AI

🏢 For Organizations

🗓️ Event Creation – Organize/manage events, location mapping
👥 Volunteer Management – Track registrations, attendance
🌐 Community Feed – Share updates/posts with volunteers
📊 Analytics – Monitor engagement, event performance
⭐ Rating System – Rate volunteers after events

⚙️ Technical Features

🎨 Modern Theme – Purple gradient, glassmorphism effects
✉️ Email Integration – OTP verification for password changes
📝 PDF Generation – Create volunteer certificates
🔄 Real-Time Updates – WebSocket live chat & sync
🖼️ Image Handling – Upload, crop profile/event photos
🗺️ Interactive Maps – Google Maps for location selection
🔍 Advanced Search – Search events and volunteers
🤖 AI Agent – Automated chat service
⏰ Automated Logout – Redirect to login on session expiry
💾 Saved Credentials – Device remembers login for a period
🔔 Push Notifications – Via Firebase Cloud Messaging

🗂️ Sample API File (Flutter)

Below is a sample lib/utils/api.dart file for configuring API endpoints in your Flutter app. Replace the placeholder URL with your actual backend URL:

// utils/api.dart

const String baseUrl = "https://your-backend-url/api/v1"; // <-- Replace with your backend URL

const String authUrl = "$baseUrl/auth";
const String eventUrl = "$baseUrl/events";
const String userUrl = "$baseUrl/users";
const String chatUrl = "wss://your-backend-url/api/v1/chat"; // <-- Replace with your backend WebSocket URL
const String communityUrl = "$baseUrl/community";
const String leaderboardUrl = "$baseUrl/leaderboard";

Frontend (Flutter)

dependencies:
  flutter: ^3.7.2
  http: ^1.1.0
  shared_preferences: ^2.2.2
  google_maps_flutter: ^2.5.0
  geolocator: ^10.1.0
  geocoding: ^2.1.1
  image_picker: ^1.0.4
  image_cropper: ^5.0.1
  cached_network_image: ^3.3.0
  url_launcher: ^6.2.1
  intl: ^0.18.1
  lottie: ^2.7.0
  web_socket_channel: ^2.4.0
  provider: ^6.1.1
  firebase_core: ^2.24.2
  firebase_messaging: ^14.7.10

Backend (FastAPI)

# Core Framework
fastapi==0.104.1
uvicorn==0.24.0

# Database & ORM
sqlalchemy==2.0.23
alembic==1.12.1
psycopg2-binary==2.9.9
redis==5.0.1

# Authentication & Security
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
python-multipart==0.0.6

# External Services
supabase==2.0.2
requests==2.31.0

# Firebase Admin SDK for FCM
firebase-admin==6.2.0

# Email & Communication
smtplib (built-in)
email-validator==2.1.0

# Utilities
python-dotenv==1.0.0
pydantic==2.5.0

📋 Prerequisites

System Requirements

Flutter SDK 3.7.2 or higher
Python 3.9 or higher
PostgreSQL 12 or higher
Redis server
Android Studio / VS Code for development
Google Maps API Key for location services
Firebase Project for push notifications
Supabase Account for additional services
GROQ API Access: Valid API key for GROQ (for chatbot integration)

Development Tools

Git version control
Postman/Fastapi Swagger Docs(for API testing)
Android/iOS emulators or physical devices

🚀 Installation & Setup

1. Clone the Repository

git clone https://github.com/your-username/Volunsphere.git
cd Volunsphere

2. Backend Setup

Navigate to backend directory

cd backend

Create and activate virtual environment

python -m venv env
# On Windows
env\Scripts\activate
# On macOS/Linux
source env/bin/activate

Install dependencies

pip install -r requirements.txt

Environment Configuration

Create a .env file in the backend directory:

# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/volunsphere

# JWT Configuration
JWT_SECRET_KEY=your-super-secret-jwt-key-here
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Email Configuration
GMAIL_USER=your-email@gmail.com
GMAIL_PASSWORD=your-app-password

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-service_role-key

# Google Maps API
GOOGLE_MAPS_API_KEY=your-google-maps-api-key

# GROQ API KEY
GROQ_API_KEY = your-GROQ-api-key

# Environment
ENVIRONMENT=development

# Firebase Credentials

FIREBASE_CREDENTIALS_JSON = your-firbase-project-credentials-as-string

Database Setup

# Create database
createdb volunsphere

# Run migrations
alembic upgrade head

Start the backend server

uvicorn src.main:app --reload --host 0.0.0.0 --port 8080

3. Frontend Setup

Navigate to frontend directory

cd frontend

Install Flutter dependencies

flutter pub get

Configure API endpoints

Create lib/utils/api.dart:

Firebase Configuration

Create a Firebase project
Add Android/iOS apps to your Firebase project
Download google-services.json (Android) and GoogleService-Info.plist (iOS)
Place them in the appropriate directories
Configure Firebase in lib/main.dart

Run the Flutter app

# For development
flutter run

# For specific platforms
flutter run -d chrome      # Web
flutter run -d android     # Android
flutter run -d ios         # iOS

� Download APK

You can download the latest Volunsphere Android APK from the following Google Drive link:

👉 Download Volunsphere APK

✅ Android - Full support with native features
✅ iOS - Full support with native features
✅ Web - Full support with responsive design

🏗️ Project Architecture

Backend Architecture

backend/
├── src/
│   ├── auth/              # Authentication & authorization
│   │   ├── routes.py      # Auth endpoints
│   │   ├── models.py      # User models
│   │   └── utils.py       # JWT utilities
│   ├── events/            # Event management
│   │   ├── routes.py      # Event CRUD operations
│   │   ├── models.py      # Event models
│   │   └── services.py    # Business logic
│   ├── community/         # Community features
│   │   ├── routes.py      # Posts & comments
│   │   └── models.py      # Community models
│   ├── chat/              # Real-time chat
│   │   ├── websocket.py   # WebSocket handlers
│   │   └── models.py      # Chat models
│   ├── leaderboard/       # User rankings
│   ├── notifications/     # Push notifications
│   ├── db/               # Database configuration
│   │   ├── database.py   # DB connection
│   │   └── base.py       # Base models
│   └── main.py           # FastAPI app initialization
├── migrations/           # Alembic migrations
|
└── requirements.txt     # Python dependencies

Frontend Architecture

frontend/
├── lib/
│   ├── main.dart                    # App entry point
│   |
│   ├── models/                      # Data models
│   │   ├── user_model.dart
│   │   ├── event_model.dart
│   │   └── post_model.dart
│   ├── services/                    # API services
│   │   ├── auth_service.dart
│   │   ├── events_service.dart
│   │   ├── community_service.dart
│   │   └── chat_service.dart
│   ├── screens/                     # UI screens
│   │   ├── auth/                    # Authentication screens
│   │   ├── events/                  # Event-related screens
│   │   ├── community/               # Community features
│   │   ├── profile/                 # User profile
│   │   └── settings/                # App settings
│   ├── widgets/                     # Reusable widgets
│   ├── utils/                       # Utility functions
│   └── constants/                   # App constants
├── assets/                          # Static assets
│   ├── images/                      # App images & logos
│   ├── animations/                  # Lottie animations
│   └── fonts/                       # Custom fonts
├── android/                         # Android configuration
├── ios/                            # iOS configuration
├── web/                            # Web configuration
└── pubspec.yaml                    # Flutter dependencies

🔧 Development

Backend Development

API Documentation: Available at http://localhost:8080/docs (Swagger UI)

Database Migrations:

alembic revision --autogenerate -m "description"
alembic upgrade head

Frontend Development

Hot Reload: Enabled automatically in development mode
Build for Development:
```
flutter run
```

Build for Production:

flutter build apk --release           # Android APK
flutter build ios --release           # iOS
flutter build web --release           # Web

🛡️ Security Features

JWT Authentication with refresh tokens
Password Hashing using bcrypt
Input Validation with Pydantic
CORS Configuration for web security
SQL Injection Protection via SQLAlchemy ORM
File Upload Validation for images
Environment Variables for sensitive data

📊 Performance Optimizations

Database Indexing on frequently queried fields
Redis Caching for session management
Image Compression and lazy loading
API Response Pagination
WebSocket Connection Pooling
Flutter Widget Optimization
Code Splitting for web builds

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes following our coding standards
Write tests for new functionality
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Coding Standards

Follow Flutter/Dart style guidelines
Follow PEP 8 for Python code
Write meaningful commit messages
Include tests for new features
Update documentation as needed
Use conventional commits format

👥 Contributors

🚀 Project Team

_{H.M. Mehedi Hasan}
🐛 💻 📖
Full-Stack Developer

_{Abu Bakar Siddique}
💻 🎨 📱
Frontend Developer

_{Ahil Islam Aurnob}
💻 🗃️ ⚡
Backend Developer

_{S M Shamiun Ferdous}
💻 🧪 📊
QA & Analytics

Contact Information

H.M. Mehedi Hasan: hasanmehedi26696@gmail.com
Abu Bakar Siddique: bojackabs@gmail.com
Ahil Islam Aurnob: aheelislam03@gmail.com
S M Shamiun Ferdous: shamiunferdous1234@gmail.com

📄 License

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

🆘 Support & Documentation

Getting Help

📧 Email Support: contact@volunsphere.com

Useful Links

🎯 Future Roadmap

Advanced Analytics Dashboard with charts and insights
Multi-language Support (Bengali, Spanish, French)
Offline Mode capabilities with data synchronization
Social Media Integration (Facebook, Twitter, LinkedIn)
Advanced Search with AI-powered recommendations
Gamification Features with badges and achievements
Event Categories and advanced filtering
Mobile App Widgets for quick actions

Made with ❤️ for the volunteer community

Empowering communities through technology and volunteering

⬆ Back to Top | 📑 Table of Contents

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
Procfile		Procfile
README.md		README.md
build.sh		build.sh
check_structure.py		check_structure.py
nixpacks.toml		nixpacks.toml
railway.json		railway.json
requirements.txt		requirements.txt
runtime.txt		runtime.txt
start.sh		start.sh
startup.sh		startup.sh

Abs-Futy7/VolunSphere

Folders and files

Latest commit

History

Repository files navigation