GiveSync - Share Kindness, Grow Hope

GiveSync is a social responsibility platform that intelligently matches those in need with donors using Google Gemini AI, ChromaDB Vector Database, and custom anti-abuse algorithms to ensure fair and accurate distribution.

This project was developed as an MVP (Minimum Viable Product) for the DEV.to hackathon.

The Problem It Solves

The two biggest problems encountered in charity platforms are:

1. Semantic Matching Problem: A traditional keyword-based search engine might not match a donation of "winter coat for a 2-year-old girl" with a request for "clothes for cold weather".
2. Abuse (Unfair Distribution): The same individuals constantly receiving aid in the same category (e.g., electronics) by using different names or keywords, thereby depriving other people in need.

Our Solution (Vector Search + LLM Judge)

1. Semantic Vector Embeddings (Gemini + ChromaDB): Users describe the item they are donating or need in their own words (natural language). The backend uses Google's gemini-embedding-2 to convert this text into a mathematical vector and stores it in ChromaDB.
2. Top-K Search & LLM Matchmaking: When a request is made, the system finds the top 5 most similar items from ChromaDB. These candidates (along with the requester's geographic location) are sent to gemini-3.1-flash-lite. Gemini acts as an expert judge, prioritizing same-city matches and selecting the absolute best candidate.
3. Abuse Prevention: When a person in need makes a request, the algorithm checks the database (SQLite). If this person (based on their contact address) has previously received aid in the same category, their request is denied with a "403 Forbidden" status. This guarantees that aid is spread out and distributed fairly.

Technologies Used

• Backend: FastAPI, Python, SQLite, SQLAlchemy
• Vector Database: ChromaDB
• AI: Google Generative AI (gemini-embedding-2, gemini-3.1-flash-lite)
• Frontend: React.js, Vite, Tailwind CSS, Axios

How to Run

The project consists of two main directories: backend and frontend.

1. Backend Setup

cd backend
python3 -m venv venv
source venv/bin/activate
pip install fastapi sqlalchemy uvicorn python-dotenv google-generativeai pydantic chromadb

# Make sure to add your own Gemini API key (GEMINI_API_KEY) to the .env file!
uvicorn main:app --reload

The server will run on port http://127.0.0.1:8000.

You can test the vector matchmaking logic by running python test_vector_match.py inside the backend directory.

2. Frontend Setup

cd frontend
npm install
npm run dev

You can access the user interface at http://localhost:5173 (or the port provided by Vite).