HopDrop

HopDrop is a modern, peer-to-peer logistics and package delivery platform designed to connect Senders of packages with Travellers who are heading in the same direction. By leveraging shared journeys, HopDrop ensures faster, cost-effective, and secure deliveries while providing a seamless user experience.

✨ Features

• Role-Based Workflows: Separate dashboards and flows for Senders, Travellers, and Receivers.
• Interactive UI: A stunning Glassmorphic interface with dynamic backgrounds including Space and Sunset Light Mode themes (powered by Three.js).
• Secure Authentication: Integrated Firebase authentication supporting both Email/Password and Google OAuth 2.0.
• Smart Addressing: Open Source Maps autocomplete integration for accurate pickup and drop-off coordination.
• OTP Verification: Secure package handover and delivery confirmation using OTPs, ensuring only the right traveller and right receiver interact with the package.
• Package Tracking: End-to-end tracking of the package delivery lifecycle.
• Payment Split: Embedded payment workflows ensuring correct fee distribution (80% to the traveller, 20% platform fee).

🛠️ Technology Stack

Frontend

• HTML/CSS/JavaScript: Core web technologies with Vanilla JavaScript.
• Three.js: Used for immersive environment background animations.
• Firebase Auth: User identity management.
• Open Source Maps API: Address verification and autocomplete.

Backend

• Python / FastAPI: Robust backend API handling user management, delivery logic, and payments.
• Firebase Firestore: NoSQL database for real-time order and user state tracking.

🚀 Setup & Installation

Prerequisites

• Python 3.8+
• Node.js (Optional, if using a local server for the frontend)
• Firebase Project setup with Authentication and Firestore enabled.

Backend Setup

1. Navigate to the backend directory:

   cd backend

2. Create and activate a virtual environment (recommended):

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

3. Install the required dependencies:

   pip install -r requirements.txt

   (Note: ensure you have FastAPI, Uvicorn, Firebase Admin, etc. installed)
4. Set up your Firebase service account credentials (contact the repo admin if you don't have this or configure your environment variables to point to your serviceAccountKey.json).
5. Run the FastAPI development server:

   uvicorn app:app --reload

Frontend Setup

1. The frontend consists of static HTML files in the frontend folder.
2. Open the frontend folder:

   cd frontend

3. You can serve the static files using a simple HTTP server. For example:

   python -m http.server 8000
   # OR using npx
   npx serve .

4. Access the web app in your browser at http://localhost:8000.

📂 Project Structure

HF26-01/
├── backend/
│ ├── app.py # Main FastAPI application
│ ├── auth.py # Backend authentication endpoints
│ ├── database.py # Firestore database logic and connection
│ ├── delivery_system.py # Core business logic for matching and tracking deliveries
│ ├── ...
├── frontend/
│ ├── index.html # Landing page / Start flow
│ ├── sender.html # Dashboard for senders creating packages
│ ├── traveller.html # Dashboard for travellers offering routes
│ ├── receiver.html # Dashboard for package verification for receivers
│ ├── app.js # Global frontend logic
│ ├── auth.js # Frontend authentication handlers
│ ├── autocomplete.js # Open Source Maps address integration
│ ├── three-bg.js # 3D canvas backgrounds
│ ├── styles.css # Glassmorphic and responsive styling
│ ├── ...
└── README.md

🤝 Contributing

1. Fork the repository
2. Create a new branch (git checkout -b feature-foo)
3. Make your changes and commit them (git commit -m 'Add feature-foo')
4. Push your branch (git push origin feature-foo)
5. Open a Pull Request

📄 License

This project is proprietary and built for logistics management. All rights reserved.