Buy4Good

A mobile app that turns everyday purchases into charitable donations through affiliate partnerships
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
   • Features
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Project Structure
5. API Documentation
6. Roadmap
7. Contributing
8. License
9. Contact
10. Acknowledgments

About The Project

Buy4Good is a comprehensive mobile application that seamlessly integrates charitable giving into everyday shopping. Users can connect their bank accounts, shop at partner merchants, and automatically donate a percentage of their purchases to their chosen charities. The app features real-time transaction tracking, donation analytics, and a curated selection of verified nonprofit organizations.

Key Benefits:

• Effortless Giving: Turn purchases into donations automatically
• Transparency: Track exactly where your money goes with detailed analytics
• Partner Network: Shop at major brands and retailers through affiliate partnerships
• Impact Visualization: See your collective impact with interactive dashboards
• Secure: Bank-grade security with Plaid integration for transaction monitoring

(back to top)

Built With

Frontend (Mobile App):

• 
• 
• 
• 
• 

Backend (API Server):

• 
• 
• 

External Integrations:

• - Bank account connection and transaction monitoring
• Pledge.to API - Nonprofit organization data and donation processing
• Google OAuth - User authentication

(back to top)

Features

Mobile App Features:

• 🔐 Secure Authentication - Google OAuth integration
• 🏦 Bank Integration - Connect spending cards via Plaid
• 🛒 Merchant Shopping - Browse and shop at partner brands
• 💝 Charity Selection - Choose from verified nonprofit organizations
• 📊 Donation Dashboard - Track donation history and impact
• 📱 Real-time Activity - See recent donations and transactions
• 🎯 Cause Filtering - Find charities by cause categories
• 📈 Analytics - Visualize donation breakdown by cause

Backend API Features:

• 🌐 RESTful API - Comprehensive endpoints for all app functionality
• 💸 Donation Processing - Handle charitable donations via Pledge.to
• 🏢 Organization Management - Fetch and manage nonprofit data
• 🔄 Transaction Simulation - Mock affiliate network transactions
• 🪝 Webhook Handling - Process affiliate network callbacks
• 🏥 Health Monitoring - Comprehensive health checks
• 📚 Auto Documentation - Interactive API docs with Swagger

(back to top)

Getting Started

This project consists of two main components: a React Native mobile app (frontend) and a FastAPI server (backend). Follow the instructions below to set up both components locally.

Prerequisites

For Frontend:

• Node.js (v18 or higher)
• npm or yarn
• Expo CLI
• iOS Simulator (Mac) or Android Studio

For Backend:

• Python 3.8+
• pip (Python package manager)

API Keys Required:

• Plaid API keys (sandbox and production)
• Pledge.to API key
• Supabase project credentials
• Google OAuth credentials

Installation

1. Clone the Repository

git clone https://github.com/AndrewCheung360/Buy4Good.git
cd Buy4Good

2. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your API keys:
# PLEDGE_TO_API_KEY=your_production_api_key_here
# PLEDGE_TO_SANDBOX_API_KEY=your_sandbox_api_key_here
# USE_SANDBOX_FOR_DONATIONS=true

# Start the server
python main.py

3. Frontend Setup

cd frontend/Buy4Good

# Install dependencies
npm install

# Configure environment variables
# Create .env file with:
# EXPO_PUBLIC_PLAID_CLIENT_ID=your_plaid_client_id
# EXPO_PUBLIC_PLEDGE_API_TOKEN=your_pledge_api_token
# EXPO_PUBLIC_SUPABASE_URL=your_supabase_url
# EXPO_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# Start the development server
npx expo start

4. Database Setup (Supabase)

1. Create a new Supabase project
2. Run the SQL migrations in database/migrations/
3. Configure Row Level Security (RLS) policies
4. Update your .env with Supabase credentials

(back to top)

Usage

Mobile App Usage

1. Sign Up/Login: Authenticate using Google OAuth
2. Connect Bank Account: Use Plaid to securely link your spending card
3. Browse Charities: Explore nonprofit organizations by cause category
4. Select Favorites: Choose charities to support with your purchases
5. Shop: Browse partner merchants and make purchases
6. Track Impact: View your donation history and analytics on the dashboard

API Usage

The backend provides a comprehensive REST API for all app functionality:

// Example: Create a donation
const response = await fetch("http://localhost:8000/api/v1/donations", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    first_name: "John",
    last_name: "Doe",
    amount: "25.00",
    organization_id: "3685b542-61d5-45da-9580-162dca725966",
  }),
});

For complete API documentation, visit the interactive docs at http://localhost:8000/docs when running the backend.

(back to top)

Project Structure

Buy4Good/
├── frontend/Buy4Good/          # React Native mobile app
│   ├── app/                    # App screens and navigation
│   │   ├── (tabs)/            # Tab-based navigation screens
│   │   ├── components/        # Reusable UI components
│   │   └── webview/           # Merchant webview screens
│   ├── assets/                # Images and static assets
│   ├── context/               # React context providers
│   ├── data/                  # Mock data and types
│   ├── utils/                 # Utility functions
│   └── types/                 # TypeScript type definitions
├── backend/                   # FastAPI server
│   ├── routes/                # API route modules
│   │   ├── donations.py       # Donation endpoints
│   │   ├── organizations.py   # Organization endpoints
│   │   ├── transactions.py    # Transaction simulation
│   │   └── health.py          # Health check endpoints
│   ├── services/              # Business logic services
│   │   └── pledge_client.py   # Pledge.to API client
│   ├── models.py              # Pydantic data models
│   ├── config.py              # Configuration settings
│   └── main.py                # FastAPI application entry
└── database/                  # Database schema and migrations
    └── migrations/            # SQL migration files

(back to top)

API Documentation

The backend provides comprehensive API documentation through FastAPI's automatic documentation generation:

• Interactive API Docs (Swagger UI): http://localhost:8000/docs
• Alternative Docs (ReDoc): http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json

Key Endpoints

Endpoint	Method	Description
/api/v1/donations	POST	Create a new donation
/api/v1/organizations	GET	List nonprofit organizations
/api/v1/organizations/{id}	GET	Get organization details
/api/v1/simulate-transaction	POST	Simulate affiliate transaction
/api/v1/webhook	POST	Handle affiliate webhooks
/health	GET	Comprehensive health check

(back to top)

Roadmap

• Phase 1: Core Foundation

  • User authentication with Google OAuth
  • Bank account integration via Plaid
  • Basic charity browsing and selection
  • Donation tracking dashboard

• Phase 2: Enhanced Shopping Experience

  • Real-time affiliate transaction processing
  • Push notifications for donations
  • Advanced analytics and reporting
  • Social sharing features

• Phase 3: Scale & Optimization

  • Additional payment method support
  • Corporate partnership program
  • Advanced charity recommendation engine
  • Multi-language support

• Phase 4: Platform Expansion

  • Web application version
  • Admin dashboard for nonprofits
  • API for third-party integrations
  • White-label solutions

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

Development Guidelines

1. Frontend: Follow React Native and TypeScript best practices
2. Backend: Adhere to FastAPI conventions and Python PEP 8
3. Testing: Write tests for new features and bug fixes
4. Documentation: Update README and API docs for any changes

Contribution Process

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Team

Developers

Andrew Cheung - [email protected]

Jason Mun - [email protected]

Dora Weng - [email protected]

Designers

Vicky Wang - [email protected]

Joanna Chen - [email protected]

(back to top)

Acknowledgments

• Expo - For the excellent React Native development platform
• FastAPI - For the high-performance Python web framework
• Plaid - For secure bank account integration
• Pledge.to - For nonprofit organization data and donation processing
• Supabase - For the backend-as-a-service platform
• Best-README-Template - For this amazing README template

(back to top)