Zariya

Zariya is a donation logistics platform connecting individual donors directly with verified NGOs across Pakistan.

• Every donation gets a tracked journey, from submission to confirmed pickup
• NGOs publish exactly what they need, so donations go where they're actually useful
• A full status pipeline keeps both sides informed, with no black-box guessing

Live demo: zariya-s2xm.onrender.com

---

Core Concept

Three roles, one pipeline:

• Donors — browse verified NGOs, see live needs, submit donations for pickup
• NGOs — apply for verification, publish needs, manage incoming donations
• Admins — review applications, resolve complaints, reassign donations, monitor analytics

Every donation moves through one auditable status flow:

pending → accepted → received
   │
   ├──→ rejected   (NGO declines, with a reason)
   └──→ cancelled  (donor withdraws before acceptance)

Each donation gets a human-readable tracking ID (ZR-0001, ZR-0002, ...) donors can look up anytime.

---

Features

Donors

• Browse and filter verified NGOs by city, zone, and accepted category
• View each NGO's live, itemized needs before donating
• Submit donations with a real, validated pickup address (house/street/area/city)
• Save incomplete donations as drafts and resume later
• Track any donation by its tracking ID
• Repeat a past donation or reuse a saved donation plan in one click
• Rate and review NGOs after pickup is confirmed
• File complaints tied to a specific donation

NGOs

• Apply for platform verification before going live
• Publish and retire specific item needs with required quantities
• Accept, decline, or mark donations as received
• Set a capacity limit on concurrently accepted donations
• Leave a thank-you note on completed donations
• Edit organization profile, service area, and accepted categories

Admins

• Review and approve/reject incoming NGO applications
• Reassign donations, override rejections, view every status bucket
• Resolve donor and NGO complaints
• View category demand trends, monthly volume, and per-NGO fulfillment rates

Platform-wide

• Idle session timeout and server-instance session binding
• Rate-limited login endpoints
• Server-side sanitization on all free-text fields
• Automatic email notifications at every stage of a donation
• Seeded directory of real, verified NGOs across major Pakistani cities

---

Tech Stack

• Backend: Flask, application factory pattern
• ORM: Flask-SQLAlchemy
• Database: PostgreSQL in production, SQLite for local development
• Auth: Werkzeug password hashing, server-side sessions
• Email: Flask-Mail over SMTP (Brevo)
• Rate limiting: Flask-Limiter
• Frontend: Jinja2 templates, vanilla CSS/JS
• WSGI server: Gunicorn

---

Project Structure

Zariya/
├── backend/
│   ├── app.py              # Application factory, all routes, migrations, seed data
│   ├── models.py           # SQLAlchemy models (User, NGO, Donation, etc.)
│   ├── config.py           # Environment-driven configuration
│   └── extensions.py       # Shared extension instances (db)
├── frontend/
│   ├── templates/          # Jinja2 templates, incl. templates/emails/
│   └── static/             # CSS, JS, images
├── run.py                  # Entry point (loads .env, creates app)
├── requirements.txt
├── Procfile                 # gunicorn run:app
└── .env.example              # Environment variable template

---

Data Model

• User — donors, NGO representatives, and admins, role-differentiated
• NGO — verified organizations: location, accepted categories, capacity
• NGOApplication — pending NGO signups awaiting admin review
• NGONeed — an NGO's published item requirement, with fulfillment tracking
• Donation — the core transaction: item, status, pickup details, post-completion feedback
• DonationDraft — a donor's in-progress, unsubmitted donation
• DonorAlert — a saved donation plan a donor can reuse
• Complaint — user-filed issues, optionally linked to a donation
• PasswordResetToken — time-limited, single-use password reset tokens

---

Getting Started

Prerequisites

• Python 3.11+
• pip

Local Setup

git clone https://github.com/UroojFatima-052/Zariya.git
cd Zariya

python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate

pip install -r requirements.txt

cp .env.example .env
# fill in .env — see Environment Variables below

• With DATABASE_URL left blank, the app runs on a local SQLite file (zariya.db), auto-created on first run
• Start the app with:

python run.py

• Available at http://localhost:5000
• A default admin account is seeded automatically from ADMIN_EMAIL / ADMIN_PASSWORD in .env

---

Environment Variables

Copy .env.example to .env and fill in your own values. Never commit .env — it's already excluded in .gitignore.

• SECRET_KEY — signs Flask sessions; use a long, random string
• DATABASE_URL — blank for local SQLite, or a PostgreSQL connection string in production
• ADMIN_EMAIL / ADMIN_PASSWORD — credentials for the auto-seeded admin account
• MAIL_SERVER, MAIL_PORT, MAIL_USE_TLS — SMTP connection settings
• MAIL_USERNAME, MAIL_PASSWORD — SMTP credentials (Brevo free tier: 300 emails/day)
• MAIL_DEFAULT_SENDER — sender name and address for outgoing email

---

Security Notes

• Passwords are hashed with Werkzeug's generate_password_hash — never stored in plaintext
• Sessions are invalidated on server restart via a per-boot instance token
• Authenticated pages are served with no-store cache headers to prevent back-button exposure after logout
• Login endpoints are rate-limited per IP to reduce brute-force risk
• Password reset uses single-use, time-limited tokens; "forgot password" always returns a generic success message to prevent email enumeration

---

License

MIT © Urooj Fatima

Author

Built by Urooj Fatima - LinkedIn · Email