A full-stack application that allows daily commuters to earn money by delivering packages on their way to their destination. Customers can create delivery requests, and commuters can accept and complete deliveries while earning money.
- Backend: Java Spring Boot 3.2.0 (REST API)
- Frontend: React.js 18.2.0
- Database: PostgreSQL
- Authentication: JWT (JSON Web Tokens)
- Maps: Leaflet + OpenStreetMap
- MVC Architecture (Controllers → Services → Repositories)
- JWT Authentication with Spring Security
- Role-based Access Control (CUSTOMER, COMMUTER, ADMIN)
- Design Patterns: Strategy, Template Method, Observer, Factory
- Dynamic Pricing: Base price + per-km + surge pricing based on demand
- Event-driven notifications
- Global exception handling
- Input validation
- User authentication (Login/Register)
- Customer dashboard (create deliveries, view maps, price breakdown)
- Commuter dashboard (accept deliveries, update status)
- Real-time notifications (pop-ups + sidebar)
- Interactive maps with route visualization
- Distance and ETA calculations
- Java 17+
- Maven 3.6+
- Node.js 14+
- PostgreSQL 12+ (or Docker)
# Create database
psql -U <your_username> postgres
CREATE DATABASE crowd_delivery_db;
CREATE USER crowd_user WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE crowd_delivery_db TO crowd_user;
\qOr use Docker:
docker run --name postgres-crowd-delivery \
-e POSTGRES_PASSWORD=password \
-e POSTGRES_USER=crowd_user \
-e POSTGRES_DB=crowd_delivery_db \
-p 5432:5432 -d postgres:14cd crowdsourced_delivery
# Update database credentials in src/main/resources/application.yml if needed
# Run application
mvn clean install
mvn spring-boot:runBackend runs on http://localhost:8080
cd frontend
npm install
npm startFrontend runs on http://localhost:3000
Note: Tables (users, deliveries, notifications) are created automatically by JPA on first run.
crowdsourced_delivery/
├── src/main/java/com/crowddelivery/
│ ├── controller/ # REST Controllers
│ ├── service/ # Business Logic (includes design patterns)
│ ├── repository/ # JPA Repositories
│ ├── entity/ # JPA Entities (User, Delivery, Notification)
│ ├── dto/ # Data Transfer Objects
│ ├── security/ # JWT & Security
│ ├── event/ # Event classes (Observer pattern)
│ ├── listener/ # Event listeners
│ └── util/ # Utilities (DistanceCalculator)
├── frontend/
│ ├── src/
│ │ ├── components/ # React components (maps, notifications)
│ │ ├── pages/ # Page components
│ │ ├── services/ # API services
│ │ └── hooks/ # Custom hooks
└── pom.xml
3 tables created automatically:
- users: id, email, password, name, phone, role, created_at
- deliveries: id, customer_id, commuter_id, pickup/drop locations & coordinates, price, status, timestamps
- notifications: id, user_id, delivery_id, title, message, type, is_read, created_at
POST /api/auth/register- Register userPOST /api/auth/login- Login and get JWT token
POST /api/customer/deliveries- Create delivery (price auto-calculated)GET /api/customer/deliveries- Get my deliveriesGET /api/customer/deliveries/calculate-price- Calculate price before creationPUT /api/customer/deliveries/{id}/status?status=CANCELLED- Cancel delivery
GET /api/commuter/deliveries/open- View open deliveriesPOST /api/commuter/deliveries/{id}/accept- Accept deliveryGET /api/commuter/deliveries- Get my deliveriesPUT /api/commuter/deliveries/{id}/status?status=PICKED_UP- Update statusPUT /api/commuter/deliveries/{id}/status?status=DELIVERED- Mark delivered
GET /api/notifications- Get all notificationsGET /api/notifications/unread- Get unread notificationsGET /api/notifications/count- Get unread countPUT /api/notifications/{id}/read- Mark as read
Base Pricing:
- Base Price: $5.00
- Price per km: $2.50/km
- Formula:
Price = Base + (Distance × $2.50)
Surge Pricing (based on open deliveries):
- 0-9 deliveries: No surge (1.0x)
- 10-19 deliveries: Low surge (1.2x = +20%)
- 20-29 deliveries: Medium surge (1.5x = +50%)
- 30+ deliveries: High surge (2.0x = +100%)
Final Price: (Base + Distance Price) × Surge Multiplier
Prices are automatically calculated when coordinates are provided.
- Strategy Pattern:
MatchingStrategyinterface with implementations - Template Method Pattern:
DeliveryService.updateDeliveryStatus()workflow - Observer Pattern: Event-driven notifications (
DeliveryCreatedEvent,DeliveryStatusChangedEvent) - Factory Pattern: JWT token generation in
JwtTokenProvider
Customer:
- Register/Login → Create delivery → System calculates price → View deliveries → Receive notifications
Commuter:
- Register/Login → View open deliveries → Accept delivery → Update status (PICKED_UP → DELIVERED) → Receive notifications
- JWT tokens required for all endpoints except
/api/auth/** - Tokens expire after 24 hours
- Include in header:
Authorization: Bearer <token> - Passwords hashed with BCrypt
Backend (src/main/resources/application.yml):
spring:
datasource:
url: jdbc:postgresql://localhost:5432/crowd_delivery_db
username: crowd_user
password: password
jpa:
hibernate:
ddl-auto: update
server:
port: 8080
jwt:
secret: yourSecretKeyShouldBeAtLeast256BitsLongForHS512AlgorithmMakeItLongerForProduction
expiration: 86400000 # 24 hoursFrontend (frontend/src/services/api.js):
- API base URL:
http://localhost:8080/api
# Register
curl -X POST http://localhost:8080/api/auth/register \
-H "Content-Type: application/json" \
-d '{"name":"John","email":"john@test.com","password":"pass123","role":"CUSTOMER"}'
# Login
curl -X POST http://localhost:8080/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"john@test.com","password":"pass123"}'- Email notifications
- Real-time location tracking
- Rating system
- Payment integration
- Admin dashboard
- Mobile app
Open source for educational purposes.
Built with ❤️ using Spring Boot and React