Charity Donation Platform (SPROJ-P08)

A full-stack Donation mobile Platform connecting donors with verified charity organizations. Built as our Final Year Project for the BS Computer Science program at LUMS, this platform empowers charities to post causes and donors to contribute securely. It includes user roles (Admin, Charity, Donor), real-time updates, media uploads, analytics, and AI-driven recommendations.

---

🚀 Project Overview

• Donors browse and search causes, donate, and track their impact.
• Charities register, post causes with media, and engage donors.
• Admins verify charities, view analytics, and manage users.

✅ Key Functionalities

• Secure authentication with JWT
• Charity approval workflows (Admin dashboard)
• Posting and searching causes (media uploads included)
• Real-time donor notifications
• AI-powered donor recommendations
• Guest browsing and access control
• Donor achievements and badge system
• Payment gateway integration

---

⚙️ Tech Stack

Component	Technology
Frontend	Flutter
Backend	Django REST Framework
Database	PostgreSQL (Dockerized with pgvector)
Asynchronous Tasks	Celery + Redis
Media Storage	Cloudinary
Authentication	JWT
Deployment	Railway (Backend)
AI Embeddings	OpenAI Embeddings

---

🗓️ Project Timeline & Progress

Sprint	Status
Sprint 1	✅ Completed
Sprint 2	✅ Completed
Sprint 3	✅ Completed
Sprint 4	✅ Completed

---

👨‍💻 Team Members

• Shahzaib Iqbal
• Ahmed Jan
• Aleesha Usman
• Abdullah Saleem

---

🔨 How to Set Up the Project Locally

Backend Setup (Django + Docker Compose)

We use Docker Compose to orchestrate the backend services including Django, PostgreSQL, Redis, Celery workers, and Celery Beat.

1️⃣ Prerequisites

• Docker and Docker Compose installed
• Python 3.x (for virtual environment)
• Flutter SDK (for frontend)

2️⃣ Clone the Repository

git clone https://github.com/SPROJ-P08/P08/
cd P08/final-deliverables/code/

3️⃣ Create Env File

You need to create an .env file inside the final-deliverables/code/backend/ folder. This file will store environment variables required by the Django backend, Docker Compose, and other services (e.g., Celery workers).

This project requires the following environment variables to be set:

Variable Name	Description
DATABASE_URL	Connection string for your PostgreSQL database. In Docker Compose, it typically points to the db service. Example: postgresql://postgres:postgres@db:5432/postgres
DEBUG	Set to True for development and False for production. Enables or disables Django's debug mode.
SECRET_KEY	A strong secret key used by Django for security features like session management and CSRF protection. Make sure to generate a unique and secure key.
GMAIL_PASS	Password (or App Password) for the Gmail account used to send emails from the backend. Tip: Use App Passwords for better security.
OPENAI_API_KEY	Your OpenAI API key to enable AI-powered recommendation features in the backend.
CELERY_BROKER_URL	The URL for the Celery broker, which is Redis in this case. Example: redis://redis:6379/0

Sample .env File

DEBUG=True
SECRET_KEY=your_django_secret_key_here

DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres

# Email credentials (Gmail)
GMAIL_PASS=your_gmail_app_password_here

# OpenAI API Key (for AI features)
OPENAI_API_KEY=your_openai_api_key_here

# Celery Broker URL (Redis)
CELERY_BROKER_URL=redis://redis:6379/0

4️⃣ Start the Services

backend Setup

• Navigate to the backend folder.

cd final-deliverables/code/backend/

• Activate the virtual environment.

python -m venv venv
source venv/bin/activate

• Run Docker Compose.

docker compose up --build

This will:

1. Start PostgreSQL (with pgvector).
2. Start Redis (for Celery).
3. Run Django (exposed on localhost:8000).
4. Start Celery worker and Celery Beat.
5. automatic Database Setup.
6. The entrypoint.sh will run Django migrations (makemigrations & migrate)and start the Django development server on 0.0.0.0:8000.

Frontend Setup

• Navigate to the frontend directory.

cd final-deliverables/code/frontend/

• Install Flutter dependencies.

flutter pub get

• Run the app on an emulator or connected device.

flutter run

Deployed Server Link (Demo) Backend Server (Railway): https://p08-code-repo-production.up.railway.app/

Example API endpoint (returns charities):

GET /charities

🗑️ Cleanup & Teardown

To stop and remove all Docker services:

docker compose down

---