A web platform for connecting surplus food from businesses with charities and individuals who need it, helping coordinate discovery, requests, communication, and pickup.
Surplus Share is a Flask and PostgreSQL application built around a simple workflow:
List surplus food
↓
Discover nearby availability
↓
Submit a request
↓
Coordinate pickup
↓
Complete the transfer
The application supports both sides of the exchange. Donors can publish available food, while recipients and charities can discover listings, request them, communicate with donors, and coordinate pickup.
- Donor, recipient, and charity accounts
- Food listings with quantity, category, description, and expiry
- Location-based proximity matching
- Interactive map using Leaflet and OpenStreetMap
- Request and approval workflow
- Pickup scheduling and completion tracking
- In-app conversations and messaging
- PostgreSQL persistence through SQLAlchemy
- Password hashing with Werkzeug
- Geocoding through OpenStreetMap Nominatim
| Layer | Technology |
|---|---|
| Backend | Python, Flask |
| ORM | Flask-SQLAlchemy |
| Database | PostgreSQL |
| Frontend | HTML, CSS, JavaScript, Jinja |
| Mapping | Leaflet, OpenStreetMap |
| Geocoding | Nominatim |
| Deployment server | Gunicorn |
SurplusShare/
├── app.py
├── seed.py
├── requirements.txt
├── .env.example
├── SECURITY.md
├── docs/
│ └── architecture.md
├── static/
│ ├── css/
│ ├── js/
│ └── img/
└── templates/
git clone https://github.com/MohammedYaser1/SurplusShare.git
cd SurplusShareWindows:
python -m venv .venv
.venv\Scripts\activatemacOS / Linux:
python3 -m venv .venv
source .venv/bin/activatepip install -r requirements.txtCopy .env.example to .env and set:
DATABASE_URL=postgresql://user:password@localhost:5432/surplus_share
SECRET_KEY=replace-with-a-long-random-secretUse a real PostgreSQL database for the application. Do not commit the resulting .env file.
The application creates its tables when started directly:
python app.pyFor demo data, run:
python seed.pyThe seed script resets the application tables before inserting sample users and listings. Use it only with a development/demo database.
python app.pyOpen the local address printed by Flask in your browser.
For a production-style server:
gunicorn app:appThe seed script creates sample donor, charity, and recipient accounts for local demonstrations. Credentials are defined in seed.py and are intended only for development/demo use.
See docs/architecture.md for the request flow, core workflows, and repository layout.
Surplus Share is a completed collaborative project demonstrating a full-stack workflow for surplus-food discovery and pickup coordination.
Developed collaboratively by Mohammed Yaser and Abdullah Ghouri.
This repository contains the application source and supporting assets. Production credentials, deployment secrets, and private service-account files should be supplied through the hosting environment rather than stored in Git.